Log#

The module writes request logs in the specified format.

Configuration Example#

log_format basic '$remote_addr [$time_local] '
                 '$protocol $status $bytes_sent $bytes_received '
                 '$session_time';

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

Directives#

access_log#

Syntax

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

access_log off;

Default

access_log off;

Context

stream, server

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 either the buffer or gzip parameter is used, writes to log will be buffered.

Warning

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 the time interval 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 buffer 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, a buffer size of 64K bytes and compression level 1 are used. The data is compressed in atomic blocks, and at any time the log file can be decompressed or read by the "zcat" utility.

Example:

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

Note

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

Variables can be used in the file path, 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;
buffering does not work;
the file is opened for each log write and closed immediately after writing. However, since descriptors of frequently used files can be stored in a cache, writing may continue to the old file during log rotation for the time specified by the valid parameter of the open_log_file_cache directive.

The if parameter enables conditional logging. A session will not be logged if the condition evaluates to "0" or an empty string.

log_format#

Syntax	`log_format` name [`escape=default` \| `json` \| `none`] string ...;
Default	—
Context	stream

Specifies the log format, for example:

log_format proxy '$remote_addr [$time_local] '
                 '$protocol $status $bytes_sent $bytes_received '
                 '$session_time "$upstream_addr" '
                 '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';

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

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

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

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

stream, server

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 the cache; when the cache overflows, the least recently used (LRU) descriptors are closed.
`inactive`	Sets the time after which a cached descriptor is closed if there were no accesses during this time; by default, 10 seconds.
`min_uses`	Sets the minimum number of file uses during the time defined by the `inactive` parameter for the descriptor to remain open in the 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;