Apache HTTP服务器 2.0版本
Apache HTTP服务器 2.0版本
| 说明: | 将对服务器发起的请求记录到日志 |
|---|---|
| 状态: | Base |
| 模块名: | log_config_module |
| 源文件: | mod_log_config.c |
本模块提供了灵活的方法将客户请求记录到日志。日志可以以自定义的格式直接写入文件，或者传送到一个外部程序中继续处理。条件日志功能可以实现根据请求的特征来决定一个日志信息是否被包含在最终的日志记录里面。
本模块提供了三个指令：TransferLog 指令用来生成一个日志文件，LogFormat 指令用来设定自定义的日志格式，最后你还可以通过CustomLog 指令来同时完成日志文件和格式的设定。TransferLog 指令和CustomLog 指令在每个服务器上都可以被多次使用，以便将一个请求记录到多个文件中。
LogFormat 指令和CustomLog 指令的格式化参数是一个字符串。这个字符串会在每次请求发生的时候，被记录到日志中去。它可以包含将被原样写入日志的文本字符串以及C语言式样的控制字符"\n"和"\t"以实现回车与换行。文本中的引号和反斜杠应通过\来转义。
请求本身的情况将通过在格式字串中放置各种"%"转义符的方法来记录，它们在写入日志文件时，根据下表的定义进行转换：
| 格 式 | 描述 | ||||||
|---|---|---|---|---|---|---|---|
%% |
百分号（Apache 2.0.44 或更高的版本） | ||||||
%...a |
远端IP地址 | ||||||
%...A |
本地IP地址 | ||||||
%...B |
除HTTP报头外传送的字节数 | ||||||
%...b |
以CLF格式显示的除HTTP报头外的传送字节数，例如：当没有字节传送时显示'-'而不是0。 | ||||||
%...{Foobar}C |
在请求中传送给服务端的cookie Foobar的内容。 | ||||||
%...D |
服务器完成本请求的时间，以毫秒为单位。 | ||||||
%...{FOOBAR}e |
环境变量FOOBAR的值 | ||||||
%...f |
文件名 | ||||||
%...h |
远端主机 | ||||||
%...H |
请求协议 | ||||||
%...{Foobar}i |
发送到服务器的请求报头Foobar的内容。 | ||||||
%...l |
远端登录名（由identd而来，如果支持的话） | ||||||
%...m |
请求的方法 | ||||||
%...{Foobar}n |
从另一个模块来的注解Foobar:。 | ||||||
%...{Foobar}o |
返回时报头的内容Foobar:。 | ||||||
%...p |
服务器提供本请求对应服务的标准端口。 | ||||||
%...P |
为本请求提供服务的子进程的进程ID。 | ||||||
%...q |
查询字串（如果存在由一个?引导，否则返回空串） | ||||||
%...r |
请求的第一行 | ||||||
%...s |
状态。对于内部重定向的请求，这个状态指的是原始请求的状态，--- %...>s则指的是最后请求的状态。 | ||||||
%...t |
时间，用普通日志时间格式（标准英语格式） | ||||||
%...{format}t |
时间，用strftime(3)指定的格式表示的时间。(默认情况下按本地化格式） | ||||||
%...T |
完成请求服务的时间，以秒为单位。 | ||||||
%...u |
远程用户名（根据验证信息而来；如果返回status (%s)为401，可能是假的） | ||||||
%...U |
请求的URL路径，不包含查询串。 | ||||||
%...v |
进行服务的服务器的标准名字ServerName。 | ||||||
%...V |
根据UseCanonicalName指令设定的服务器名称。 | ||||||
%...X |
请求完成时的连接状态：
（在Apache 1.3后来的版本中，这个指令是 | ||||||
%...I |
接收的字节数，包括请求头的数据，并且不能为零。要使用这个指令你必须启用mod_logio模块。 | ||||||
%...O |
发送的字节数，包括请求头的数据，并且不能为零。要使用这个指令你必须启用mod_logio模块。 |
上表中的"..."在实际中可以什么也没有（例如："%h %u %r %s %b"），也可以用来指定条目被包含的条件（如果条件不满足，它会被"-"来替换）。条件是由一个HTTP状态代码的列表来组成的，状态代码前还可以加上"!"前缀。
这样，格式串"%400,501{User-agent}i" 只记录400错误（错误的请求）和501错误（没实现的功能）到User-agent:；
"%!200,304,302{Referer}i"记录任何没有正常返回的请求到Referer:。
注意在处理由%...r、%...i和%...o组成的字串时，不会进行ESC序列的转义。这主要是为了符合通用日志格式（Common Log Format）的要求。这样就使用户能在日志中插入控制字符，因此，在处理原始的日志文件的时候，要特别注意这一点。
一些常见的格式串如下所示：
"%h %l %u %t \"%r\" %>s %b""%v %h %l %u %t \"%r\" %>s %b""%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
\"%{User-agent}i\"""%{Referer}i -> %U""%{User-agent}i"注意对请求提供服务的服务器的正式主机名（ServerName）和侦听端口（Listen）分别由%v和%p来得到。
这一点将忽略UseCanonicalName 指令的设置，因为否则日志分析程序会需要成倍地进行整个虚拟主机算法的运算以决定实际上是哪个服务器在响应请求。
如果日志文件放置的目录对除了启动Apache服务以外的用户可写的话，可能会对系统的安全性造成威胁，具体的讨论请参见安全方面的提示一章。
| 说明: | 设定针对cookies的日志文件名 |
|---|---|
| 语法: | CookieLog filename |
| 上下文: | 服务器配置, 虚拟主机 |
| 状态: | Base |
| 模块: | mod_log_config |
| 兼容性: | 本指令有争议 |
CookieLog 指令设置针对cookies所作的日志记录的文件名。文件是相对ServerRoot目录的。 包含本指令仅仅是为了保持与mod_cookies模块的兼容，并且不推荐使用。
| 说明: | 设定日志的文件名和格式 |
|---|---|
| 语法: | CustomLog file|pipe
format|nickname
[env=[!]environment-variable] |
| 上下文: | 服务器配置, 虚拟主机 |
| 状态: | Base |
| 模块: | mod_log_config |
CustomLog 指令用来对服务器的请求进行日志记录。可以指定日志的格式，也可以使用环境变量根据请求的特征来随意地组织日志。
第一个参数指定了日志记录的位置，可以使用以下两种方式来设定：
ServerRoot 目录。|"后面紧跟着一个程序的路径，这个程序把日志从标准输入设备中读入并处理。
如果这里用到了程序，那个这个程序是以启动httpd的用户来执行的。因此如果启动httpd的用户是root，那这个程序也是以root用户身份来启动的；确认这个程序是安全的。
当在非UNIX平台上输入文件路径的时候，要特别注意即使平台本身是使用反斜杠来分隔路径的，在这里也只能使用斜杠。通常在配置文件里只用斜杠来分隔路径总是不会错的。
第二个参数指定了写入日志文件的内容。它既可以是由前面的LogFormat 指令定义的别名，也可以是直接按日志格式一节所描述的规则定义的格式字符串。
例如：以下两组指令的结果是完全一样的：
# 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"
第三个参数是可选的，它根据服务器上特定的环境变量是否被设置来决定是否对某一特定的请求进行日志记录。如果这个特定的环境变量被设置（在'env=!name'的情况下，没被设置），那么这个请求就被日志所记录。
可以使用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
| 说明: | 定义日志文件里的记录格式 |
|---|---|
| 语法: | LogFormat format|nickname
[nickname] |
| 默认值: | LogFormat "%h %l %u %t \"%r\" %>s %b" |
| 上下文: | 服务器配置, 虚拟主机 |
| 状态: | Base |
| 模块: | mod_log_config |
本指令定义访问日志的记录格式。
LogFormat 指令可以使用两种方式中的一种。在第一种定义方式中，指令只带一个参数，以定义后续的TransferLog 指令中指定的日志内容的日志格式。这唯一的参数可以按上述自定义日志格式所描述的格式来定义。另外它也可以通过下述的方法使用别名来参照预先定义的日志格式。
在LogFormat 指令的第二种定义方式中，将一个直接的格式和一个别名联系起来。这样在后续的LogFormat 或CustomLog 指令中，就不用一再重复整个冗长的格式串。定义别名的LogFormat 指令仅仅用来一个别名，它不做其它任何事情 -- 也就是说，它只是定义了这个别名，它既没有实际应用这个别名，也不是把它设为缺省的格式。因此，它不会影响后续的TransferLog 指令。另外，LogFormat 不能用一个别名来定义另一个别名。注意，别名不能包含百分号（%）。
LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common
| 说明: | 指定日志文件的位置 |
|---|---|
| 语法: | TransferLog file|pipe |
| 上下文: | 服务器配置, 虚拟主机 |
| 状态: | Base |
| 模块: | mod_log_config |
本指令除不允许直接定义日志格式或根据条件进行日志记录外，与CustomLog 指令有完全相同的参数和功能。实际应用中，日志的格式是由最近的非别名定义的LogFormat 指令指定。如果没有定义任何日志格式，则使用通用日志格式。
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
TransferLog logs/access_log