Master Nginx Logging: Access Log, Formats, and Debugging Tips

nginx access log configuration

access_log configuration

access_log defines the log level and location. Syntax:

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

Default: access_log logs/access.log combined; Scope: http, server, location, if in location, limit_except.

log_format definition

log_format name [escape=default|json] string ...;
# default value
log_format combined "...";
Scope: http

Example:

log_format compression '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent "$http_referer" "$http_user_agent" "$gzip_ratio"';
access_log /spool/logs/nginx-access.log compression buffer=32k;

common log variables

$remote_addr

, $http_x_forwarded_for – client IP address $remote_user – client username $request – request line (method, URI, protocol) $status – response status code $body_bytes_sent – bytes sent to client (excluding headers) $bytes_sent – total bytes sent $connection – connection serial number $connection_requests – number of requests on this connection $msec – time of log write in milliseconds $pipe – "p" if request was pipelined, otherwise "." $http_referer – referring page $http_user_agent – client browser info $request_length – length of the request (headers + body) $request_time – request processing time in seconds (millisecond precision) $time_iso8601 – local time in ISO‑8601 format $time_local – local time in common log format

open_log_file_cache

Use open_log_file_cache to set log file caching (default off).

max – maximum number of file descriptors cached; LRU eviction when full

inactive – idle time before a cached descriptor is closed (default 10s)

min_uses – minimum uses within inactive period before caching (default 1)

valid – cache validation interval (default 60s)

off – disable caching

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

Example:

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

nginx log debugging techniques

Log only errors from your IP

When debug level generates excessive logs, restrict error logging to a specific IP:

events {
    debug_connection 1.2.3.4;
}

Debug rewrite rules

Enable rewrite logging to trace rewrite processing:

server {
    error_log /var/logs/nginx/example.com.error.log;
    rewrite_log on;
}

With rewrite_log on; rewrite messages are sent to the error log at the notice level.

Log specific URLs with location

server {
    error_log /var/logs/nginx/example.com.error.log;
    location /static/ {
        error_log /var/logs/nginx/static-error.log debug;
    }
}

Requests to /static/ are recorded separately in static-error.log.

nginx logging involves three main directives: access_log (path and format), log_format (template), and open_log_file_cache (file cache).

When backend applications need the client IP, set:

proxy_set_header X-Forwarded-For $remote_addr;

common examples

main format

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

json format

log_format logstash_json '{"@timestamp":"$time_iso8601","host":"$server_addr","client":"$remote_addr","size":$body_bytes_sent,"responsetime":$request_time,"domain":"$host","url":"$request_uri","referer":"$http_referer","agent":"$http_user_agent","status":"$status","x_forwarded_for":"$http_x_forwarded_for"}';

compression format

Include compression ratio in logs:

http {
    log_format compression '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$gzip_ratio"';
    server {
        gzip on;
        access_log /spool/logs/nginx-access.log compression;
    }
}

upstream format

Record upstream connection times:

http {
    log_format upstream_time '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" rt=$request_time uct="$upstream_connect_time" uht="$upstream_header_time" urt="$upstream_response_time"';
    server {
        access_log /spool/logs/nginx-access.log upstream_time;
    }
}

reference commands

Count occurrences of each status code:

awk '{print $9}' access.log | sort | uniq -c | sort -rn

Show URLs that returned a 302 status:

awk '($9 ~ /302/)' access.log | awk '{print $7}' | sort | uniq -c | sort -rn