Mastering Nginx Logging: From Basic Access Logs to Advanced Conditional Logging

Nginx is not just a web server or reverse proxy—it’s also a powerful logging platform that can provide deep insights into your application’s behavior. Whether you’re debugging API issues, monitoring performance, or tracking specific user journeys, nginx logging capabilities can be your best friend. In this comprehensive guide, we’ll explore everything from basic access logs to advanced conditional logging techniques.

Why Nginx-Level Logging Matters

Before diving into the technical details, let’s understand why nginx-level logging is crucial:

• First line of defense: Nginx sees every request before it reaches your application
• Performance insights: Track response times, connection times, and bottlenecks
• Security monitoring: Identify suspicious patterns and attack attempts
• Load balancing intelligence: Monitor upstream server performance
• Debugging without touching application code: Troubleshoot issues at the infrastructure level

Basic Nginx Logging Setup

Nginx comes with built-in logging capabilities that you can configure in your nginx.conf file:

# Basic access logging
access_log /var/log/nginx/access.log combined;

# Error logging
error_log /var/log/nginx/error.log warn;

The combined format includes common fields like IP address, timestamp, request method, status code, and user agent. But we can do much better than this!

Custom Log Formats: Getting More Insights

Custom log formats allow you to capture exactly the information you need. Here’s a powerful example that includes performance metrics:

log_format detailed '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   'request_time=$request_time '
                   'upstream_response_time=$upstream_response_time '
                   'upstream_connect_time=$upstream_connect_time '
                   'upstream_header_time=$upstream_header_time';

access_log /var/log/nginx/detailed.log detailed;

This format captures timing information that’s invaluable for performance analysis:

• $request_time: Total time nginx spent processing the request
• $upstream_response_time: Time to receive response from upstream server
• $upstream_connect_time: Time to establish connection to upstream
• $upstream_header_time: Time to receive response headers

Conditional Logging: Log What Matters

One of nginx’s most powerful features is conditional logging. Instead of logging every request, you can log only what’s important to you.

Example: Logging Specific API Endpoints

Let’s say you have multiple API services and want to log only requests to a specific service (like /api/v2/payments/):

# Create a map to identify specific requests
map $request_uri $log_payments {
    ~*/api/v2/payments/* 1;
    default              0;
}

# Custom log format for API monitoring
log_format api_monitor '$remote_addr - $remote_user [$time_local] '
                      '"$request" $status $body_bytes_sent '
                      '"$http_referer" "$http_user_agent"\n'
                      'nginx_total_time=$request_time\t'
                      'upstream_response_time=$upstream_response_time\t'
                      'upstream_connect_time=$upstream_connect_time\t'
                      'upstream_header_time=$upstream_header_time\t'
                      'service=payments\n-------------------------------';

server {
    listen 8080 ssl;
    
    # Only log requests matching our condition
    access_log /var/log/nginx/payments_api.log api_monitor if=$log_payments;
    
    location / {
        proxy_pass http://backend;
    }
}

This configuration creates beautifully formatted logs that are easy to read and analyze:

192.168.1.100 - - [07/Aug/2025:19:00:00 +0000] "POST /api/v2/payments/process HTTP/1.1" 200 1234 "-" "Mozilla/5.0..."
nginx_total_time=0.156	upstream_response_time=0.123	upstream_connect_time=0.002	upstream_header_time=0.045	service=payments
-------------------------------

Advanced Conditional Logic

You can create more complex conditions using multiple variables:

# Log only slow requests (>1 second)
map $request_time $slow_request {
    ~^[0-9]+\.[0-9]*[0-9][1-9]+$ 1;  # >1 second
    default 0;
}

# Log only errors
map $status $error_request {
    ~^[45] 1;
    default 0;
}

# Combined condition: slow requests OR errors
map "$slow_request$error_request" $should_log {
    ~1 1;
    default 0;
}

Real-World Use Cases

1. API Performance Monitoring

log_format api_performance '$time_local API_CALL '
                          'method=$request_method '
                          'uri=$request_uri '
                          'status=$status '
                          'response_time=$request_time '
                          'upstream_time=$upstream_response_time '
                          'bytes_sent=$body_bytes_sent '
                          'client_ip=$remote_addr';

2. Security Monitoring

# Log suspicious requests
map $request_uri $suspicious {
~*(\.\./)|(etc/passwd)|(cmd=)|(exec\()|(

log_format upstream_health '$upstream_addr '
                          'status=$status '
                          'connect_time=$upstream_connect_time '
                          'response_time=$upstream_response_time '
                          'request="$request"';

# Log only upstream failures
map $upstream_status $upstream_error {
    ~^[45] 1;
    default 0;
}

access_log /var/log/nginx/upstream_errors.log upstream_health if=$upstream_error;

# Watch logs in real-time
tail -f /var/log/nginx/api.log

# Filter for specific patterns
tail -f /var/log/nginx/api.log | grep "status=500"

# Monitor response times
tail -f /var/log/nginx/api.log | grep -o "request_time=[0-9.]*"