How to Set Custom Log Format in Nginx for Better Logging

To set a custom log format in Nginx, use the log_format directive inside the http block to define your format, then apply it with the access_log directive. This lets you customize what details Nginx records in access logs.

Syntax

The log_format directive defines a custom format for access logs. It is placed inside the http block. The syntax is:

• log_format name 'format string'; — defines a format named name.
• The format string contains variables like $remote_addr for client IP, $request for the request line, etc.
• Use the access_log directive to specify the log file and the format name.

nginx

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

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

    # other configurations
}

Example

This example shows how to create a custom log format that logs client IP, time, request, status, bytes sent, referrer, and user agent. It then applies this format to the access log.

nginx

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

    access_log /var/log/nginx/my_access.log my_custom;

    server {
        listen 80;
        server_name example.com;

        location / {
            root /usr/share/nginx/html;
            index index.html;
        }
    }
}

Output

Sample log line in /var/log/nginx/my_access.log:
127.0.0.1 - - [27/Apr/2024:12:00:00 +0000] "GET / HTTP/1.1" 200 612 "-" "Mozilla/5.0 (compatible)"

Common Pitfalls

Common mistakes when setting custom log formats include:

• Defining log_format outside the http block, which causes errors.
• Forgetting to specify the custom format name in the access_log directive, so default format is used.
• Using incorrect variable names or syntax errors in the format string.
• Not reloading Nginx after changes, so new format is not applied.

nginx

http {
    # Wrong: log_format outside http block
}

log_format wrong_format '$remote_addr - $request';

http {
    access_log /var/log/nginx/access.log wrong_format;
}

# Correct way:
http {
    log_format correct_format '$remote_addr - $request';
    access_log /var/log/nginx/access.log correct_format;
}

Quick Reference

Use this quick guide to set custom log formats:

Directive	Purpose	Example
log_format	Define a custom log format	log_format myformat '$remote_addr - $request';
access_log	Set log file and format	access_log /var/log/nginx/access.log myformat;
Variables	Use variables to customize logs	$remote_addr, $status, $request, $http_user_agent

Key Takeaways

Define custom log formats inside the http block using the log_format directive.

Apply your custom format with the access_log directive specifying the format name.

Use Nginx variables like $remote_addr and $request to customize log details.

Always reload Nginx after changing log formats to apply updates.

Avoid syntax errors and place directives correctly to prevent configuration failures.