<!-- review: finished -->

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

# Log

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

日志在请求处理结束的 `location` 上下文中写入。如果在请求处理过程中发生了 [内部重定向](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#internal),这可能是与原始位置不同的 `location`。

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

## 配置示例

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

## 指令

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

<a id="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 logs/access.log combined;`<br/>(路径取决于 [构建参数](https://cn.angie.software//angie/docs/installation/sourcebuild.md#paths) `--http-log-path`) |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location, limit_except                                                                                                 |

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

如果使用 `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 combined gzip flush=5m;
```

#### NOTE
要支持日志的 gzip 压缩,Angie 必须使用 zlib 库构建。

文件路径中可以使用变量,但此类日志有一些限制:

* 工作进程运行所使用的凭据的 [用户](https://cn.angie.software//angie/docs/configuration/modules/core.md#user) 必须具有在包含此类日志的目录中创建文件的权限;
* 缓冲不起作用;
* 每次日志写入时打开文件,写入后立即关闭。但是,由于常用文件的描述符可以存储在缓存中,因此在 [open_log_file_cache](#open-log-file-cache) 指令的 valid 参数指定的时间内进行日志轮换时,可能会继续写入旧文件。
* 对于每次日志写入,都会检查请求的根目录是否存在——如果该目录不存在,则不会创建日志。因此 [root](https://cn.angie.software//angie/docs/configuration/modules/http/index.md#root) 和 [access_log](#access-log) 应该在同一配置级别描述:

```nginx
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
```

`if` 参数启用条件日志记录。如果条件评估结果为 `"0"` 或空字符串,则不会记录请求。在以下示例中,响应代码为 2xx 和 3xx 的请求将不会被记录:

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

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

指定日志格式。

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

使用 `default` 时,字符 """、"\\" 以及值小于 32 或大于 126 的字符将被转义为 "\\xXX"。如果未找到变量值,则将连字符 "-" 作为值写入日志。

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

发送到客户端的标头行以前缀 `sent_http_` 开头,例如 `$sent_http_content_range`。

预定义格式 `combined` 始终存在于配置中:

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

| [语法](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)  | http, server, location                                                                                                 |

定义一个缓存,用于存储使用变量指定名称的常用日志的文件描述符。参数:

| `max`      | 设置缓存中描述符的最大数量;当缓存溢出时,最近最少使用 (LRU) 的描述符将被关闭。                     |
|------------|-----------------------------------------------------------------|
| `inactive` | 设置在此时间内未访问缓存描述符后关闭它的时间。<br/>默认为 10 秒。                           |
| `min_uses` | 设置在 `inactive` 参数指定的时间内文件使用的最小次数,之后文件描述符将在缓存中保持打开状态。<br/>默认为 1。 |
| `valid`    | 指定在多长时间后检查文件是否仍以相同名称存在。<br/>默认为 60 秒。                           |
| `off`      | 禁用缓存。                                                           |

使用示例:

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