Enable NGINX logs

Overview

NGINXaaS for Azure supports integrating Azure Diagnostic Settings to collect NGINX error and access logs.

Configuring NGINX logs collection using diagnostic settings

Prerequisites

• A valid NGINX configuration with log directives enabled. NGINX logs can be configured using error_log and access_log directives.

• A system-assigned managed identity.

  Note:
  The system-assigned managed identity does not need any role assignments to enable the logging functionality described in this section. You will need to make sure that the managed identity has the appropriate role assignments to access other resources that it is attached to (for example, certificates stored in Azure Key Vault).

• User must be an owner or user access administrator for the NGINX deployment resource.

Adding diagnostic settings

1. Go to your NGINXaaS for Azure deployment.

2. Select Diagnostic Settings in the left menu.

3. Select Add diagnostic setting.

4. Choose the NGINX Logs option and complete the details on the form, including the Diagnostic setting name.

   Note:
   You will need to configure the system-assigned managed identity in order to see and select the NGINX Logs option.

5. Select preferred Destination details.

For more information about diagnostic settings destinations, please see the Diagnostic Settings Destinations documentation.

Note:
Due to limitations imposed by Azure, if the destination chosen is an Azure Storage account, the resource has to be in the same region as the NGINXaaS deployment resource.

Note:
If you are a terraform user, please refer to examples provided to setup diagnostic settings for your NGINXaaS deployment

Analyzing NGINX logs in Azure Storage.

If the diagnostic setting destination details included a Storage Account, logs show up in the storage container “insights-logs-nginxlogs” with the following format: resourceID=/<NGINXaaS-resourceID>/y=<YYYY>/m=<MM>/d=<DD>/h=<HH>/PT1H.json

Note:
It can take up to 90 minutes after adding diagnostic settings for logs to appear in the provided Azure Storage container.

Each log event in the PT1H.json file is written in a new line delimited JSON text format. The properties that show up in each log line are described described in the Top Level Common Schema documentation.

For instance, an access log event logging to a particular file path will have attributes similar to this example:

{
	"category": "NginxLogs",
	"location": "westcentralus",
	"operationName": "NGINX.NGINXPLUS/NGINXDEPLOYMENTS/LOG",
	"properties": {
		"message": "172.92.129.50 - \"-\" [18/Jan/2024:17:59:00 +0000] \"GET / HTTP/1.1\" 200 11232 \"-\" \"curl/8.4.0\" \"-\" \"20.69.58.179\" sn=\"localhost\" rt=0.000 ua=\"-\" us=\"-\" ut=\"-\" ul=\"-\" cs=\"-\" ",
		"filePath": "/var/log/nginx/access.log"
	},
	"resourceId": "/SUBSCRIPTIONS/FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF/RESOURCEGROUPS/RESOURCEGROUP1/PROVIDERS/NGINX.NGINXPLUS/NGINXDEPLOYMENTS/TEST1",
	"time": "2024-01-18T17:59:00.363956795Z"
}

If syslog-based logs are used, the log event entry has different properties sub-fields:

#...
"properties": {
		"message": "172.92.129.50 - - [16/Jan/2024:18:00:00 +0000] \"GET / HTTP/1.1\" 200 11232 \"-\" \"curl/8.4.0\"",
		"tag": "nginx",
		"severity": "info",
		"facility": "local7"
	},
#...

Analyzing NGINX logs in Azure Log Analytics workspaces.

If the diagnostic setting destination details included a Logs Analytics workspace, logs show up in the table “NGXOperationLogs” with the following non-standard attributes:

Using a KQL, a custom query can be run to view the logs:

NGXOperationLogs
| where Location contains "eastus"

For more information on the standard attributes that appear in Logs Analytics,see the Standard columns in Azure Monitor Logs documentation.

For more information on using KQL see Queries in Log Analytics.

Note:
It can take up to 90 minutes after adding diagnostic settings for logs to appear in the provided Logs Analytics Workspace.

Disable NGINX logs collection

1. Go to your NGINXaaS for Azure deployment.

2. Select Diagnostic Settings in the left menu.

3. Edit the previously added Diagnostic Settings.

4. Select Delete.

Note:
It can take up to 90 minutes after removing the diagnostic settings for logs to stop publishing to the diagnostic destinations.

Setting Up Error Logs

By default, the error log in NGINXaaS for Azure is located at the path /var/log/nginx/error.log and logs messages with severity error and above. This can be overridden to use a preferred filename and severity level. The log path should always be configured to be inside /var/log/nginx. For instance, to log error logs to /var/log/nginx/nginx-error.log with a severity level of emerg, the directive in the NGINX config can be specified as:

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

To disable error logs completely, the directive should be configured as:

error_log /dev/null;

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

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

Note:
It is recommended that log lines include the datetime for the purpose of ordering logs after being exported. The $time_local variable provides an easy way to include this in the log format that is used.

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:
When not using syslog, the configured path for nginx logs has to be within /var/log/nginx. If the log directives are configured to log to other file path locations, they will not be scraped, leading to a loss of log data.

Logging to syslog

NGINXaaS for Azure allows configuring log directives with the syslog: prefix, which can be a domain name, an IP address or a specific Unix domain socket.

In addition to using an external syslog server, NGINXaaS deployments also provide a way for logs to be sent to a local syslog server that then gets exported to the destination configured by the Diagnostic Settings. To leverage the provided local unix domain socket, please ensure the unix domain path used in the syslog configuration is always unix:/var/log/nginx.socket.

For instance:

error_log  syslog:server=unix:/var/log/nginx.socket debug;

For more information about how to configure the error_log and access_log directives for syslog see Logging to syslog.

Note:
The log traffic sent to external syslog domains or servers is unencrypted. It is strongly recommended that the syslog server be in the same VNet as the NGINXaaS for Azure deployment or one that is peered with the VNet where the NGINXaaS for Azure deployment is on.

Limitations

1. File-based logs must be configured to use the path /var/log/nginx.
2. The gzip parameter for the access_log directive is not supported, and uploading a config with this parameter will cause an error.
3. Logging error_log to a cyclic memory buffer using the memory: prefix is not allowed and will cause a config upload error.
4. Egress Networking charges apply for traffic sent from the NGINX deployment to a syslog server present in a different VNet.