# Enable NGINX logs

Type of document: How-to guide
Product: NGINXaaS for AWS
> Learn how to configure, export, view, and disable NGINX access and error log export to Amazon CloudWatch 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](/nginxaas/aws/deploy/access-management.md) for how to create the role and attach the [Policy for CloudWatch Logs](/nginxaas/aws/deploy/access-management.md#step-3-add-inline-policies-to-your-role).
- 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/auth-and-access-control-cwl.html) 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**:

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

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

```nginx
error_log /dev/null;
```

To learn more about how to specify `error_log` in different configuration levels, see the documentation of the [error_log](https://nginx.org/en/docs/ngx_core_module.html?#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**.

```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;
	# ...
}
```

**Note:**  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:

```nginx
http {
	access_log off;
}
```

or

```nginx
http {
	access_log /dev/null;
}
```

To learn more about how to specify `access_log` in different configuration levels and their effect, see [access_log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log)

**Note:** 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](/nginxaas/aws/deploy/create-deployment/) for a step-by-step guide. To update an existing deployment, in the NGINXaaS console,

1. On the navigation menu, select **Deployments**.
1. Select the deployment you want to update and select **Edit**.
1. In the **Identity** section, make sure the **Role ARN** field is populated with an IAM role that has the [required permissions](#before-you-begin). Log export fails without it.
1. In the **Observability** section, turn on the **Export Logs to CloudWatch** toggle.
1. 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.
1. Select **Update**.

## View NGINX logs in Amazon CloudWatch Logs

In the [AWS Management Console](https://console.aws.amazon.com/),

1. Go to the **CloudWatch** console and select **Logs** > **Log Management** > **Log groups**.
1. In the **Filter log groups** field, enter the name of your log group to find it quickly.
1. 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) 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**.
1. Select the log group for your deployment (default value is the deployment object ID).
1. In the query editor, enter the following query to filter for access log entries

```text
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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/LogAnalytics.html) 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**.
1. Select the deployment you want to update and select **Edit**.
1. In the **Observability** section, turn off the **Export Logs to CloudWatch** toggle.
1. 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**.
1. Select **Add Filter**.
1. Select **Affected Object** and the name of your NGINXaaS deployment.

Events are deleted after 14 days.

## What's next

- [Enable monitoring](/nginxaas/aws/monitoring/enable-monitoring.md)
- [Metrics catalog](/nginxaas/aws/monitoring/metrics-catalog.md)
- [Identity and access management](/nginxaas/aws/deploy/access-management.md)