How to Use Conditional Logging in Nginx for Flexible Log Control

Use the if directive inside the http or server block to set a variable that controls logging. Then, use the access_log directive with a condition to enable or disable logging based on that variable.

Syntax

Conditional logging in Nginx uses a variable to decide whether to log a request. You define a variable with set inside an if block, then use that variable in the access_log directive with the if= parameter.

• if (condition) { set $loggable 1; }: Sets a variable when the condition is true.
• access_log /path/to/log combined if=$loggable;: Logs only if $loggable is true (non-empty and not 0).

nginx

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

    server {
        listen 80;

        # Default: do not log
        set $loggable 0;

        # Enable logging only for requests with URI starting with /api
        if ($request_uri ~ ^/api) {
            set $loggable 1;
        }

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

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

Example

This example logs only requests where the URI starts with /api. Other requests are not logged, reducing log size and focusing on important traffic.

nginx

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

    server {
        listen 8080;

        set $loggable 0;

        if ($request_uri ~ ^/api) {
            set $loggable 1;
        }

        access_log /var/log/nginx/api_access.log main if=$loggable;

        location /api {
            return 200 'API request logged';
        }

        location / {
            return 200 'No logging for this request';
        }
    }
}

Common Pitfalls

• Using if inside location blocks can cause unexpected behavior; prefer using it inside server or http blocks.
• Not initializing the variable (e.g., $loggable) to 0 can cause all requests to be logged.
• Using complex conditions inside if can slow down Nginx; keep conditions simple.
• Remember that if is not a full programming conditional; avoid nested or complex logic.

nginx

## Wrong way: No variable initialization
http {
    server {
        listen 80;

        if ($request_uri ~ ^/admin) {
            set $loggable 1;
        }

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

## Right way: Initialize variable to 0
http {
    server {
        listen 80;

        set $loggable 0;

        if ($request_uri ~ ^/admin) {
            set $loggable 1;
        }

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

Quick Reference

Tips for conditional logging in Nginx:

• Always initialize your logging variable to 0 before using if.
• Use simple regex or conditions in if to avoid performance issues.
• Use access_log ... if=$variable; to enable conditional logging.
• Test your config with nginx -t before reloading.

Key Takeaways

Use the 'if' directive to set a variable that controls logging conditionally.

Initialize the logging control variable to 0 to avoid logging all requests unintentionally.

Apply the 'if=' parameter in 'access_log' to enable conditional logging based on the variable.

Keep 'if' conditions simple and avoid placing them inside 'location' blocks for stability.

Always test your Nginx configuration with 'nginx -t' before applying changes.