mod_log_config
描述: | 记录对服务器的请求 |
状态: | Base |
模块标识符: | log_config_module |
源文件: | mod_log_config.c |
摘要
此模块提供 client 请求的灵活 logging。日志以可自定义的格式编写,可以直接写入文件或外部程序。提供条件 logging,以便可以基于请求的特征在日志中包括或排除各个请求。
该模块提供了三个指令:TransferLog创建 log 文件,LogFormat设置自定义格式,CustomLog定义 log 文件并在一个 step 中格式化。TransferLog
和CustomLog
指令可以在每个服务器中多次使用,以使每个请求记录到多个 files。
自定义 Log 格式
LogFormat和CustomLog指令的 format 参数是 string。此 string 用于 log 每个请求到 log 文件。它可以包含复制到 log files 和 C-style 控制字符“\ n”和“\ t”的文字字符,以表示 new-lines 和制表符。应使用反斜杠转义文字引号和反斜杠。
通过将“%
”指令放在 string 格式中来记录请求本身的特征,这些指令在 log 文件中被值替换,如下所示:
格式化 String | 描述 |
%% | 百分号。 |
%a | Client 请求的 IP 地址(请参阅mod_remoteip模块)。 |
%{c}a | 连接的底层对等 IP 地址(请参阅mod_remoteip模块)。 |
%A | 本地 IP-address。 |
%B | 响应的大小(以字节为单位),不包括 HTTP headers。 |
%b | 响应的大小(以字节为单位),不包括 HTTP headers。在 CLF 格式中,i.e。没有字节发送时,'- '而不是 0。 |
%{VARNAME}C | 发送给服务器的请求中的 cookie VARNAME 的内容。仅完全支持 version 0 cookies。 |
%D | 用于提供请求的 time,以微秒为单位。 |
%{VARNAME}e | 环境变量 VARNAME 的内容。 |
%f | 文件名。 |
%h | Remote 主机名。如果HostnameLookups设置为Off ,则 log IP 地址,这是默认值。如果它仅记录少数主机的主机名,则可能具有通过 name 提及它们的访问控制指令。见Require host 文档。 |
%{c}h | 与%h 类似,但始终报告底层 TCP 连接的主机名,而不是像mod_remoteip这样的模块对 remote 主机名的任何修改。 |
%H | 请求协议。 |
%{VARNAME}i | 发送给服务器的请求中VARNAME: header line(s)的内容。其他模块(e.g .modheaders)所做的更改会影响这一点。如果您对大多数模块修改它之前的请求标头感兴趣,请使用mod_setenvif将标头复制到内部环境变量中,并使用上述%{VARNAME}e 将 value 复制到 log。 |
%k | 此连接上处理的 keepalive 请求数。有趣的是,如果使用活着,那么,例如,'1'表示初始请求后的第一个 keepalive 请求,第二个等等的'2'等等;否则这始终为 0(表示初始请求)。 |
%l | Remote logname(来自 identd,如果提供)。除非mod_ident存在且在 IdentityCheck设置为On ,否则这将_return。 |
%L | 来自错误 log 的请求 log ID(如果没有记录到此请求的错误 log,则为'-')。查找匹配错误 log line 以查看哪些请求导致了什么错误。 |
%m | 请求方法。 |
%{VARNAME}n | 来自另一个模块的 note VARNAME 的内容。 |
%{VARNAME}o | 回复中VARNAME: header line(s 的内容。 |
%p | 服务请求的服务器的规范 port。 |
%{format}p | 服务于请求的服务器的规范 port,或服务器的实际 port,或 client 的实际 port。有效格式为canonical ,local 或remote 。 |
%P | 为请求提供服务的子进程的 process ID。 |
%{format}P | 为请求提供服务的子进程的 process ID 或线程 ID。有效格式为pid ,tid 和hextid 。hextid 要求 APR 1.2.0 或更高。 |
%q | 查询 string(如果查询 string 存在,则前缀为? ,否则为空 string)。 |
%r | 请求的第一行 line。 |
%R | 生成响应的处理程序(如果有)。 |
%s | 状态。对于已内部重定向的请求,这是原始请求的状态。使用%>s 作为最终状态。 |
%t | Time 收到请求,格式为[18/Sep/2011:19:18:28 -0400] 。最后一个数字表示与 GMT 的 timezone 偏移量 |
%{format}t | time,格式给出的形式,应该是扩展的strftime(3) 格式(可能是本地化的)。如果格式以begin: (默认值)开头,则 time 将在请求处理开始时进行。如果它以end: 开头,那么 log 条目被写入时的 time,接近请求处理的结束。除了strftime(3) 支持的格式之外,还支持以下格式标记:sec 自 Epoch 以来的秒数msec 自 Epoch 以来的毫秒数usec 自 Epoch 以来的微秒数%{format}t msec_frac 毫秒分数usec_frac 微秒分数这些令牌不能相互组合或 strftime(3) 格式化为相同的格式 string。您可以使用多个%{format}t 代币。 |
%T | 用于服务请求的 time,以秒为单位。 |
%{UNIT}T | 以UNIT 给出的 time 单位服务请求的 time。有效单位为ms (毫秒),us (微秒)和s (秒)。使用s 给出与%T 相同的结果,没有任何格式;使用us 会得到与%D 相同的结果。在 2.4.13 及更高版本中可以将%T 与单位组合使用。 |
%u | 如果请求已通过身份验证,则远程用户。如果 return status(%s )为 401(未经授权),则可能是假的。 |
%U | 请求的 URL 路径,不包括任何查询 string。 |
%v | 服务请求的服务器的规范服务器名称。 |
%V | 服务器 name 根据UseCanonicalName设置。 |
%X | 响应完成时的连接状态:X =连接在响应完成之前中止。+ =发送响应后,连接可能会保持活动状态。- =发送响应后将关闭连接。 |
%I | 收到的字节数,包括请求和 headers。不能为零。您需要启用mod_logio才能使用它。 |
%O | 发送的字节数,包括 headers。在极少数情况下可能为零,例如在发送响应之前请求被中止。您需要启用mod_logio才能使用它。 |
%S | 传输(接收和发送)的字节,包括请求和 headers,不能为零。这是%I 和%O 的组合。您需要启用mod_logio才能使用它。 |
%{VARNAME}^ti | 发送到服务器的请求中VARNAME: trailer line(s 的内容。 |
%{VARNAME}^to | 从服务器发送的响应中的VARNAME: trailer line(s)的内容。 |
修饰符
通过在“%”之后立即放置 comma-separated 状态代码列表,可以限制特定项目仅打印具有特定 HTTP 状态代码的响应。状态 code 列表可以在“!
”之前指示否定。
格式化 String | 含义 |
%400,501{User-agent}i | 仅在 400 个错误和 501 个错误上记录User-agent 。对于其他状态代码,将记录文字 string "-" 。 |
%!200,304,302{Referer}i | 在没有_return 三个指定代码之一的所有请求上记录Referer ,否则返回“- ”。 |
修饰符“<" and ">”可用于内部重定向的请求,以选择是否应查阅原始或最终(分别)请求。默认情况下,%
指令%s,%U,%T,%D,
和%r
查看原始请求,而所有其他指令查看最终请求。因此,对于 example,%>s
可用于记录请求的最终状态,%<u
可用于在内部重定向到未经身份验证的资源的请求上记录原始身份验证用户。
格式说明
出于安全原因,从,和%r
,%i
和%o
中的其他特殊字符开始使用\xhh
sequences 进行转义,其中 hh 代表原始字节的十六进制表示。此规则的例外是"
和\
,它们通过添加反斜杠和所有空白字符进行转义,这些字符用 C-style 表示法(\n
,\t
等)编写。在 2.0.46 之前的版本中,没有对这些 strings 执行转义,因此在处理原始 log files 时必须非常小心。
由于 httpd 2.0,与 1.3 不同,%b
和%B
格式 strings 不表示发送到 client 的字节数,而只是 HTTP 响应的字节大小(例如,如果连接中止,则会有所不同,或者如果使用 SSL)。mod_logio提供的%O
格式将 log 通过网络发送的实际字节数。
注意:mod_cache实现为 quick-handler 而不是标准处理程序。因此,当涉及内容缓存时,%R
format string 将不会_retret 任何处理程序信息。
例子
一些常用的 log 格式 strings 是:
- Common Log 格式(CLF)
“%h%l%u%t \”%r \“%> s%b” - 使用 Virtual Host 的 Common Log 格式
“%v%h%l%u%t \”%r \“%> s%b” - NCSA extended/combined log 格式
“%h%l%u%t \”%r \“%> s%b \”%{。 176}我\“\”%{。 177}我\“” - Referer log 格式“%{。178}我->%U”
- 代理(浏览器)log 格式
“%{。179}我”
你可以多次使用%{format}t
指令来使用像msec_frac
这样的扩展格式标记来构建 time 格式:
- 时间戳包括毫秒
“%{%d /%b /%Y%T}t。%{。182}t%{%z}t”
安全注意事项
如果存储日志文件的目录可由除启动服务器的用户以外的任何人写入,请参阅安全提示文档以获取有关安全性可能受到危害的原因的详细信息。
BufferedLogs 指令
描述: | 写入磁盘之前 memory 中的缓冲区 log 条目 |
句法: | BufferedLogs On\|Off |
默认: | BufferedLogs Off |
Context: | 服务器配置 |
状态: | Base |
模块: | mod_log_config |
BufferedLogs
指令导致mod_log_config在 memory 中存储多个 log 条目并将它们一起写入磁盘,而不是在每次请求后写入它们。在某些系统上,这可能会导致更高效的磁盘访问,从而提高性能。它可能只为整个服务器设置一次;它不能按 virtual-host 配置。
应谨慎使用此指令,因为崩溃可能会导致 logging 数据丢失。
CustomLog 指令
描述: | Sets 文件名和 log 文件的格式 |
句法: | CustomLog file\|pipe format\|nickname[env=[!]environment-variable\| expr=expression] |
Context: | server config,virtual host |
状态: | Base |
模块: | mod_log_config |
CustomLog
指令用于 log 请求到服务器。指定了 log 格式,并且可以选择使用环境变量使 logging 以请求特征为条件。
第一个参数指定了日志的写入位置,可以采用以下两种值之一:
- 文件
相对于 ServerRoot 的文件名。 - 管
管道符“|”,后跟程序的路径,以接收其标准输入上的 log 信息。有关更多信息,请参阅管道日志上的说明。安全性:如果使用某个程序,那么它将作为启动 httpd 的用户 run。如果服务器是由 root 启动的,那么这将是 root 用户;确保该程序是安全的。注意在 non-Unix 平台上输入文件路径时,应注意确保仅使用正向斜线,即使平台可能允许使用反斜杠。通常,在 configuration files 中始终使用正斜杠是一个很好的 idea。
第二个参数指定将写入 log 文件的内容。它可以指定由前一个LogFormat指令定义的昵称,也可以是log 格式部分中描述的显式格式 string。
对于 example,以下两个_set 指令具有完全相同的效果:
# CustomLog with format nickname LogFormat "%h %l %u %t "%r" %>s %b" common CustomLog "logs/access_log" common # CustomLog with explicit format string CustomLog "logs/access_log" "%h %l %u %t "%r" %>s %b"
第三个参数是可选的,控制是否 log 特定请求。条件可以是服务器环境中特定变量的存在或不存在(在'env=!name
'子句的情况下)。或者,条件可以表示为任意 boolean 表达。如果不满足条件,则不会记录请求。表达式中对 HTTP headers 的引用不会导致标题名称被添加到 Vary 标头中。
可以使用mod_setenvif and/or mod_rewrite模块在 per-request 基础上设置环境变量。例如,如果要在服务器上的所有 GIF 图像的 record 请求在单独的日志文件中但不在主 log 中,则可以使用:
SetEnvIf Request_URI .gif$ gif-image CustomLog "gif-requests.log" common env=gif-image CustomLog "nongif-requests.log" common env=!gif-image
或者,要重现旧 RefererIgnore 指令的行为,您可以使用以下内容:
SetEnvIf Referer example.com localreferer CustomLog "referer.log" referer env=!localreferer
GlobalLog 指令
描述: | Sets 文件名和 log 文件的格式 |
句法: | GlobalLogfile\|pipe format\|nickname[env=[!]environment-variable\| expr=expression] |
Context: | 服务器配置 |
状态: | Base |
模块: | mod_log_config |
兼容性: | 可在 Apache HTTP Server 2.4.19 及更高版本中使用 |
GlobalLog
指令定义主服务器 configuration 和所有已定义的虚拟主机共享的 log。
除了以下区别之外,GlobalLog
指令与CustomLog
指令相同:
GlobalLog
在虚拟 host context 中无效。GlobalLog
由定义自己的CustomLog
的虚拟主机使用,与全局指定的CustomLog
不同。
LogFormat 指令
描述: | 描述在 log 文件中使用的格式 |
句法: | LogFormat format\|nickname[nickname] |
默认: | LogFormat "%h %l %u %t \"%r\"%>s %b" |
Context: | server config,virtual host |
状态: | Base |
模块: | mod_log_config |
该指令指定 access log 文件的格式。
LogFormat
指令可以采用两种形式之一。在第一种形式中,只指定了一个参数,该指令设置 log 格式,该格式将由后续TransferLog
指令中指定的日志使用。单个参数可以指定显式格式,如上面自定义 log 格式部分所述。或者,它可以使用昵称来引用先前LogFormat
指令中定义的 log 格式,如下所述。
LogFormat
指令的第二种形式将显式格式与昵称相关联。然后可以在随后的LogFormat
或CustomLog指令中使用此昵称,而不是重复整个格式 string。定义昵称的LogFormat
指令不会做任何其他事情-也就是说,它只定义昵称,它实际上不应用格式并使其成为默认值。因此,它不会影响后续的TransferLog指令。此外,LogFormat
不能使用一个昵称来定义另一个昵称。请注意,昵称不应包含百分号(%
)。
例
LogFormat "%v %h %l %u %t "%r" %>s %b" vhost_common
TransferLog 指令
描述: | 指定 log 文件的位置 |
句法: | TransferLog file\|pipe |
Context: | server config,virtual host |
状态: | Base |
模块: | mod_log_config |
该指令与CustomLog指令具有完全相同的 arguments 和效果,exception 它不允许显式指定 log 格式或者允许条件 logging 请求。相反,log 格式由最近指定的LogFormat指令确定,该指令未定义昵称。如果未指定其他格式,则使用 Common Log Format。
例
LogFormat "%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-agent}i"" TransferLog logs/access_log