<!-- review: finished -->

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

# Log

The module writes request logs in the specified format.

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

## Configuration Example

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

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

## Directives

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

<a id="s-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 off;`                                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | 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](https://en.angie.software//angie/docs/configuration/processing.md#syslog-logging) 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](https://en.angie.software//angie/docs/configuration/runtime.md#log-rotation) 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:

```nginx
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](https://en.angie.software//angie/docs/configuration/modules/core.md#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](https://en.angie.software//angie/docs/configuration/modules/http/http_log.md#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.

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

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

### log_format

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` name [`escape=``default` | `json` | `none`] string ...;   |
|------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| Default                                                                                  | —                                                                      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                 |

Specifies the log format, for example:

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

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

<a id="s-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)  | 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:

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