Apache 模块 mod_log_config
| Description: | 记录对服务器的请求 |
|---|---|
| Status: | Base |
| Module Identifier: | log_config_module |
| Source File: | mod_log_config.c |
Summary
该模块提供了 Client 端请求的灵活日志记录。日志以可自定义的格式写入，并且可以直接写入文件或外部程序。提供有条件的日志记录，以便可以基于请求的 Feature 将各个请求包括在日志中或从日志中排除。
此模块提供了三个指令：TransferLog创建日志文件，LogFormat设置自定义格式，CustomLog一步定义日志文件和格式。 TransferLog和CustomLog伪指令可以在每个服务器中多次使用，以使每个请求都记录到多个文件中。
自定义日志格式
LogFormat和CustomLog伪指令的格式参数是字符串。该字符串用于将每个请求记录到日志文件中。它可以包含复制到日志文件中的 Literals 字符以及 C 样式的控制字符“\n”和“\t”，以表示换行符和制表符。Literals 引号和反斜杠应使用反斜杠转义。
通过在格式字符串中放置“ %”指令来记录请求本身的 Feature，这些指令在日志文件中由以下值代替：
| Format String | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
%% | 百分号。 | |||||||||||||||
%a | 请求的 Client 端 IP 地址(请参阅mod_remoteip模块)。 | |||||||||||||||
%{c}a | 连接的基础对等 IP 地址(请参阅mod_remoteip模块)。 | |||||||||||||||
%A | Local IP-address. | |||||||||||||||
%B | 响应的大小(以字节为单位)，不包括 HTTP Headers。 | |||||||||||||||
%b | 响应的大小(以字节为单位)，不包括 HTTP Headers。在 CLF 格式中，当没有字节发送时，即*为'-'而不是 0. | |||||||||||||||
%{VARNAME}C | 发送到服务器的请求中 Cookie VARNAME 的内容。仅完全支持版本 0 Cookie。 | |||||||||||||||
%D | 服务请求所花费的时间(以微秒为单位)。 | |||||||||||||||
%{VARNAME}e | 环境变量 VARNAME 的内容。 | |||||||||||||||
%f | Filename. | |||||||||||||||
%h | 远程主机名。如果HostnameLookups设置为Off，则将记录 IP 地址，这是默认值。如果它仅记录了少数几个主机的主机名，则您可能具有访问控制指令，并按名称提及了它们。参见需要主机文档。 | |||||||||||||||
%{c}h | 类似于%h，但是始终报告底层 TCP 连接的主机名，而不报告诸如mod_remoteip的模块对远程主机名的任何修改。 | |||||||||||||||
%H | 请求协议。 | |||||||||||||||
%{VARNAME}i | 发送到服务器的请求中VARNAME:Headers 行的内容。其他模块(例如mod_headers)所做的更改会对此产生影响。如果您对大多数模块进行了修改之前的请求 Headers 感兴趣，请使用mod_setenvif将 Headers 复制到内部环境变量中，并使用上述%{VARNAME}e记录该值。 | |||||||||||||||
%k | 在此连接上处理的保持活动请求数。如果使用KeepAlive会很有趣，例如，“ 1”表示在初始请求之后的第一个 keepalive 请求，“ 2”表示在第二个请求之后的等等，等等。否则，它始终为 0(表示初始请求)。 | |||||||||||||||
%l | 远程日志名(来自 identd，如果提供)。除非存在mod_ident并将IdentityCheck设置为On，否则这将返回破折号。 | |||||||||||||||
%L | 错误日志中的请求日志 ID(如果没有将此请求记录到错误日志中，则为'-')。查找匹配的错误日志行，以查看导致该错误的请求。 | |||||||||||||||
%m | 请求方法。 | |||||||||||||||
%{VARNAME}n | 来自另一个模块的 Comments VARNAME 的内容。 | |||||||||||||||
%{VARNAME}o | 回复中VARNAME:个标题行的内容。 | |||||||||||||||
%p | 服务请求的服务器的规范端口。 | |||||||||||||||
%{format}p | 服务请求的服务器的规范端口，或服务器的实际端口，或 Client 端的实际端口。有效格式为canonical，local或remote。 | |||||||||||||||
%P | 为请求提供服务的子进程的进程 ID。 | |||||||||||||||
%{format}P | 为请求提供服务的子进程的进程 ID 或线程 ID。有效格式为pid，tid和hextid。 hextid要求 APR 1.2.0 或更高。 | |||||||||||||||
%q | 查询字符串(如果存在查询字符串，则以?开头，否则为空字符串)。 | |||||||||||||||
%r | 第一行要求。 | |||||||||||||||
%R | 生成响应的处理程序(如果有)。 | |||||||||||||||
%s | 状态。对于内部已重定向的请求，这是原始请求的状态。使用%>s作为最终状态。 | |||||||||||||||
%t | 收到请求的时间，格式为[18/Sep/2011:19:18:28 -0400]。最后一个数字表示与格林尼治标准时间的时区偏移量 | |||||||||||||||
%{format}t | 时间，格式为格式，应为扩展的strftime(3)格式(可能已本地化)。如果格式以begin:(默认)开头，则会在请求处理开始时花费时间。如果它以end:开头，则这是写入日志条目的时间，接近请求处理的结尾。除了strftime(3)支持的格式外，还支持以下格式标记：<_ 93> | sec | 自大纪元以来的秒数 | <_ 95> | msec | 自纪元以来的毫秒数 | <_ 97> | usec | 自纪元以来的微秒数 | <_ 99> | msec_frac | 毫秒分数 | <_ 101> | usec_frac | 微秒分数 | <_ 103>这些标记不能互相组合，也不能以相同的格式字符串strftime(3)格式化。您可以改用多个%{format}t令牌。 |
%T | 服务请求所花费的时间，以秒为单位。 | |||||||||||||||
%{UNIT}T | 服务请求所花费的时间，以UNIT给出的时间单位表示。有效单位是ms毫秒，us毫秒和s秒。使用s可以得到与%T相同的结果，但没有任何格式。使用us可以得到与%D相同的结果。在 2.4.13 及更高版本中可以将%T与单位结合在一起。 | |||||||||||||||
%u | 远程用户(如果请求已通过身份验证)。如果返回状态(%s)为 401(未授权)，则可能是伪造的。 | |||||||||||||||
%U | 请求的 URL 路径，不包括任何查询字符串。 | |||||||||||||||
%v | 服务请求的服务器的规范ServerName。 | |||||||||||||||
%V | 根据UseCanonicalName设置的服务器名称。 | |||||||||||||||
%X | 响应完成时的连接状态：<_ 127> | X = | 在响应完成之前，连接已中止。 | <_ 129> | + = | 发送响应后，连接可以保持活动状态。 | <_ 131> | - = | 发送响应后，连接将关闭。 | |||||||
%I | 收到的字节，包括请求和 Headers。不能为零。您需要启用mod_logio才能使用它。 | |||||||||||||||
%O | 发送的字节，包括标题。在极少数情况下，例如在发送响应之前中止请求时，该值可能为零。您需要启用mod_logio才能使用它。 | |||||||||||||||
%S | 传输(接收和发送)的字节(包括请求和 Headers)不能为零。这是％I 和％O 的组合。您需要启用mod_logio才能使用它。 | |||||||||||||||
%{VARNAME}^ti | 发送到服务器的请求中的VARNAME:个预告片行的内容。 | |||||||||||||||
%{VARNAME}^to | 服务器发送的响应中的VARNAME:个预告片行的内容。 |
Modifiers
通过将逗号分隔的状态代码列表紧跟在“％”之后，可以将特定项限制为仅打印具有特定 HTTP 状态代码的响应。状态代码列表之前可以带有“ !”以表示否定。
| Format String | Meaning |
|---|---|
%400,501{User-agent}i | 仅记录User-agent个 400 错误和 501 错误。对于其他状态代码，将记录 Literals 字符串"-"。 |
%!200,304,302{Referer}i | 在所有不“不” *的请求上登录Referer会返回三个指定代码之一，否则返回“ -”。 |
修饰符“ <”和“>”可用于已在内部重定向的请求，以选择应查询原始请求还是最终(分别)请求。默认情况下，%指令%s, %U, %T, %D,和%r会查看原始请求，而其他所有指令都会看最终请求。因此，例如，%>s可用于记录请求的最终状态，而%<u可用于记录在内部重定向到未经身份验证的资源的请求上的原始身份验证用户。
Format Notes
出于安全原因，从版本 2.0.46 开始，使用\xhh序列对%r，%i和%o中的不可打印字符和其他特殊字符进行转义，其中 hh 表示原始字节的十六进制表示形式。此规则的 exceptions 是"和\(通过在前面加反斜杠来转义)，以及所有空格字符(均以其 C 样式符号(\n，\t等)编写)。在 2.0.46 之前的版本中，没有对这些字符串进行转义，因此在处理原始日志文件时必须非常小心。
自从 httpd 2.0 以来，与 1.3 不同，%b和%B格式字符串不代表发送给 Client 端的字节数，而只是代表 HTTP 响应的字节大小(例如，如果 Connecting 止，则该字节数会有所不同，或者如果使用 SSL)。 mod_logio提供的%O格式将记录通过网络发送的实际字节数。
Note
注意：mod_cache被实现为快速处理程序，而不是标准处理程序。因此，当涉及内容缓存时，%R格式字符串将不返回任何处理程序信息。
Examples
一些常用的日志格式字符串是：
-
通用日志格式(CLF)
"%h %l %u %t \"%r\" %>s %b"
-
虚拟主机的通用日志格式
"%v %h %l %u %t \"%r\" %>s %b"
-
NCSA 扩展/组合日志格式
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
-
引用日志格式
"%{Referer}i -> %U"
-
代理(浏览器)日志格式
"%{User-agent}i"
您可以多次使用%{format}t指令，以使用诸如msec_frac之类的扩展格式标记来构建时间格式：
-
时间戳(包括毫秒)
"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"
Security Considerations
请参阅security tips文档，以详细了解如果启动日志的用户以外的任何人都可写日志文件存储目录的原因，那么为什么安全性会受到损害。
BufferedLogs Directive
| Description: | 写入磁盘之前在内存中缓冲日志条目 |
|---|---|
| Syntax: | BufferedLogs On|Off |
| Default: | BufferedLogs Off |
| Context: | server config |
| Status: | Base |
| Module: | mod_log_config |
BufferedLogs指令使mod_log_config将多个日志条目存储在内存中，然后将它们一起写入磁盘，而不是在每次请求后将它们写入。在某些系统上，这可能导致更有效的磁盘访问并因此获得更高的性能。整个服务器只能设置一次。不能为每个虚拟主机配置它。
Note
应谨慎使用此指令，因为崩溃可能会导致日志数据丢失。
CustomLog Directive
| Description: | 设置日志文件的文件名和格式 |
|---|---|
| Syntax: | CustomLog file|pipe format|nickname [env=[!]environment-variable| expr=expression] |
| Context: | 服务器配置，虚拟主机 |
| Status: | Base |
| Module: | mod_log_config |
CustomLog伪指令用于将请求记录到服务器。指定了日志格式，并且可以选择使用环境变量将日志设置为基于请求 Feature 的条件。
第一个参数指定要写入日志的位置，它可以采用以下两种类型之一：
-
file
- 相对于ServerRoot的文件名。
-
pipe
- 管道字符“
|”，后跟程序的路径，以在其标准 Importing 上接收日志信息。有关更多信息，请参见piped logs上的 Comments。
- 管道字符“
Security:
如果使用了程序，则它将以启动httpd的用户身份运行。如果服务器是由 root 启动的，那么它将是 root；否则，它将是 root。确保程序安全。
Note
在非 Unix 平台上 Importing 文件路径时，即使平台可能允许使用反斜杠，也应确保仅使用正斜杠。通常，在整个配置文件中始终使用正斜杠是一个好主意。
第二个参数指定将写入日志文件的内容。它可以指定由先前的LogFormat指令定义的昵称，也可以是log formats部分中所述的显式格式字符串。
例如，以下两组指令具有完全相同的效果：
# 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"
第三个参数是可选的，它控制是否记录特定请求。条件可以是服务器environment中特定变量的存在或不存在(在'env=!name'子句的情况下)。或者，该条件可以表示为任意布尔expression。如果不满足条件，则不会记录该请求。在表达式中对 HTTP Headers 的引用不会导致 Headers 名称被添加到 Vary Headers 中。
可以使用mod_setenvif和/或mod_rewrite模块针对每个请求设置环境变量。例如，如果要在单独的日志文件中而不是在主日志中记录对服务器上所有 GIF 图像的请求，则可以使用：
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 Directive
| Description: | 设置日志文件的文件名和格式 |
|---|---|
| Syntax: | GlobalLogfile|pipe format|nickname [env=[!]environment-variable| expr=expression] |
| Context: | server config |
| Status: | Base |
| Module: | mod_log_config |
| Compatibility: | 在 Apache HTTP Server 2.4.19 和更高版本中可用 |
GlobalLog指令定义由主服务器配置和所有定义的虚拟主机共享的日志。
GlobalLog指令与CustomLog指令相同，不同之处在于：
-
GlobalLog在虚拟主机上下文中无效。 -
GlobalLog由定义自己的CustomLog的虚拟主机使用，与全局指定的CustomLog不同。
LogFormat Directive
| Description: | 描述在日志文件中使用的格式 |
|---|---|
| Syntax: | LogFormat format|nickname [nickname] |
| Default: | LogFormat "%h %l %u %t \"%r\" %>s %b" |
| Context: | 服务器配置，虚拟主机 |
| Status: | Base |
| Module: | mod_log_config |
该伪指令指定访问日志文件的格式。
LogFormat指令可以采用以下两种形式之一。在第一种形式中，仅指定了一个参数，此伪指令设置日志格式，该格式将由后续TransferLog伪指令中指定的日志使用。单个参数可以指定一种显式格式，如上面的自定义日志格式部分所述。或者，它可以使用昵称来引用先前的LogFormat指令中定义的日志格式，如下所述。
LogFormat指令的第二种形式将显式格式与昵称相关联。然后，可以在后续的LogFormat或CustomLog指令中使用此昵称，而不必重复整个格式字符串。定义昵称的LogFormat指令 无其他作用 -也就是说，仅定义了昵称，它实际上并不应用格式并将其设置为默认格式。因此，它不会影响后续的TransferLog指令。此外，LogFormat不能使用一个昵称来定义另一个昵称。请注意，昵称不应包含百分号(%)。
Example
LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
TransferLog Directive
| Description: | 指定日志文件的位置 |
|---|---|
| Syntax: | TransferLog file|pipe |
| Context: | 服务器配置，虚拟主机 |
| Status: | Base |
| Module: | mod_log_config |
该伪指令的参数和作用与CustomLog伪指令完全相同，不同之处在于它不允许显式指定日志格式或不允许有条件地记录请求。相反，日志格式由最近指定的LogFormat指令(未定义昵称)确定。如果未指定其他格式，则使用“通用日志格式”。
Example
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log
