<!-- review: finished -->

<a id="http-log"></a>

# 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](https://en.angie.software//angie/docs/configuration/modules/http/index.md#internal) occurs during request processing.

<a id="configuration-example-27"></a>

## Configuration Example

```nginx
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;
```

<a id="directives-28"></a>

## Directives

<a id="index-0"></a>

<a id="access-log"></a>

### access_log

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `access_log` path [format [`buffer=`size] [`gzip=`level]] [`flush=`time] [`if=`condition]];<br/><br/>`access_log` `off`;                                                      |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `access_log logs/access.log combined;`<br/>(path depends on the [build parameter](https://en.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | 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](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging) 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](https://en.angie.software//angie/docs/configuration/runtime.md#log-rotation) 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:

```nginx
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](https://en.angie.software//angie/docs/configuration/modules/core.md#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](#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](https://en.angie.software//angie/docs/configuration/modules/http/index.md#root) and [access_log](#access-log) should be described at the same configuration level:

```nginx
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:

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

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

<a id="index-1"></a>

<a id="log-format"></a>

### log_format

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` name [`escape`=:samp:default | `json` | `none`] string ...;   |
|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Default                                                                                  | `log_format combined "...";`                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | 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:

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

<a id="index-2"></a>

<a id="open-log-file-cache"></a>

### open_log_file_cache

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `open_log_file_cache` `max=`N [`inactive=`time] [`min_uses=`N] [`valid=`time];<br/><br/>`open_log_file_cache` `off`;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | `open_log_file_cache off;`                                                                                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | 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.<br/>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.<br/>Default is 1. |
| `valid`    | Specifies after what time to check that the file still exists under the same name.<br/>Default is 60 seconds.                                                                |
| `off`      | Disables caching.                                                                                                                                                            |

Usage example:

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