<!-- review: finished -->

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

# Log

该模块以指定格式写入请求日志。

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

## 配置示例

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

## 指令

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

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

### access_log

| [语法](https://cn.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`;   |
|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| 默认                                                                                   | `access_log off;`                                                                                                         |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                            |

设置缓冲日志写入的路径、格式和配置。可以在同一配置级别上指定多个日志。通过在第一个参数中指定 `"syslog:"` 前缀，可以配置记录到 [syslog](https://cn.angie.software//angie/docs/configuration/processing.md#syslog-logging)。特殊值 `off` 取消当前级别上的所有 `access_log` 指令。

如果使用了 `buffer` 或 `gzip` 参数，则日志写入将被缓冲。

#### WARNING
缓冲区大小不得超过对磁盘文件的原子写入大小。对于 FreeBSD，该大小是无限制的。

启用缓冲时，数据将写入文件：

* 如果下一行日志不适合缓冲区；
* 如果缓冲的数据比 `flush` 参数指定的时间间隔更旧；
* 当工作进程 [重新打开日志文件](https://cn.angie.software//angie/docs/configuration/runtime.md#log-rotation) 或关闭时。

如果使用了 `gzip` 参数，则缓冲区将在写入文件之前进行压缩。压缩级别可以设置在 `1` （最快，压缩较少）到 `9` （最慢，压缩效果最好）之间。默认情况下，使用 `64K` 字节的缓冲区大小和压缩级别 `1`。数据以原子块压缩，日志文件可以在任何时候通过 `"zcat"` 工具解压或读取。

示例：

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

#### NOTE
为了支持 gzip 压缩，Angie 必须使用 zlib 库构建。

文件路径可以包含变量，但这类日志有一些限制：

* 使用工作进程凭据的 [user](https://cn.angie.software//angie/docs/configuration/modules/core.md#user) 应该具有在此类日志目录中创建文件的权限；
* 缓冲不起作用；
* 每次日志写入时都会打开文件，写入后立即关闭。然而，由于可以将频繁使用的文件的描述符存储在缓存中，因此在日志轮转期间，可能会在 [open_log_file_cache](https://cn.angie.software//angie/docs/configuration/modules/http/http_log.md#open-log-file-cache) 指令的 `valid` 参数指定的时间内继续写入旧文件。

`if` 参数启用条件日志记录。如果条件评估为 `"0"` 或空字符串，则不会记录该会话。

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

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

### log_format

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `log_format` name [`escape=``default` | `json` | `none`] string ...;   |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| 默认                                                                                   | —                                                                      |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                                                 |

指定日志格式，例如：

```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"';
```

`escape` 参数允许在变量中设置 `json` 或 `default` 字符转义；默认使用 `default`。`none` 值禁用字符转义。

使用 `default` 时，字符 """、"\\" 以及值小于 32 或大于 126 的字符将被转义为 "\\xXX"。如果未找到变量值，则将记录一个连字符 "-"。

使用 `json` 时，所有在 JSON 字符串中不允许的字符都将被转义：字符 """ 和 "\\" 被转义为 "\\"" 和 "\\\\"，值小于 32 的字符被转义为 "\\n"、"\\r"、"\\t"、"\\b"、"\\f" 或 "\\u00XX"。

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

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

### open_log_file_cache

| [语法](https://cn.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`;   |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 默认                                                                                   | `open_log_file_cache off;`                                                                                             |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                                                                                                         |

定义一个缓存，用于存储名称包含变量的频繁使用日志的文件描述符。该指令具有以下参数：

| `max`      | 设置缓存中描述符的最大数量；当缓存溢出时，关闭最近最少使用（LRU）的描述符。                |
|------------|--------------------------------------------------------|
| `inactive` | 设置缓存描述符在此时间内未被访问后关闭的时间；默认为 10 秒。                       |
| `min_uses` | 设置在 `inactive` 参数定义的时间内文件使用的最小次数，以便让描述符保持在缓存中打开；默认为 1。 |
| `valid`    | 设置检查文件是否仍然以相同名称存在的时间；默认为 60 秒。                         |
| `off`      | 禁用缓存。                                                  |

用法示例：

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