Log#

The module writes request logs in the specified format.

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

Configuration Example#

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

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

Directives#

access_log#

Syntax

access_log path [format [buffer=size] [gzip=level]] [flush=time] [if=condition]];

access_log off;

Default

access_log logs/access.log combined; (the path depends on the --http-log-path build option)

Context

http, server, location, if in location, limit_except

Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same configuration level. Logging to syslog can be configured by specifying the "syslog:" prefix in the first parameter. The special value off cancels all access_log directives on the current level. If the format is not specified then the predefined "combined" format is used.

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

Caution

The buffer size must not exceed the size of an 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;
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;

Important

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

The file path can contain variables, 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;
the file is opened and closed for each log write. However, since the descriptors of frequently used files can be stored in a cache, writing to the old file can continue during the time specified by the open_log_file_cache directive's valid parameter
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 configuration level:

server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...

The if parameter enables conditional logging. A request will not be logged if the condition evaluates to "0" or an empty string. In the following example, the requests with response codes 2xx and 3xx will not be logged:

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

access_log /path/to/access.log combined if=$loggable;

log_format#

Syntax	`log_format` name [`escape=default` \| `json` \| `none`] string ...;
Default	`log_format combined "...";`
Context	http

Specifies log format.

The escape parameter allows setting json or default characters escaping in variables, by default, default escaping is used. The none value disables escaping.

For default escaping, characters """, "\", and other characters with values less than 32 or above 126 are escaped as "\xXX". If the variable value is not found, a hyphen "-" will be logged.

For json escaping, all characters not allowed in JSON strings will be escaped: characters """ and "\" are escaped as "\"" and "\\", characters with values less than 32 are escaped as "\n", "\r", "\t", "\b", "\f", or "\u00XX".

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

The configuration always includes the predefined combined format:

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

open_log_file_cache#

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 the file descriptors of frequently used logs whose names contain variables. The directive has the following parameters:

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

Usage example:

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