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 access_log |
---|---|
默认值 |
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 |
---|---|
默认值 |
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
- 本地时间,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 open_log_file_cache |
---|---|
默认值 |
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;