Log#

The module writes request logs in the specified format.

Logs are written in the context of a location where processing ends. This may be a location different from the original one if an internal redirect occurs 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; (path depends on the build parameter --http-log-path)

Context

http, server, location, if in location, limit_except

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

If the buffer size is specified using the buffer parameter or the gzip parameter is specified, writing 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, data is written to the file:

if the next log line does not fit in the buffer;
if the data in the buffer has been there longer than the time interval specified by the flush parameter;
when reopening the log file or terminating the worker process.

If the gzip parameter is specified, the buffer will be compressed before writing to the file. The compression level can be set in the range from 1 (faster, but worse compression) to 9 (slower, but better compression). By default, a buffer size of 64K bytes and compression level 1 are used. Data is compressed in atomic blocks, and at any time the log file can be decompressed or read using the zcat utility.

Example:

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

Note

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

Variables can be used in the file path, but such logs have some limitations:

the user under whose credentials the worker processes run must have permissions to create files in the 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 cache, during log rotation within the time specified by the valid parameter of the open_log_file_cache directive, writing may continue to the old file.
for each log write, the existence of the root directory for the request is checked — if this directory does not exist, the log is not created. Therefore root and access_log should be described at 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 evaluation result is "0" or an empty string. In the following example, 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`=:samp:default \| `json` \| `none` ] string ...;
Default	`log_format combined "...";`
Context	http

Specifies the log format.

The escape parameter allows setting character escaping to json or default 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 written to the log as the value.

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".

Header lines sent to the client start with the prefix sent_http_, for example, $sent_http_content_range.

The predefined format combined always exists in the configuration:

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 file descriptors of frequently used logs whose names are specified using variables. 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 it has not been accessed during this time. Default is 10 seconds.
`min_uses`	Sets the minimum number of file uses during the time specified by the `inactive` parameter, after which the file descriptor will remain open in the cache. Default is 1.
`valid`	Specifies after what time to check that the file still exists under the same name. Default is 60 seconds.
`off`	Disables caching.

Usage example:

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