Nginx Log Format Customization

Proper log configuration in Nginx provides critical visibility into traffic patterns, performance bottlenecks, and security events. Custom log formats help you extract precisely the data you need for effective monitoring and troubleshooting.

Default Log Format

Nginx's built-in combined format includes the client IP, timestamp, request line, status code, response size, referrer, and user agent:

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

JSON Log Format

Structured JSON logs are significantly easier to parse and index with modern log aggregation tools like the ELK Stack, Datadog, Splunk, or CloudWatch:

log_format json_combined escape=json
    '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"request":"$request",'
        '"status":$status,'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_response_time":"$upstream_response_time",'
        '"http_referrer":"$http_referer",'
        '"http_user_agent":"$http_user_agent"'
    '}';

access_log /var/log/nginx/access.log json_combined;

The escape=json parameter ensures special characters in log values are properly escaped to produce valid JSON output that will not break your log parser.

Performance Metrics

Add timing variables to your log format to identify slow requests and backend performance issues:

• $request_time: Total elapsed time from first client byte received to last byte sent back.
• $upstream_response_time: Time Nginx spent waiting for the upstream backend server to respond.
• $upstream_connect_time: Time to establish a TCP connection to the upstream server.

Conditional Logging

Reduce log volume and noise by filtering out known repetitive requests like health checks or monitoring probes:

map $request_uri $loggable {
    /health 0;
    /ready  0;
    default 1;
}

access_log /var/log/nginx/access.log combined if=$loggable;

Per-Site Logging

Use separate log files for each server block to simplify analysis and troubleshooting for individual applications:

server {
    server_name example.com;
    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log warn;
}

Error Log Levels

Error log severity levels from most to least verbose: debug, info, notice, warn, error, crit, alert, emerg. Use warn or error in production to avoid excessive disk usage from verbose logging.

Log Rotation

Configure logrotate to prevent log files from consuming all available disk space. After rotation completes, send the USR1 signal to the Nginx master process to reopen log file descriptors without requiring a full restart.