緣起

近來(lái)因?yàn)楣卷?xiàng)目需要，閱讀了一部分ATS logging system的源碼實(shí)現(xiàn)，越發(fā)覺(jué)得logs_xml.config文件的配置非常重要，而我目前只是實(shí)踐了一點(diǎn)它的皮毛。為此，根據(jù)自己的理解，翻譯了官網(wǎng)的這篇文檔，以作備忘。

logs_xml.config文件定義了自定義日志文件格式，過(guò)濾器和處理選項(xiàng)。文件格式采用xml。

文件格式
logs_xml.config文件包含下面的規(guī)范：
LogFormat指定了來(lái)自每個(gè)protocol event access的field
LogFilter指定了使用這些過(guò)濾器去包含或是排除某些將要記錄的日志log entry
LogObject指定了一個(gè)日志對(duì)象，它包含特定的格式，本地文件名，過(guò)濾器和審計(jì)服務(wù)器等
logs_xml.config文件忽略空白符，空行，和注釋。

日志格式LogFormat
下面的列表給出了LogFormat規(guī)范：
<Name = "valid_format_name"/>
指定日志格式的名稱。要求是除squid，common，extended或是extend2等預(yù)定義格式之外的任何合法名稱，該tag沒(méi)有默認(rèn)值。
LogFormat對(duì)象需要在LogObject對(duì)象之上定義
<Format = "valid_format_specification"/>
指定日志格式規(guī)范，合法的格式規(guī)范是一個(gè)printf風(fēng)格的字符串，當(dāng)格式化為ASCII輸出時(shí)用來(lái)描述每條日志
printf風(fēng)格可以接受八進(jìn)制/十六進(jìn)制Oct/Hex轉(zhuǎn)義表示
\abc 是8進(jìn)制序列，a,b,c是[0-9]中的一個(gè)數(shù)，并且 (a*8^2 + b*8 + c)在[0,255]中
\xab 是16進(jìn)制序列，a,b,c是[0-9, a-f, A-F]中的一個(gè)數(shù)，并且 (a*16 + b)在[0,255]中
使用%<field>作為合法域名的占位符，詳情參見(jiàn)自定義日志字段
https://docs.trafficserver.apache.org/en/latest/admin/event-logging-formats.en.html#custom-logging-fields

指定的field可以是下面的類型之一：
簡(jiǎn)單類型：比如%<cqu>
容器類型：field包含在容器中，比如一個(gè)HTTP header或是一個(gè)統(tǒng)計(jì)量，形如%<{field} container>，比如%<{User-Agent}cqh>
聚合類型：比如計(jì)數(shù)，求和，平均，取首字段，取尾字段，形如%<operator (field)>
注意：
你不能生成一個(gè)既包含聚合運(yùn)算aggregate operators又包含普通類型regular fields的格式規(guī)范。

<Interval = "aggregate_interval_secs"/>
當(dāng)日志格式中包含聚合運(yùn)算時(shí)可選該tag，值"aggregate_interval_secs"表示單個(gè)aggregate value之間間隔的秒數(shù)
聚合運(yùn)算包括COUNT，SUM，AVG，FIRST，LAST

日志過(guò)濾器LogFilter
下面的列表給出了LogFilter規(guī)范：
<Name = "valid_filter_name"/>
要求所有的過(guò)濾器唯一命名

<Condition = "valid_log_field valid_operator valid_comparison_value"/>
要求該域包含下列元素
valid_log_field
將與給定值比較的field，詳情參見(jiàn)日志格式交叉引用
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相同（區(qū)分大小寫），為真
CASE_INSENSITIVE_MATCH 除了不區(qū)分大小寫外，同MATCH
CONTAIN 假如field包含value，或說(shuō)value是field的子字符串，為真
CASE_INSENSITIVE_CONTAIN ?除了不區(qū)分大小寫外，同CONTAIN
valid_comparison_value
與field類型匹配的任意字符串或整數(shù)，如果是整數(shù)，所有的運(yùn)算都是等價(jià)的，該field必須等于給定值

對(duì)IP的fields，可以是IP地址列表和包括范圍range.
一個(gè)range就是一個(gè)IP地址，后跟-，然后是同域的IP地址，比如10.0.0.0-10.255.255.255

注意
不支持否定比較運(yùn)算符negative comparison operators，假如想指定否則條件，可以對(duì)REJECT記錄使用Action field

<Action = "valid_action_field"/>
要求是ACCEPT or REJECT or WIPE_FIELD_VALUE
ACCEPT or REJECT指示ATS要么接收要么拒絕滿足filter條件的記錄。WIPE_FIELD_VALUE會(huì)清除條件中指定的url中query參數(shù)所含的值。
注意：
1.WIPE_FIELD_VALUE行為只應(yīng)用于query部分的參數(shù)；
2.多個(gè)參數(shù)可以列在單個(gè)WIPE_FIELD_VALUE過(guò)濾器中；
3.假如query部分相同參數(shù)不止出現(xiàn)一次，只有第一次出現(xiàn)的值會(huì)清除

日志對(duì)象LogObject
下面的列表給出了LogObject規(guī)范：
<Format = "valid_format_name"/>
要求合法的日志格式名稱，包括預(yù)定義日志格式：squid, common, extended, and extended2，以及以前定義的自定義日志格式。
該tag沒(méi)有默認(rèn)值。LogFormat對(duì)象必須在LogObject對(duì)象上面定義好。

<Filename = "file_name"/>
對(duì)應(yīng)日志文件的名稱，該日志文件將寫到本地磁盤或是遠(yuǎn)程審計(jì)服務(wù)器remote collation server。
假如你沒(méi)有指定該tag，將沒(méi)有本地日志文件生成。所有的文件名都相當(dāng)于默認(rèn)的日志系統(tǒng)目錄。
假如文件名沒(méi)有包括擴(kuò)展名，比如squid，默認(rèn)對(duì)ASCII日志添加.log后綴，對(duì)二進(jìn)制日志添加.blog后綴，如果不想默認(rèn)添加后綴，可以在文件名后面添加一個(gè).,比如squid.

<Mode = "valid_logging_mode"/>
可選的合法日志模式包括ascii , binary , 和ascii_pipe，默認(rèn)ascii
使用ascii去生成human-readable形式的event log files
使用binary去生成二進(jìn)制日志文件，它系統(tǒng)負(fù)載低，磁盤空間占用少（依據(jù)記錄的日志信息），但是你必須使用traffic_logcat工具來(lái)將二進(jìn)制文件轉(zhuǎn)換為可讀的ascii格式的日志文件
使用ascii_pipe將log記錄寫到UNIX命名管道（內(nèi)存中的一個(gè)buffer），其他進(jìn)程然后能用標(biāo)準(zhǔn)I/O函數(shù)來(lái)讀取數(shù)據(jù)。
使用該選項(xiàng)的好處是，ATS無(wú)須寫磁盤，這減輕了其他任務(wù)對(duì)磁盤和帶寬占用的壓力，另外，寫pipe不會(huì)因?yàn)榇疟P空間耗盡而停止，因?yàn)閜ipe不利用磁盤空間
假如你使用審計(jì)服務(wù)器，log將會(huì)寫到你審計(jì)服務(wù)器的管道中，本地管道甚至在transaction處理之前就生成好了，所以你在ATS一啟動(dòng)后就看到pipe，審計(jì)服務(wù)器上的pipe是ATS啟動(dòng)后創(chuàng)建的。

<Filters = "list_of_valid_filter_names"/>
可選項(xiàng)，是以前定義的日志過(guò)濾器名字列表，逗號(hào)分隔，假如定義了多個(gè)過(guò)濾器，對(duì)要記錄的一條日志，所有的過(guò)濾器必須都要滿足，過(guò)濾器LogFilter需要在LogObject之前定義好

<Protocols = "list_of_valid_protocols"/>
可選項(xiàng)，該日志對(duì)象可以記錄的協(xié)議列表，逗號(hào)分隔，目前合法的協(xié)議名是http，ftp已經(jīng)過(guò)時(shí)了

<ServerHosts = "list_of_valid_servers"/>
可選項(xiàng)，合法hostname列表，逗號(hào)分隔，該tag指定了只有來(lái)自給定服務(wù)器的日志記錄才會(huì)記錄

<CollationHosts = "list_of_valid_hostnames:port|failover hosts"/>
可選項(xiàng)，審計(jì)服務(wù)器列表，逗號(hào)分隔，包括pipe受限時(shí)故障轉(zhuǎn)移服務(wù)器，該對(duì)象的所以日志將會(huì)轉(zhuǎn)發(fā)到這些審計(jì)服務(wù)器
審計(jì)服務(wù)器可以使用name或是IP address指定，審計(jì)端口號(hào)在name后加冒號(hào)指定。比如，
host1:5000|failhostA:5000|failhostB:6000, host2:6000，
日志將會(huì)發(fā)送到host1和host2，failhostA和failhostB充當(dāng)host1的故障轉(zhuǎn)移主機(jī)，當(dāng)host斷開(kāi)后，日志將會(huì)發(fā)送到failhostA,假如failhostA斷開(kāi)，日志記錄將會(huì)發(fā)送到failhostB，直至host1或failhostA復(fù)活之前。

<Header = "header"/>
可選項(xiàng)，你想日志文件包含的header text，它出現(xiàn)在日志文件開(kāi)頭，在第一條日志記錄之前

<RollingEnabled = "truth value"/>
可選項(xiàng)，是否啟用該LogObject的日志文件回滾。該設(shè)置會(huì)重寫records.config文件中的
proxy.config.log.rolling_enabled?
配置項(xiàng)，可選值如下：
0 ?禁用特定LogObject對(duì)象的回滾
1 ?在每天中的指定間隔回滾日志文件，你需要使用RollingIntervalSec和RollingOffsetHr fields指定時(shí)間間隔
2 ?當(dāng)日志文件達(dá)到一定大小時(shí)回滾日志文件，使用RollingSizeMb field指定大小
3 ?當(dāng)日志文件到達(dá)指定時(shí)間間隔或指定大小時(shí)回滾，誰(shuí)先滿足就按誰(shuí)回滾
4 ?當(dāng)日志文件達(dá)到指定大小時(shí)，在指定時(shí)間間隔時(shí)回滾日志文件

<RollingIntervalSec = "seconds"/>
可選項(xiàng)，回滾LogObject之間的時(shí)間間隔，對(duì)不同的LogObject可以指定不同的回滾間隔
該選項(xiàng)會(huì)重寫records.config配置文件中的 proxy.config.log.rolling_interval_sec?

<RollingOffsetHr = "hour"/>
可選項(xiàng)，讓日志文件在某小時(shí)(從0到23)回滾，回滾可能提前開(kāi)始，但是生成回滾文件將在那時(shí)候。設(shè)置時(shí)需要注意是否回滾間隔比一小時(shí)大。
該選項(xiàng)會(huì)重寫records.config配置文件中的 proxy.config.log.rolling_offset_hr?

<RollingSizeMb = "size_in_MB"/>
可選項(xiàng)，設(shè)置回滾日志大小

示例
下面是LogFormat規(guī)范的一個(gè)例子，它使用3個(gè)普通fields來(lái)收集信息
<LogFormat>
? ? <Name="minimal"/>
? ? <Format = "%<chi> : %<cqu> : %<pssc>"/>
</LogFormat>

下面是LogFormat規(guī)范的一個(gè)例子，它用到了aggregate運(yùn)算
<LogFormat>
? ? <Name = "summary"/>
? ? <Format = "%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>"/>
? ? <Interval = "10"/>
</LogFormat>

下面是LogFilter的一個(gè)例子，它只記錄REFRESH_HIT的日志
<LogFilter>
? ? ?<Name = "only_refresh_hits"/>
? ? ?<Action = "ACCEPT"/>
? ? ?<Condition = "%<pssc> MATCH REFRESH_HIT"/>
</LogFilter>

注意：
當(dāng)在過(guò)濾條件中指定field時(shí)，可以省略%<>，這意味著下面的過(guò)濾器和上面的例子相同
<LogFilter>
? ? <Name = "only_refresh_hits"/>
? ? <Action = "ACCEPT"/>
? ? <Condition = "pssc MATCH REFRESH_HIT"/>
</LogFilter>

下面是LogFilter的一個(gè)例子，它會(huì)將cquc(client_req_unmapped_url_canonical)中passwd子field的值清除
<LogFilter>
? ? <Name = "wipe_password"/>
? ? <Condition = "cquc CONTAIN passwd"/>
? ? <Action = "WIPE_FIELD_VALUE"/>
</LogFilter>

下面是LogObject的一個(gè)例子，它將生成早前定義的minimal format的本地文件，該日志文件名為minimal.log,
因?yàn)樗茿SCII日志文件(默認(rèn))
<LogObject>
? ? <Format = "minimal"/>
? ? <Filename = "minimal"/>
</LogObject>

下面是LogObject的一個(gè)例子，它只包含域名company.com或server.somewhere.com服務(wù)的HTTP請(qǐng)求，
日志記錄被發(fā)送到審計(jì)服務(wù)器logs.company.com的4000端口，和審計(jì)服務(wù)器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報(bào)告工具分析ATS日志。下面在logs_xml.config中
提供了一個(gè)兼容WEFL的預(yù)定義LogFormat，為了生成WELF格式的日志文件，使用下面預(yù)定義的LogFormat來(lái)生成一個(gè)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>

下面是源碼中給出的一個(gè)比較完整的配置文件截圖

參考文獻(xiàn)
[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配置文件注釋

總結(jié)

以上是生活随笔為你收集整理的ATS 5.3.0中自定义日志格式文件logs_xml.config解读的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。