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

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

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

缘起

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

指定日志格式的名称。要求是除squid，common，extended或是extend2等预定义格式之外的任何合法名称，该tag没有默认值。

LogFormat对象需要在LogObject对象之上定义

指定日志格式规范，合法的格式规范是一个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]中

使用%作为合法域名的占位符，详情参见自定义日志字段

https://docs.trafficserver.apache.org/en/latest/admin/event-logging-formats.en.html#custom-logging-fields

指定的field可以是下面的类型之一：

简单类型：比如%

容器类型：field包含在容器中，比如一个HTTP header或是一个统计量，形如%<{field} container>，比如%<{User-Agent}cqh>

聚合类型：比如计数，求和，平均，取首字段，取尾字段，形如%

注意：

你不能生成一个既包含聚合运算aggregate operators又包含普通类型regular fields的格式规范。

当日志格式中包含聚合运算时可选该tag，值"aggregate_interval_secs"表示单个aggregate value之间间隔的秒数

聚合运算包括COUNT，SUM，AVG，FIRST，LAST

日志过滤器LogFilter

下面的列表给出了LogFilter规范：

要求所有的过滤器唯一命名

要求该域包含下列元素

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

要求是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规范：

要求合法的日志格式名称，包括预定义日志格式：squid, common, extended, and extended2，以及以前定义的自定义日志格式。

该tag没有默认值。LogFormat对象必须在LogObject对象上面定义好。

对应日志文件的名称，该日志文件将写到本地磁盘或是远程审计服务器remote collation server。

假如你没有指定该tag，将没有本地日志文件生成。所有的文件名都相当于默认的日志系统目录。

假如文件名没有包括扩展名，比如squid，默认对ASCII日志添加.log后缀，对二进制日志添加.blog后缀，如果不想默认添加后缀，可以在文件名后面添加一个.,比如squid.

可选的合法日志模式包括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启动后创建的。

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

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

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

可选项，审计服务器列表，逗号分隔，包括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 text，它出现在日志文件开头，在第一条日志记录之前

可选项，是否启用该LogObject的日志文件回滚。该设置会重写records.config文件中的

proxy.config.log.rolling_enabled

配置项，可选值如下：

0 禁用特定LogObject对象的回滚

1 在每天中的指定间隔回滚日志文件，你需要使用RollingIntervalSec和RollingOffsetHr fields指定时间间隔

2 当日志文件达到一定大小时回滚日志文件，使用RollingSizeMb field指定大小

3 当日志文件到达指定时间间隔或指定大小时回滚，谁先满足就按谁回滚

4 当日志文件达到指定大小时，在指定时间间隔时回滚日志文件

可选项，回滚LogObject之间的时间间隔，对不同的LogObject可以指定不同的回滚间隔

该选项会重写records.config配置文件中的 proxy.config.log.rolling_interval_sec

可选项，让日志文件在某小时(从0到23)回滚，回滚可能提前开始，但是生成回滚文件将在那时候。设置时需要注意是否回滚间隔比一小时大。

该选项会重写records.config配置文件中的 proxy.config.log.rolling_offset_hr

可选项，设置回滚日志大小

示例

下面是LogFormat规范的一个例子，它使用3个普通fields来收集信息

: % : %"/>

下面是LogFormat规范的一个例子，它用到了aggregate运算

: % : %"/>

下面是LogFilter的一个例子，它只记录REFRESH_HIT的日志

MATCH REFRESH_HIT"/>

注意：

当在过滤条件中指定field时，可以省略%<>，这意味着下面的过滤器和上面的例子相同

下面是LogFilter的一个例子，它会将cquc(client_req_unmapped_url_canonical)中passwd子field的值清除

下面是LogObject的一个例子，它将生成早前定义的minimal format的本地文件，该日志文件名为minimal.log,

因为它是ASCII日志文件(默认)

下面是LogObject的一个例子，它只包含域名company.com或server.somewhere.com服务的HTTP请求，

日志记录被发送到审计服务器logs.company.com的4000端口，和审计服务器209.131.52.129的5000端口

WEFL

ATS支持WELF(WebTrends Enhanced Log Format)，所以你能使用WebTrends报告工具分析ATS日志。下面在logs_xml.config中

提供了一个兼容WEFL的预定义LogFormat，为了生成WELF格式的日志文件，使用下面预定义的LogFormat来生成一个LogObject。

pri=6

proto=% duration=% sent=% rcvd=%

src=% dst=% dstname=% user=% op=%

arg="%" result=% ref="%<{Referer}cqh>"

agent="%<{user-agent}cqh>" cache=%"/>

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

参考文献

[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配置文件注释

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

更多相关：

qt能使用logback_使用ELK系统分析SpringBoot日志

qt能使用logback_Spring boot使用logback实现日志配置

Go的日志模块glog调研笔记

ATS 5.3.0中按域名生成日志配置文件log_hosts.config解读

linux 删除含有关键词的文件_误删除Linux系统文件了？这个方法教你解决

mysql低权限用户getshell_GetShell的姿势总结

文件系统类型是ntfs无法确定卷版本和状态_硬盘写到一半时断电，文件系统里会发什么？...

python页面跳转中_python web页面跳转

PCL安装常见的错误集合解决方案（一）