Module ngx_http_log

模块 ngx_http_log_module

示例配置
指令
     access_log
     log_format
     open_log_file_cache

ngx_http_log_module 模块按指定格式记录请求日志。

请求日志记录在处理结束的位置上下文中。如果在请求处理过程中发生内部重定向，则可能与原始位置不同。

示例配置

log_format compression '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $bytes_sent '
                       '"$http_referer" "$http_user_agent" "$gzip_ratio"';

access_log /spool/logs/nginx-access.log compression buffer=32k;

指令

语法：	`access_log 路径 [格式 [buffer=大小] [gzip[=级别]] [flush=时间] [if=条件]];` `access_log off;`
默认值：	access_log logs/access.log combined;
上下文：	`http`, `server`, `location`, `if in location`, `limit_except`

设置缓冲日志写入的路径、格式和配置。可以在同一配置级别上指定多个日志。可以通过在第一个参数中指定“syslog:”前缀来配置日志记录到 syslog。特殊值off取消当前级别上的所有access_log指令。如果未指定格式，则使用预定义的“combined”格式。

如果使用了buffer或gzip（1.3.10, 1.2.7）参数之一，将会对日志进行缓冲写入。

缓冲区大小不能超过对磁盘文件的原子写入大小。对于 FreeBSD，此大小为无限制。

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

如果下一个日志行不适合于缓冲区；
如果缓冲的数据比flush参数指定的时间（1.3.10, 1.2.7）旧；
当工作进程正在重新打开日志文件或正在关闭时。

如果使用了gzip参数，则缓冲的数据将在写入文件之前进行压缩。压缩级别可设置为1（最快，压缩最小）到9（最慢，最佳压缩）。默认情况下，缓冲区大小为64K字节，压缩级别设置为1。由于数据是以原子块进行压缩的，因此日志文件可以随时通过“zcat”进行解压缩或读取。

示例：

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

要使gzip压缩生效，nginx 必须使用 zlib 库进行构建。

文件路径可以包含变量（0.7.6+），但此类日志存在一些限制：

使用工作进程的凭证的用户应具有在包含这些日志的目录中创建文件的权限；
缓冲写入不起作用；
每次日志写入时都会打开和关闭文件。但是，由于频繁使用的文件描述符可以存储在缓存中，在open_log_file_cache指令的valid参数指定的时间内，可以继续向旧文件写入
每次日志写入时都会检查请求的根目录的存在性，如果不存在，则不会创建日志。因此，在同一配置级别上同时指定root和access_log是一个好主意：
```
server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...
```

参数if（1.7.0）启用条件日志记录。如果条件评估为“0”或空字符串，则不会记录请求。在下面的示例中，响应代码为2xx和3xx的请求将不会被记录：

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

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

语法：	`log_format 名称 [escape=default\|json\|none] 字符串 ...;`
默认：	log_format combined "...";
上下文：	`http`

指定日志格式。

参数escape（1.11.8）允许在变量中设置json或default字符转义，默认情况下使用default转义。值none（1.13.10）禁用转义。

对于default转义，字符“"”、“\”和其他值小于32（0.7.0）或大于126（1.1.6）的字符会转义为“\xXX”。如果未找到变量值，则将记录一个连字符（“-”）。

对于json转义，所有不允许出现在JSON字符串中的字符都会被转义：字符“"”和“\”会转义为“\"”和“\\”，值小于32的字符会转义为“\n”、“\r”、“\t”、“\b”、“\f”或“\u00XX”。

日志格式可以包含常见变量，以及仅在日志写入时存在的变量：

$bytes_sent: 发送到客户端的字节数
$connection: 连接序列号
$connection_requests: 通过连接进行的当前请求次数（1.1.18）
$msec: 记录写入时的秒数，以毫秒为单位
$pipe: 如果请求是流水线化的，则为“p”，否则为“.”
$request_length: 请求长度（包括请求行、标头和请求正文）
$request_time: 请求处理时间，以秒为单位，毫秒分辨率；从客户端读取第一个字节到发送给客户端最后一个字节后记录写入的时间间隔
$status: 响应状态
$time_iso8601: 以ISO 8601标准格式表示的本地时间
$time_local: 以通用日志格式表示的本地时间

在现代的nginx版本中，变量 $status（1.3.2，1.2.2）、$bytes_sent（1.3.8，1.2.5）、$connection（1.3.8，1.2.5）、$connection_requests（1.3.8，1.2.5）、$msec（1.3.9，1.2.6）、$request_time（1.3.9，1.2.6）、$pipe（1.3.12，1.2.7）、$request_length（1.3.12，1.2.7）、$time_iso8601（1.3.12，1.2.7）和 $time_local（1.3.12，1.2.7）也作为常用变量可用。

发送到客户端的标头行具有前缀“sent_http_”，例如，$sent_http_content_range。

配置始终包括预定义的“combined”格式：

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

语法：	`open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];` `open_log_file_cache off;`
默认：	open_log_file_cache off;
上下文：	`http`, `server`, `location`

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

max: 设置缓存中描述符的最大数量；如果缓存满了，最近最少使用（LRU）的描述符会被关闭
inactive: 设置在此时间内无访问时关闭缓存描述符的时间；默认为10秒
min_uses: 设置由 inactive 参数定义的时间内文件使用的最小次数，以保持缓存中描述符的开启；默认为1
valid: 设置应检查文件是否仍然以相同名称存在的时间；默认为60秒
off: 禁用缓存

使用示例：

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