Master Nginx Logging: Configure access_log, error_log, and Custom Formats

Setting access_log

Nginx access logs record client requests, including IP address, browser information, referer, request processing time, and request URL. The specific fields to log are defined by the log_format directive.

Syntax

access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]];
access_log off;  # disable access log

path – specifies the log file location.

format – selects the log format (default is the predefined combined).

buffer – sets the buffer size for log writes (default 64k).

gzip – compresses log data before writing (level 1‑9, default 1).

flush – defines how long buffered data is kept before being flushed.

if – conditional logging; if the condition evaluates to 0 or an empty string, the request is not logged.

The special value off disables all access logging in the current scope.

Scope

The access_log directive can be used in the http, server, location, and limit_except scopes; using it outside these scopes results in an error.

Basic usage

access_log /var/logs/nginx-access.log

This example writes access logs to /var/logs/nginx-access.log using the default combined format.

access_log /var/logs/nginx-access.log buffer=32k gzip flush=1m

This example sets a 32 KB buffer, enables gzip compression with the default level, and flushes the buffer every minute.

Using log_format to customize log format

Nginx provides a predefined combined format. To define a custom format, use the log_format directive.

log_format combined '$remote_addr - $remote_user [$time_local] '
                '"$request" $status $body_bytes_sent '
                '"$http_referer" "$http_user_agent"';

If you need a format other than the predefined one, define it with log_format.

Syntax

log_format name [escape=default|json] string ...;

name – the format name, referenced by access_log.

escape – sets variable escaping to default or json (default is default).

string – the format string, which may contain Nginx variables.

Common variables include $bytes_sent, $body_bytes_sent, $connection, $request_time, $status, $time_local, $http_referer, $http_user_agent, $remote_addr, $http_x_forwarded_for, and many others.

access_log /var/logs/nginx-access.log main
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" "$http_user_agent" '
                '"$http_x_forwarded_for"';

Example log line generated with the above configuration:

112.195.209.90 - - [20/Feb/2018:12:12:14 +0800] "GET / HTTP/1.1" 200 190 "-" "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Mobile Safari/537.36" "-"

Variables such as $remote_user, $http_referer, and $http_x_forwarded_for appear as - when they are empty.

Setting error_log

The error_log directive records server and request processing errors.

Syntax

error_log file [level];
# Default: error_log logs/error.log error;

The first parameter specifies the log file path. The second parameter sets the log level, which can be debug, info, notice, warn, error, crit, alert, or emerg. Only messages with a severity equal to or higher than the specified level are logged; the default level is error.

Basic usage

error_log /var/logs/nginx/nginx-error.log

This configures the error log path; the default level error is used. The directive can be placed in the main, http, mail, stream, server, or location scopes.

open_log_file_cache

Each log entry normally opens the file, writes the record, and closes the file. When the log file path contains variables (e.g., access_log /var/logs/$host/nginx-access.log), you can improve performance by caching file descriptors with open_log_file_cache.

Syntax

open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];

max – maximum number of file descriptors cached; excess descriptors are closed using LRU.

inactive – time after which unused cached descriptors are closed (default 10s).

min_uses – minimum number of uses within the inactive period for a descriptor to stay cached (default 1).

valid – interval to re‑check the log file name for changes (default 60s).

off – disables caching (default is off).

Basic usage

open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;

This example caches up to 1000 file descriptors, keeps them for 20 seconds if they have been used at least twice, and checks the file names every minute.

Summary

In Nginx, access_log and error_log configure request and error logging. The log_format directive allows custom log layouts, and open_log_file_cache improves performance when log paths contain variables.