ATS 5.3.0中自定义日志格式文件logs_xml.config解读

清疚 2022-08-04 13:53 244阅读 0赞

**缘起**

近来因为公司项目需要，阅读了一部分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,b,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>

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

![Center][]

**参考文献**  
\[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配置文件注释

[Center]: /images/20220731/613c9b846a8b4b9fb8cad051e7f73a7b.png