缘起

近来因为公司项目需要，阅读了一部分ATS logging system的源码实现，越发觉得logs_xml.config文件的配置非常重要，而我目前只是实践了一点它的皮毛。为此，根据自己的理解，翻译了官网的这篇文档，以作备忘。

logs_xml.config文件定义了自定义日志文件格式，过滤器和处理选项。文件格式采用xml。

文件格式
logs_xml.config文件包含下面的规范：
LogFormat指定了来自每个protocol event access的field
LogFilter指定了使用这些过滤器去包含或是排除某些将要记录的日志log entry
logobject指定了一个日志对象，它包含特定的格式，本地文件名，过滤器和审计服务器等
logs_xml.config文件忽略空白符，空行，和注释。

日志格式LogFormat
下面的列表给出了LogFormat规范：
<Name = "valid_format_name"/>
指定日志格式的名称。要求是除squid，common，extended或是extend2等预定义格式之外的任何合法名称，该tag没有默认值。
LogFormat对象需要在logobject对象之上定义
<Format = "valid_format_specification"/>
指定日志格式规范，合法的格式规范是一个printf风格的字符串，当格式化为ASCII输出时用来描述每条日志
printf风格可以接受八进制/十六进制Oct/Hex转义表示
\abc 是8进制序列，a,b,c是[0-9]中的一个数，并且 (a*8^2 + b*8 + c)在[0,255]中
\xab 是16进制序列，a,c是[0-9,a-f,A-F]中的一个数，并且 (a*16 + b)在[0,255]中
使用%<field>作为合法域名的占位符，详情参见自定义日志字段
https://docs.trafficserver.apache.org/en/latest/admin/event-logging-formats.en.html#custom-logging-fields

指定的field可以是下面的类型之一：
简单类型：比如%<cqu>
容器类型：field包含在容器中，比如一个HTTP header或是一个统计量，形如%<{field} container>，比如%<{User-Agent}cqh>
聚合类型：比如计数，求和，平均，取首字段，取尾字段，形如%<operator (field)>
注意：
你不能生成一个既包含聚合运算aggregate operators又包含普通类型regular fields的格式规范。

<Interval = "aggregate_interval_secs"/>
当日志格式中包含聚合运算时可选该tag，值"aggregate_interval_secs"表示单个aggregate value之间间隔的秒数
聚合运算包括COUNT，SUM，AVG，FIRST，LAST

日志过滤器LogFilter
下面的列表给出了LogFilter规范：
<Name = "valid_filter_name"/>
要求所有的过滤器唯一命名

<Condition = "valid_log_field valid_operator valid_comparison_value"/>
要求该域包含下列元素
valid_log_field
将与给定值比较的field，详情参见日志格式交叉引用
https://docs.trafficserver.apache.org/en/latest/admin/event-logging-formats.en.html#logging-format-cross-reference
valid_operator_field
下列值之一：MATCH,CASE_INSENSITIVE_MATCH,CONTAIN,CASE_INSENSITIVE_CONTAIN.
MATCH 假如field和value相同（区分大小写），为真
CASE_INSENSITIVE_MATCH 除了不区分大小写外，同MATCH
CONTAIN 假如field包含value，或说value是field的子字符串，为真
CASE_INSENSITIVE_CONTAIN 除了不区分大小写外，同CONTAIN
valid_comparison_value
与field类型匹配的任意字符串或整数，如果是整数，所有的运算都是等价的，该field必须等于给定值

对IP的fields，可以是IP地址列表和包括范围range.
一个range就是一个IP地址，后跟-，然后是同域的IP地址，比如10.0.0.0-10.255.255.255

注意
不支持否定比较运算符negative comparison operators，假如想指定否则条件，可以对REJECT记录使用Action field

<Action = "valid_action_field"/>
要求是ACCEPT or REJECT or WIPE_FIELD_VALUE
ACCEPT or REJECT指示ATS要么接收要么拒绝满足filter条件的记录。WIPE_FIELD_VALUE会清除条件中指定的url中query参数所含的值。
注意：
1.WIPE_FIELD_VALUE行为只应用于query部分的参数；
2.多个参数可以列在单个WIPE_FIELD_VALUE过滤器中；
3.假如query部分相同参数不止出现一次，只有第一次出现的值会清除

日志对象logobject
下面的列表给出了logobject规范：
<Format = "valid_format_name"/>
要求合法的日志格式名称，包括预定义日志格式：squid,common,extended,and extended2，以及以前定义的自定义日志格式。
该tag没有默认值。LogFormat对象必须在logobject对象上面定义好。

<Filename = "file_name"/>
对应日志文件的名称，该日志文件将写到本地磁盘或是远程审计服务器remote collation server。
假如你没有指定该tag，将没有本地日志文件生成。所有的文件名都相当于默认的日志系统目录。
假如文件名没有包括扩展名，比如squid，默认对ASCII日志添加.log后缀，对二进制日志添加.blog后缀，如果不想默认添加后缀，可以在文件名后面添加一个.,比如squid.

<Mode = "valid_logging_mode"/>
可选的合法日志模式包括ascii,binary,和ascii_pipe，默认ascii
使用ascii去生成human-readable形式的event log files
使用binary去生成二进制日志文件，它系统负载低，磁盘空间占用少（依据记录的日志信息），但是你必须使用traffic_logcat工具来将二进制文件转换为可读的ascii格式的日志文件
使用ascii_pipe将log记录写到UNIX命名管道（内存中的一个buffer），其他进程然后能用标准I/O函数来读取数据。
使用该选项的好处是，ATS无须写磁盘，这减轻了其他任务对磁盘和带宽占用的压力，另外，写pipe不会因为磁盘空间耗尽而停止，因为pipe不利用磁盘空间
假如你使用审计服务器，log将会写到你审计服务器的管道中，本地管道甚至在transaction处理之前就生成好了，所以你在ATS一启动后就看到pipe，审计服务器上的pipe是ATS启动后创建的。

<Filters = "list_of_valid_filter_names"/>
可选项，是以前定义的日志过滤器名字列表，逗号分隔，假如定义了多个过滤器，对要记录的一条日志，所有的过滤器必须都要满足，过滤器LogFilter需要在logobject之前定义好

<Protocols = "list_of_valid_protocols"/>
可选项，该日志对象可以记录的协议列表，逗号分隔，目前合法的协议名是http，ftp已经过时了

<ServerHosts = "list_of_valid_servers"/>
可选项，合法hostname列表，逗号分隔，该tag指定了只有来自给定服务器的日志记录才会记录

<CollationHosts = "list_of_valid_hostnames:port|failover hosts"/>
可选项，审计服务器列表，逗号分隔，包括pipe受限时故障转移服务器，该对象的所以日志将会转发到这些审计服务器
审计服务器可以使用name或是IP address指定，审计端口号在name后加冒号指定。比如，
host1:5000|failhostA:5000|failhostB:6000,host2:6000，
日志将会发送到host1和host2，failhostA和failhostB充当host1的故障转移主机，当host断开后，日志将会发送到failhostA,假如failhostA断开，日志记录将会发送到failhostB，直至host1或failhostA复活之前。

<Header = "header"/>
可选项，你想日志文件包含的header text，它出现在日志文件开头，在第一条日志记录之前

<RollingEnabled = "truth value"/>
可选项，是否启用该logobject的日志文件回滚。该设置会重写records.config文件中的
proxy.config.log.rolling_enabled
配置项，可选值如下：
0 禁用特定logobject对象的回滚
1 在每天中的指定间隔回滚日志文件，你需要使用RollingIntervalSec和RollingOffsetHr fields指定时间间隔
2 当日志文件达到一定大小时回滚日志文件，使用RollingSizeMb field指定大小
3 当日志文件到达指定时间间隔或指定大小时回滚，谁先满足就按谁回滚
4 当日志文件达到指定大小时，在指定时间间隔时回滚日志文件

<RollingIntervalSec = "seconds"/>
可选项，回滚logobject之间的时间间隔，对不同的logobject可以指定不同的回滚间隔
该选项会重写records.config配置文件中的 proxy.config.log.rolling_interval_sec

<RollingOffsetHr = "hour"/>
可选项，让日志文件在某小时(从0到23)回滚，回滚可能提前开始，但是生成回滚文件将在那时候。设置时需要注意是否回滚间隔比一小时大。
该选项会重写records.config配置文件中的 proxy.config.log.rolling_offset_hr

<RollingSizeMb = "size_in_MB"/>
可选项，设置回滚日志大小

示例
下面是LogFormat规范的一个例子，它使用3个普通fields来收集信息
<LogFormat>
<Name="minimal"/>
<Format = "%<chi> : %<cqu> : %<pssc>"/>
</LogFormat>

下面是LogFormat规范的一个例子，它用到了aggregate运算
<LogFormat>
<Name = "summary"/>
<Format = "%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>"/>
<Interval = "10"/>
</LogFormat>

下面是LogFilter的一个例子，它只记录REFRESH_HIT的日志
<LogFilter>
<Name = "only_refresh_hits"/>
<Action = "ACCEPT"/>
<Condition = "%<pssc> MATCH REFRESH_HIT"/>
</LogFilter>

注意：
当在过滤条件中指定field时，可以省略%<>，这意味着下面的过滤器和上面的例子相同
<LogFilter>
<Name = "only_refresh_hits"/>
<Action = "ACCEPT"/>
<Condition = "pssc MATCH REFRESH_HIT"/>
</LogFilter>

下面是LogFilter的一个例子，它会将cquc(client_req_unmapped_url_canonical)中passwd子field的值清除
<LogFilter>
<Name = "wipe_password"/>
<Condition = "cquc CONTAIN passwd"/>
<Action = "WIPE_FIELD_VALUE"/>
</LogFilter>

下面是logobject的一个例子，它将生成早前定义的minimal format的本地文件，该日志文件名为minimal.log,
因为它是ASCII日志文件(默认)
<logobject>
<Format = "minimal"/>
<Filename = "minimal"/>
</logobject>

下面是logobject的一个例子，它只包含域名company.com或server.somewhere.com服务的HTTP请求，
日志记录被发送到审计服务器logs.company.com的4000端口，和审计服务器209.131.52.129的5000端口
<logobject>
<Format = "minimal"/>
<Filename = "minimal"/>
<ServerHosts = "company.com,server.somewhere.com"/>
<Protocols = "http"/>
<CollationHosts = "logs.company.com:4000,209.131.52.129:5000"/>
</logobject>

WEFL
ATS支持WELF(WebTrends Enhanced Log Format)，所以你能使用WebTrends报告工具分析ATS日志。下面在logs_xml.config中
提供了一个兼容WEFL的预定义LogFormat，为了生成WELF格式的日志文件，使用下面预定义的LogFormat来生成一个logobject。
<LogFormat>
<Name = "welf"/>
<Format = "id=firewall time=\"%<cqtd> %<cqtt>\" fw=%<phn> pri=6
proto=%<cqus> duration=%<ttmsf> sent=%<psql> rcvd=%<cqhl>
src=%<chi> dst=%<shi> dstname=%<shn> user=%<caun> op=%<cqhm>
arg=\"%<cqup>\" result=%<pssc> ref=\"%<{Referer}cqh>\"
agent=\"%<{user-agent}cqh>\" cache=%<crc>"/>

</LogFormat>

下面是源码中给出的一个比较完整的配置文件截图

参考文献 [1].https://docs.trafficserver.apache.org/en/latest/reference/configuration/logs_xml.config.en.html [2].https://docs.trafficserver.apache.org/en/latest/admin/event-logging-formats.en.html#custom-logging-fields [3].logs_xml.config配置文件注释 原文链接：https://www.f2er.com/xml/296211.html