nginx: http_log_module

语法	access_log path [format [buffer=size [flush=time]] [if=condition]]; access_log path format gzip[=level] [buffer=size] [flush=time] [if=condition]; access_log syslog:server=address[,parameter=value] [format [if=condition]]; access_log off;
默认	access_log logs/access.log combined;
环境	http, server, location, if in location

为带缓冲的日志记录设置路径、格式和配置。

可以同时在同级指定多种记录方式。如果要记录到 syslog，可以在第1个参数前面指定“syslog:”前缀。特殊值“off”可以取消当前级别所有“access_log”的访问日志记录。如果未指定格式，将使用预定义的“combined”格式。

如果既指定了“buffer”参数又指定了“gzip”参数，日志写入将会被缓冲。（缓冲区大小一定不能超出磁盘文件原子写入的最大值。对于FreeBSD，该值不受限。）

当启用缓冲时，若出现以下情况，数据将被写入到文件：

• 下一条日志将使缓冲区溢出；
• 被缓冲的数据要比“flush”参数指定的要旧（1.3.10，1.2.7）；
• 其中一个工作进程“重新打开”日志文件或其正退出。

如果使用了gzip参数，数据在写入文件之前将会被压缩。gzip的压缩级别可以设置为1（最快，压缩度不高）到9（最慢，但压缩度最高）之间。默认情况下，缓冲区大小等于64KB，压缩级别是1。由于数据压缩是基于原子块的，所以日志文件可随时被“zcat”解压或读取。

示例：

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

注：nginx在编译时必须包含了zlib库才能使用gzip压缩。

文件路径可以包含变量（0.7.6+），但这种日志会有一些限制：

• 用来创建工作进程的用户（user）必须有在某文件夹下创建此日志的权限。
• 缓冲写方式无法工作。
• 每一次日志写入操作都将导致文件的打开和关闭。然而，由于频繁使用的文件描述符可以储存到缓存（cache）中，open_log_file_cache指令的参数指定的有效时间内仍可以继续写入。

• 在每次日志写入期间都会检查请求的根目录是否存在，如果不存在，将不会创建日志文件。因此，在同级同时指定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 name string ...
默认	log_format combined "..."
环境	http

指定日志格式。

日志格式可以包含共同使用的变量，这类变量仅在写日志的时候才会存在：

$bytes_sent

已发送给客户端的字节数。

$connection

连接序列号。

$connection_requests

当前连接已产生多少次请求（1.1.18）。

$msec

记录日志的时间（以秒计+毫秒精度）。

$pipe

如果是流水线请求则为“p”，否则为“.”。

$request_length

请求长度（包括请求行、头部、请求主体）。

$request_time

请求的处理时间（以秒计+毫秒精度）。从从客户端读取到第1字节时开始计，到把最后一字节发送给客户端并记录日志后结束。

$status

HTTP响应状态码。

$time_iso8601

ISO 8601标准格式的本地时间。

$time_local

公共日志格式（Common Log Format）的本地时间。

现代版本的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_conent_range.

配置文件总是包含预定义的“combined”格式：

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

语法	open_log_file_cahce 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;