Conditional logging in Nginx - Commands & Configuration

Introduction

Sometimes you want to log only certain requests in your web server to save space or focus on important events. Conditional logging in nginx lets you decide which requests get logged based on rules you set.

When you want to log only error responses to find problems faster.

When you want to skip logging requests for static files like images to reduce log size.

When you want to log requests from specific IP addresses for security monitoring.

When you want to disable logging for health check requests to keep logs clean.

When you want to log only POST requests to analyze form submissions.

Config File - nginx.conf

nginx.conf

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

    map $status $loggable {
        ~^[23] 1;
        default 0;
    }

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

    server {
        listen 80;
        server_name example.com;

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

The log_format defines how each log entry looks.

The map block creates a variable $loggable that is 1 for status codes starting with 2 or 3 (success and redirects), and 0 otherwise.

The access_log directive uses the if=$loggable condition to log only requests where $loggable is 1, meaning successful and redirect statuses.

The server block defines a simple web server listening on port 80.

Commands

Check the nginx configuration file syntax to make sure there are no errors before reloading.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

View the last 5 lines of the access log to verify that only requests matching the condition are logged.

Terminal

tail -n 5 /var/log/nginx/access.log

Expected Output

192.168.1.10 - - [27/Apr/2024:12:00:01 +0000] "GET /notfound HTTP/1.1" 404 150 "-" "Mozilla/5.0"

192.168.1.11 - - [27/Apr/2024:12:00:05 +0000] "POST /submit HTTP/1.1" 500 200 "-" "Mozilla/5.0"

Key Concept

If you remember nothing else from this pattern, remember: nginx can log requests selectively using variables and the 'if' condition in the access_log directive.

Common Mistakes

Using 'if' inside the server or location block to control logging instead of the 'if' parameter in access_log.

The 'if' directive inside server or location blocks does not control logging and can cause unexpected behavior.

Use the 'if' parameter directly in the access_log directive with a variable that controls logging.

Not testing nginx configuration with 'nginx -t' before reloading.

Reloading with a bad config will fail and may cause downtime.

Always run 'nginx -t' to verify syntax before reloading.

Setting the condition variable incorrectly so that all requests are logged or none are logged.

This defeats the purpose of conditional logging and can fill logs unnecessarily or miss important entries.

Use the 'map' directive carefully to set the variable based on exact conditions like status codes.

Summary

Define a log format to specify how logs look.

Use the 'map' directive to create a variable that decides which requests to log.

Apply conditional logging with 'access_log' using the 'if' parameter and the variable.

Test the configuration with 'nginx -t' before reloading nginx.

Check the logs to confirm only desired requests are logged.