FAQ

Page Discussion Edit History

HttpLogModule

Contents

[edit] Synopsis

Controls how nginx logs requests.

Example:

log_format gzip '$remote_addr - $remote_user [$time_local]  '
                '"$request" $status $bytes_sent '
                '"$http_referer" "$http_user_agent" "$gzip_ratio"';
 
access_log  /spool/logs/nginx-access.log  gzip  buffer=32k;

For information about logging of errors see error_log documentation in core module.

[edit] Directives

[edit] access_log

Syntax: access_log path [ format [ buffer = size ]]
access_log off
Default: logs/access.log combined
Context: http
server
location
if in location
limit_except
Reference:access_log


The access_log directive sets the path, format and buffer size for the access log file. Using "off" as the only parameter clears all access_log directives for the current level. If the format is not indicated, it defaults to "combined". The size of buffer must not exceed the size of the atomic record for writing into the disk file. This size is not limited for FreeBSD 3.0-6.0.

The log file path can contain variables (version >=0.7.4) but such logs have some limitations:

  • worker user must have permission to create files in;
  • buffering does not work;
  • for each log entry, the file is opened and immediately closed after writing the record. However, descriptors of frequently used files may be stored in open_log_file_cache . Regarding log rotation, it must be kept in mind that over time (which is set by the parameter valid of directive open_log_file_cache), logging can be still continue to the old file.

Nginx supports powerful access log separation per location. Accesses can also be output to more than one log at the same time. For more details, see the Multiple access_log directives in different contexts thread on the mailing list.

[edit] log_format

Syntax: log_format name string ...
Default: combined "..."
Context: http
Reference:log_format


The log_format directive describes the format of a log entry. You can use general variables in the format, as well as variables which exist only at the moment of writing into the log:

  • $body_bytes_sent, the number of bytes, transmitted to client minus the response headers. This variable is compatible with the %B parameter of Apache's mod_log_config (this was called $apache_bytes_sent, before version 0.3.10)
  • $bytes_sent, the number of bytes transmitted to client
  • $connection, the number of connection
  • $msec, the current time at the moment of writing the log entry (microsecond accuracy)
  • $pipe, "p" if request was pipelined
  • $request_length, the length of the body of the request
  • $request_time, the time it took nginx to work on the request, in seconds with millisecond precision (just seconds for versions older than 0.5.19)
  • $status, status of answer
  • $time_iso8601, time in ISO 8601 format, e. g. 2011-03-21T18:52:25+03:00 (added in 0.9.6)
  • $time_local, local time into common log format.

The headers, transmitted to client, begin from the prefix "sent_http_", for example, $sent_http_content_range.

Note that variables produced by other modules can also be logged. For example you can log upstream response headers with the prefix "upstream_http_", see upstream .

There is a predefined log format called "combined":

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

[edit] open_log_file_cache

Syntax: open_log_file_cache max = N [ inactive = time ] [ min_uses = N ] [ valid = time ]
open_log_file_cache off
Default: off
Context: http
server
location
Reference:open_log_file_cache


The directive sets the cache, which stores file descriptors of frequently used logs with variable in path.

Directive options:

  • max - maximal number of descriptors in the cache, with overflow Least Recently Used is removed (LRU);
  • inactive - sets the time after which descriptor without hits during this time are removed; default is 10 seconds;
  • min_uses - sets the minimum number of file usage within the time specified in parameter inactive, after which the file descriptor will be put in the cache; default is 1;
  • valid - sets the time until it will be checked if file still exists under same name; default is 60 seconds;
  • off - disables the cache.

Example:

open_log_file_cache max=1000 inactive=20s min_uses=2 valid=1m;

[edit] References

Original Documentation