Enable NGINX logs using CLI

Overview

F5 NGINX as a Service for Azure (NGINXaaS) supports integrating Azure Diagnostic Settings to collect NGINX error and access logs.

Caution:
Enabling logs using the NGINX Logs blade on your NGINXaaS deployment is now deprecated. This feature will be removed in an upcoming update. If you have issues accessing your NGINX logs using the deprecated method, please follow the steps in this guide to access your NGINX 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

Diagnostic settings for the NGINXaaS deployment resource can be managed using the Azure monitor diagnostic settings commands.

To add diagnostic settings to export NGINX logs to a storage account for an NGINXaaS deployment, the following command can be used:

 az monitor diagnostic-settings create --resource <nginxaas_resource_id> --logs "[{category:NginxLogs,enabled:true,retention-policy:{enabled:false,days:0}}]" --name <diagnostic_setting_name> --storage-account <storage_account_name>

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.

To use a logs analytics workspace as the export destination, use the following command:

 az monitor diagnostic-settings create --resource <nginxaas_resource_id> --logs "[{category:NginxLogs,enabled:true,retention-policy:{enabled:false,days:0}}]" --name <diagnostic_setting_name> --workspace <logs_analytics_workspace_name>

To view the supported log categories for an NGINXaaS resource, use the following command:

az monitor diagnostic-settings list --resource <nginxaas_resource_id>

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 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.

Setting up error logs

By default, NGINXaaS for Azure puts the error log at /var/log/nginx/error.log. It includes messages with severity error and above.

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.

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:
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:
Unless you use syslog, keep NGINX logs in the /var/log/nginx directory. Otherwise, you may lose data from your logs.

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.