Module ngx_http_log_module

• Example Configuration
• Directives
  • access_log
  • log_format
  • open_log_file_cache
    

ngx_http_log_module模块以指定格式写入请求日志。

请求记录在处理结束位置的上下文中。如果在请求处理期间发生了internal redirect，则它可能与原始位置不同。

Example Configuration

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;

Directives

Syntax:	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指令。如果未指定格式，则使用 sched 义的“ combined”格式。

如果使用buffer或gzip(1.3.10，1.2.7)参数，则将写入日志。

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

• 如果下一个日志行不适合缓冲区；

• 如果缓冲的数据早于flush参数(1.3.10，1.2.7)指定的数据；

• 当工作进程为re-opening个日志文件或正在关闭时。

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

Example:

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

文件路径可以包含变量(0.7.6)，但是此类日志具有一些约束：

• 工作进程使用其凭据的user应具有在具有此类日志的目录中创建文件的权限；

• 缓冲写不起作用；

• 每次写入日志时都会打开和关闭文件。但是，由于可以将常用文件的 Descriptors 存储在cache中，因此可以在open_log_file_cache指令的valid参数指定的时间内 continue 写入旧文件。

• 在每个日志中写入请求的root directory是否存在，如果不存在，则不创建日志。因此，最好在同一级别上同时指定root和access_log：

server {
    root       /spool/vhost/data/$host;
    access_log /spool/vhost/logs/$host;
    ...

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

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

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

Syntax:	log_format name [escape=default|json|none] string ...;
Default:	log_format combined "...";
Context:	http

指定日志格式。

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

对于default转义，字符“ "”，“ \”以及其他值小于 32(0.7.0)或大于 126(1.1.6)的字符将转义为“ \xXX”。如果找不到变量值，将记录连字符(“ -”)。

对于json转义，将转义 JSON strings中不允许的所有字符：字符“ "”和“ \”转义为“ \"”和“ \\”，值小于 32 的字符转义为“ \n”，“ \r” ，“ \t”，“ \b”，“ \f”或“ \u00XX”。

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

$bytes_sent

• 发送给客户端的字节数

$connection

• 连接序列号

$connection_requests

• 通过连接发出的当前请求数(1.1.18)

$msec

• 日志写入时的时间(以毫秒为单位)，以毫秒为单位

$pipe

• “ p”(如果请求已传递)，否则为“ .”

$request_length

• 请求长度(包括请求行，Headers 和请求正文)

$request_time

• 请求以毫秒为单位的处理时间(以秒为单位)；从客户端读取第一个字节到将最后一个字节发送到客户端后的日志写入之间经过的时间

$status

• response status

$time_iso8601

• ISO 8601 标准格式的当地时间

$time_local

• 通用日志格式的本地时间

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

该配置始终包括 sched 义的“ combined”格式：

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

Syntax:	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

定义一个缓存，该缓存存储名称中包含变量的常用日志的文件 Descriptors。该指令具有以下参数：

• max

  • 设置缓存中 Descriptors 的最大数量；如果缓存已满，则关闭最近最少使用(LRU)Descriptors

• inactive

  • 设置如果在这段时间内没有访问权限，则关闭缓存的 Descriptors 的时间；默认情况下为 10 秒

• min_uses

  • 设置在inactive参数定义的时间内文件使用的最小数量，以使 Descriptors 在缓存中保持打开状态；默认情况下，1

• valid

  • 设置时间，在该时间后应检查文件是否仍然具有相同名称；默认情况下为 60 秒

• off

  • disables caching

Usage example:

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