Enable NGINX logs

Overview

F5 NGINXaaS for AWS integrates with Amazon CloudWatch Logs to collect NGINX error and access logs.

When you enable log export, NGINXaaS writes NGINX logs to a CloudWatch Logs log group (the Log Group) in a log stream named logs.

Before you begin

• Configure a Role ARN in the Identity section of your deployment. NGINXaaS uses this IAM role to export logs to CloudWatch. See Identity and access management for how to create the role and attach the Policy for CloudWatch Logs.

• Grant the IAM role the permissions required to export logs:

  • logs:CreateLogStream and logs:PutLogEvents: required for NGINXaaS to write logs to the log group.
  • logs:CreateLogGroup: required only if you want NGINXaaS to create the log group for you. If you pre-create the log group yourself, you can omit this permission.

  See AWS’s documentation on controlling access to CloudWatch Logs with IAM for more information.

• To view logs in the CloudWatch console, your own AWS identity needs read access such as logs:GetLogEvents and logs:FilterLogEvents. This is separate from the deployment’s IAM role.

Set up error logs

NGINX error logs are disabled by default. You can enable error logs by adding error_log directives to your NGINX configuration to specify the location of the logs and formats. The log path should always be configured to be inside /var/log/nginx.

While you should configure log files in the /var/log/nginx directory, you can change the filename and severity level. For example, the following line in the NGINX configuration sends errors to the nginx-error.log file, and limits messages to a severity level of emerg:

error_log /var/log/nginx/nginx-error.log emerg;

Alternatively, you can disable error logs completely with the following line:

error_log /dev/null;

To learn more about how to specify error_log in different configuration levels, see the documentation of the error_log directive.

Set up access logs

NGINX access logs are disabled by default. You can enable access logs by adding access_log directives to your NGINX configuration to specify the location of the logs and formats. The log path should always be configured to be inside /var/log/nginx.

http {
	log_format myfmt '$remote_addr - $remote_user [$time_local] '
						   '"$request" $status $body_bytes_sent '
						   '"$http_referer" "$http_user_agent" "$gzip_ratio"';

	access_log /var/log/nginx/nginx-access.log myfmt;
	# ...
}

The $time_local variable includes the date and time for each log. It helps with ordering logs after export.

To explicitly disable access logs, apply the following config:

http {
	access_log off;
}

or

http {
	access_log /dev/null;
}

To learn more about how to specify access_log in different configuration levels and their effect, see access_log

Warning

Keep NGINX logs in the /var/log/nginx directory. Otherwise, you may lose data from your logs.

Export NGINX logs to CloudWatch

To enable exporting logs, turn on the Export Logs to CloudWatch toggle when creating or updating a deployment. To create a deployment, see our documentation on creating an NGINXaaS deployment for a step-by-step guide. To update an existing deployment, in the NGINXaaS console,

1. On the navigation menu, select Deployments.
2. Select the deployment you want to update and select Edit.
3. In the Identity section, make sure the Role ARN field is populated with an IAM role that has the required permissions. Log export fails without it.
4. In the Observability section, turn on the Export Logs to CloudWatch toggle.
5. In the Log Group Name field, enter the name of the CloudWatch Logs log group you want to receive exported logs. If you leave this field at its default, NGINXaaS uses a log group named after the deployment object ID.
6. Select Update.

View NGINX logs in Amazon CloudWatch Logs

In the AWS Management Console,

1. Go to the CloudWatch console and select Logs > Log Management > Log groups.
2. In the Filter log groups field, enter the name of your log group to find it quickly.
3. Select your log group and open the logs log stream, or use Logs Insights to query across streams.

Refer to the AWS’s CloudWatch Logs Insights documentation to learn how you can create queries.

Within the log group, NGINX access and error logs are written to a log stream named logs, which you can use to separate NGINX logs from the rest of your log group’s streams. You can also filter based on the following fields using a CloudWatch Logs Insights filter or stats query, for example,

• filename
• nginxaas_deployment_location
• nginxaas_deployment_name
• nginxaas_deployment_object_id
• nginxaas_namespace
• nginxaas_organization_object_id

For example, to query for a deployment’s /var/log/nginx/access.log entries:

1. In the CloudWatch console, select Logs > Logs Insights.
2. Select the log group for your deployment (default value is the deployment object ID).
3. In the query editor, enter the following query to filter for access log entries

fields @timestamp, @message
| filter @logStream = "logs" and attributes.filename = "/var/log/nginx/access.log"
| sort @timestamp desc

The same procedure can be used to query via the newer Log Analytics feature in the CloudWatch console. See AWS’s documentation on Log Analytics for more information.

Disable NGINX log export to CloudWatch

To stop exporting logs, update your NGINXaaS deployment to turn off the log export toggle. To update the deployment, in the NGINXaaS console,

1. On the navigation menu, select Deployments.
2. Select the deployment you want to update and select Edit.
3. In the Observability section, turn off the Export Logs to CloudWatch toggle.
4. Select Update.

Troubleshooting

If Amazon CloudWatch Logs is not showing any logs, check for Failed Log Export to CloudWatch events from your NGINXaaS deployment.

In the NGINXaaS console:

1. On the navigation menu, select Events.
2. Select Add Filter.
3. Select Affected Object and the name of your NGINXaaS deployment.

Events are deleted after 14 days.

What’s next

• Enable monitoring
• Metrics catalog
• Identity and access management