緣起

近來因為公司專案需要，閱讀了一部分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>

下面是原始碼中給出的一個比較完整的配置檔案截圖

參考文獻
[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配置檔案註釋