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”格式。

如果使用 buffergzip 参数 (1.3.10, 1.2.7),日志写入将进行缓冲。

缓冲区大小不得超过对磁盘文件进行原子写入的大小。对于 FreeBSD,此大小不受限制。

启用缓冲后,数据将被写入文件

如果使用 gzip 参数,则缓冲数据在写入文件之前会被压缩。压缩级别可以设置为 1(最快,压缩率最低)到 9(最慢,压缩率最高)之间。默认情况下,缓冲区大小为 64K 字节,压缩级别设置为 1。由于数据是以原子块的形式压缩的,日志文件可以随时使用“zcat”进行解压缩或读取。

示例

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

为了使 gzip 压缩工作,nginx 必须使用 zlib 库构建。

文件路径可以包含变量 (0.7.6+),但此类日志有一些限制:

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) 允许在变量中设置 jsondefault 字符转义,默认使用 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
本地时间,Common Log 格式

在现代的 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=时间] [min_uses=N] [valid=时间];
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;