nginx中文文档-ngx_http_log_module

此页面版本:2016-06-08
ngx_http_log_module模块按指定的格式写请求日志。请求最终处理的location会被记录到日志中,如果在处理请求时产生内部重定向,可能与原始的location不同。

示例配置

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 path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]]
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定义的时间更老
  • 当工作进行执行reopen操作或关闭时

如果使用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 name string
默认:log_format combined “…”
上下文:http

指定日志格式。
日志格式可以包含公用变量,变量只存在于写日志时:

$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

语法: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
设置缓存中描述符的最大数,如果缓存满了,会将最近最少使用的描述符关闭。

inactive
设置在多长时间内没有访问的缓存描述符将被关闭,默认是10秒。

min_uses
设置在inactive参数定义的时间内文件使用的最少次数,默认为1

valid
设置时间用于检查相同文件名是否仍然存在,默认是60秒

off
关闭缓存

使用方法:
open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;