Master Nginx Access & Error Log Configuration: A Complete Guide

Nginx is an open‑source, high‑performance HTTP and reverse‑proxy server that handles traffic for many large sites. One of the most common tasks when managing Nginx is checking its log files.

Understanding how to configure and read logs is essential for troubleshooting server or application issues because logs provide detailed debugging information.

Nginx records events using two types of logs: access logs, which capture client request details, and error logs, which capture server and application problems.

Configure Nginx Access Log

Each client request generates a new entry in the access log, containing a timestamp and various details about the client and the requested resource.

The log_format directive lets you define the log format, and the access_log directive enables logging and sets the file location and format.

The basic syntax of the access_log directive is: access_log log_file log_format; where log_file is the full path to the log file and log_format is the format name defined elsewhere (e.g., in the http, server, or location context).

By default, the http block in the main Nginx configuration defines a global access‑log format.

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

For better maintainability, it is recommended to set a separate access‑log file for each server. An access_log directive inside a server block overrides the one defined in the http block.

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

  server {
    server_name domain.com;
    access_log /var/log/nginx/domain.access.log;
    ...
  }
}

If no custom format is specified, Nginx uses the predefined combined format:

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

You can define a new format, for example custom, that adds the X-Forwarded-For header:

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

To use the new format, specify its name after the log file: access_log /var/log/nginx/access.log custom; If disk space or performance is a concern, you can disable the access log by setting the access_log directive to off:

access_log off;

Configure Error Log

Nginx writes application and server error messages to the error log. The error_log directive enables and sets the log file location and severity level. error_log log_file log_level; The log_level parameter can be one of the following (from lowest to highest severity): debug – debug messages info – informational messages notice – normal but significant conditions warn – warnings error – error conditions (default) crit – critical conditions alert – alerts requiring immediate action emerg – emergency, system unusable

Higher severity levels include all messages of lower levels; for example, setting warn also logs error, crit, alert, and emerg messages.

By default, the error_log directive is defined in the http context of the main nginx.conf file:

http {
  ...
  error_log /var/log/nginx/error.log;
  ...
}

It is also advisable to set a separate error‑log file for each server, which overrides the global setting.

http {
  ...
  error_log /var/log/nginx/error.log;
  ...

  server {
    server_name domain.com;
    error_log /var/log/nginx/domain.error.log warn;
    ...
  }
}

After modifying any configuration file, reload Nginx to apply the changes.

Log File Locations

On most Linux distributions (e.g., Ubuntu, CentOS, Debian), the default location for both access and error logs is /var/log/nginx.

Read and Understand Nginx Log Files

You can use standard Linux commands such as cat, less, grep, cut, and awk to open and parse Nginx log files. An example access‑log entry using the default format looks like:

192.168.33.1 - - [15/Oct/2019:19:41:46 +0000] "GET / HTTP/1" 200 396 "-" "Mozilla/0 (X11; Linux x86_64) AppleWebKit/536 (KHTML, like Gecko) Chrome/38120 Safari/536"

The fields represent: $remote_addr – client IP address (e.g., 192.168.33.1) $remote_user – HTTP authentication user ("-" if not set) [$time_local] – local server time "$request" – request line (method, path, protocol) $status – HTTP response code $body_bytes_sent – size of the response in bytes "$http_referer" – referer URL ("-" if none) "$http_user_agent" – client user‑agent string

Use the tail -f command to watch log entries in real time:

tail -f access.log