nginx

Module ngx_http_log_module


english
русский

简体中文
עברית
日本語
türkçe

news
about
download
security advisories
documentation
pgp keys
faq
links
books
support
donation

trac
wiki
twitter
nginx.com
Example Configuration
Directives
     access_log
     log_format
     open_log_file_cache

The ngx_http_log_module module writes request logs in the specified format.

Requests are logged in a context of a location where processing ends. This may be different from the original location, if an internal redirect happens during request processing.

Example Configuration

log_format compression '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $bytes_sent '
                       '"$http_referer" "$http_user_agent" "$gzip_ratio"';

access_log /spool/logs/nginx-access.log compression buffer=32k;

Directives

syntax: access_log path [format [buffer=size [flush=time]]];
access_log path format gzip[=level] [buffer=size] [flush=time];
access_log off;
default:
access_log logs/access.log combined;
context: http, server, location, if in location, limit_except

Sets the path, format, and configuration of the buffered log writes. Several logs can be specified on the same level. The special value off cancels all access_log directives on the current level. If format is not specified then the predefined format “combined” is used.

If either the buffer or gzip (1.3.10) parameter is used, writes to log will be buffered.

The buffer size must not exceed the size of the atomic write to a disk file. For FreeBSD this size is unlimited.

When buffering is enabled, the data will be written to the file:

  • if the next log line does not fit into the buffer;
  • if the buffered data is older than specified by the flush parameter (1.3.10);
  • when a worker process is re-opening log files or is shutting down.

If the gzip parameter is used, then the buffered data will be compressed before writing to the file. The compression level can be set between 1 (fastest, less compression) and 9 (slowest, best compression). By default the buffer size is equal to 64K bytes, and the compression level is set to 1. Since the data is compressed in atomic blocks, the log file can be decompressed or read by “zcat” at any time.

Example:

access_log /path/to/log.gz combined gzip flush=5m;

For gzip compression to work, nginx must be built with the zlib library.

The file path can contain variables (0.7.6+), but such logs have some constraints:

  • the user whose credentials are used by worker processes should have permissions to create files in a directory with such logs;
  • buffered writes do not work;
  • a file is opened and closed for each log write. However, since the descriptors of frequently used files can be stored in a cache, writes during the time specified by the valid parameter of the open_log_file_cache directive can continue to be made to the old file.
  • during each log write the existence of the request’s root directory is checked, and if it does not exist the log is not created. It is thus a good idea to specify both root and access_log on the same level:
    server {
        root       /spool/vhost/data/$host;
        access_log /spool/vhost/logs/$host;
        ...
    

syntax: log_format name string ...;
default:
log_format combined "...";
context: http

Specifies format of a log.

The log format can contain common variables, and variables that exist only at the time of a log write:

$bytes_sent
the number of bytes sent to a client
Since versions 1.3.8 and 1.2.5 there is a common variable with the same name.
$connection
connection serial number
Since versions 1.3.8 and 1.2.5 there is a common variable with the same name.
$connection_requests
the current number of requests made through a connection (1.1.18)
Since versions 1.3.8 and 1.2.5 there is a common variable with the same name.
$msec
time in seconds with a milliseconds resolution at the time of log write
Since versions 1.3.9 and 1.2.6 there is a common variable with the same name.
$pipe
p” if request was pipelined, “.” otherwise
$request_length
request length (including request line, header, and request body)
$request_time
request processing time in seconds with a milliseconds resolution; time elapsed between the first bytes were read from the client and the log write after the last bytes were sent to the client
Since versions 1.3.9 and 1.2.6 there is a common variable with the same name.
$status
response status
Since versions 1.3.2 and 1.2.2 there is a common variable with the same name.
$time_iso8601
local time in the ISO 8601 standard format
$time_local
local time in the Common Log Format

Header lines sent to a client have the prefix “sent_http_”, for example, $sent_http_content_range.

The configuration always includes the predefined format “combined”:

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

syntax: open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];
open_log_file_cache off;
default:
open_log_file_cache off;
context: http, server, location

Defines a cache that stores file descriptors of frequently used logs whose names contain variables. The directive has the following parameters:

max
sets a maximum number of descriptors in a cache; if cache becomes full the least recently used (LRU) descriptors are closed
inactive
sets a time after which the cached descriptor is closed if there were no access during this time; by default, 10 seconds
min_uses
sets a minimum number of file uses during the time defined by the inactive parameter after which the descriptor will stay open in a cache; by default, 1
valid
sets a time after which it should be checked that the file still exists with the same name; by default, 60 seconds
off
disables caching

Example usage:

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