Log Service預設將整條日誌以原始形式存入 content 欄位,無論其來源是純文字還是結構化資料(如 JSON)。雖然您可以通過全文檢索搜尋訪問其中的資訊,但若希望高效地按欄位進行查詢、統計或可視化,就需要藉助解析外掛程式,將內容提取為結構化的索引值對(Key-Value)。解析外掛程式不僅支援對 content 欄位進行解析,還能對任意欄位(例如 message 中嵌套的子日誌)執行進一步解析。您只需指定新的解析目標欄位,並選擇適合該內容格式的解析外掛程式即可。
資料解析效果樣本
以常見的應用列印文本日誌為例,直觀瞭解使用資料解析外掛程式前後的差異。
不使用解析外掛程式
未經任何處理的原始日誌,儲存到Log Service後所有資訊都混雜在一個content欄位中,難以直接使用。
Content:"127.0.0.1 - - [16/Aug/2024:14:37:52 +0800] "GET /wp-admin/admin-ajax.php?action=rest-nonce HTTP/1.1" 200 41 "http://www.example.com/wp-admin/post-new.php?post_type=page" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 Edg/127.0.0.0""
使用正則解析外掛程式
使用正則解析外掛程式,原始日誌被精確地提取為多個有意義的欄位,每個欄位都可以被獨立查詢和分析。
body_bytes_sent: 41
http_referer: http://www.example.com/wp-admin/post-new.php?post_type=page
http_user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; ×64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 Edg/127.0.0.0
remote_addr: 127.0.0.1
remote_user: -
request_method: GET
request_protocol: HTTP/1.1
request_uri: /wp-admin/admin-ajax.php?action=rest-nonce
status: 200
time_local: 16/Aug/2024:14:37:52 +0800
如何選擇資料解析外掛程式
-
優先選擇:專用日誌格式解析。
如果您的日誌來源於 Nginx、Apache 或 IIS 等主流服務,請務必優先使用為其量身定製的專用解析模式(Nginx模式解析、Apache模式解析、IIS模式解析)。這不僅能提供“開箱即用”的便捷體驗,免去手動編寫規則的複雜性,也是效能最優、最為可靠的選擇。 -
次選方案:結構化資料解析 (JSON / 分隔字元)
若日誌不屬於上述專用格式,請檢查其是否為結構化或半結構化資料。對於標準的 JSON Object 或由固定分隔字元(如逗號、豎線等)組織的日誌,應選擇JSON解析或分隔字元模式解析。這兩種模式配置直觀、解析速度快,是處理已有結構日誌的理想方案。 -
最終備選:正則解析
僅當您的日誌格式為不規則的非結構化文本,且無法通過以上任何一種模式有效處理時,才推薦使用正則解析。雖然Regex通用性強,能應對幾乎所有複雜的文本匹配需求,但其編寫和調試成本較高,且在高輸送量情境下可能會帶來一定的效能開銷。
功能入口
當需要使用外掛程式處理日誌時,可在建立或修改Logtail配置時,添加外掛程式。
修改Logtail配置時添加外掛程式
在Project列表地區,單擊目標Project。

-
在頁簽中,單擊目標日誌庫前面的>,依次選擇。
在目標Logtail配置的操作列,單擊管理Logtail配置。
-
在logtail配置列表中,單擊目標Logtail配置後操作列的管理Logtail配置。
-
單擊頁面上方的編輯,在頁面下方的處理配置地區,新增Logtail外掛程式,然後單擊儲存。
建立Logtail配置時添加外掛程式
-
單擊控制台頁面右側的快速接入數據卡片。
-
在接入數據對話方塊中,單擊任意卡片,按照設定精靈進行操作,在logtail配置的處理配置中添加處理外掛程式。
說明該外掛程式配置與在修改Logtail配置時的外掛程式配置相同。
資料解析外掛程式使用
通用配置參數
以下參數在各資料解析外掛程式中都會出現,其功能和用法是統一的,在後續外掛程式說明中不再贅述。
|
參數名稱 |
說明 |
|
原始欄位 |
解析日誌前,用於存放日誌內容的原始欄位,預設為 |
|
解析失敗時保留原始欄位 |
推薦開啟。當日誌無法被外掛程式成功解析時(例如格式不匹配),此選項能確保原始日誌內容不會丟失,而是被完整保留在指定的原始欄位中。這對於調試和保證資料完整性至關重要。 |
|
解析成功時保留原始欄位 |
選中後,即使日誌解析成功,原始日誌內容也會被保留。通常用於資料核對情境。 |
|
重新命名的原始欄位 |
當開啟解析失敗時保留原始欄位或解析成功時保留原始欄位後,可以使用此參數為保留下來的原始日誌內容指定一個新的欄位名,以避免與原欄位名衝突。 |
正則解析
正則解析外掛程式支援通過Regex提取日誌欄位,並將日誌解析為索引值對形式。靈活性極高,能適應幾乎所有文字格式設定。
配置說明
-
參數說明
除通用配置參數外核心參數如下:
參數名稱
說明
Regex
用於匹配日誌的Regex。
-
若在處理配置中配置了日誌範例,在正則解析處理外掛程式中會出現您配置的日誌範例,支援通過自動或手動輸入行首Regex的方式產生Regex。
-
單擊自動生成Regex,然後在日誌範例文字框中,劃選需提取的日誌內容,單擊產生正則,Simple Log Service會根據劃選的內容,產生Regex。
-
單擊手動輸入規則運算式,輸入Regex。配置完成後,單擊驗證即可驗證輸入的Regex是否可以解析、提取目標日誌內容。更多資訊,請參見如何調試Regex。
-
-
若未配置日誌範例,需根據實際日誌輸入Regex。
日志提取欄位
為提取到的日誌內容(Value),設定對應的欄位名(Key)。
-
-
配置樣本
-
輸入日誌
127.0.0.1 - - [16/Oct/2023:12:36:49 +0800] "GET /index.html HTTP/1.1" 200 612 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36" -
外掛程式配置
參考功能入口配置,其中,Regex為
(\S+)\s-\s(\S+)\s\[([^]]+)]\s"(\w+)\s(\S+)\s([^"]+)"\s(\d+)(\s\d+)[^-]+([^"]+)"\s"([^"]+).*。配置原始欄位為
content,日誌範例中填入一條 Nginx access log。Regex解析後,日誌提取欄位包含 remote_addr、remote_user、time_local、request_method、request_uri、request_protocol、status、body_bytes_sent、http_referer、http_user_agent 等 Key-Value 對。底部解析失敗時保留原始欄位和解析成功時保留原始欄位兩個選項均未勾選。 -
解析結果經過Regex解析後,該條日誌被結構化提取為以下欄位:
remote_addr、remote_user、time_local、request_method、request_uri、request_protocol、status、body_bytes_sent、http_referer、http_user_agent,各欄位值與輸入日誌中對應位置的內容一致。
-
JSON解析
JSON解析外掛程式支援將Object類型的JSON日誌結構化,解析為索引值對形式。
使用限制
JSON日誌包含Object類型(索引值對的集合)和Array類型(值的有序列表)。JSON解析外掛程式預設僅提取JSON Object的首層索引值對;不支援直接解析JSON Array,若有相關需求請參考如何處理複雜JSON。
配置說明
-
參數說明
除通用配置參數外無需額外參數配置。
-
配置樣本
-
輸入日誌
{"url": "POST /PutData?Category=YunOsAccountOpLog&AccessKeyId=U0Ujpek********&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=pD12XYLmGxKQ%2Bmkd6x7hAgQ7b1c%3D HTTP/1.1", "ip": "10.200.98.220", "user-agent": "aliyun-sdk-java", "request": {"status": "200", "latency": "18204"}, "time": "05/Jan/2020:13:30:28"} -
外掛程式配置
參考功能入口配置。在Processor 處理器配置彈窗中,處理器類型選擇JSON解析,原始欄位填寫
content,解析失敗時保留原始欄位和解析成功時保留原始欄位複選框均不勾選,進階參數保持關閉,單擊確認。 -
解析結果
url: POST /PutData?Category=YunOsAccountOpLog&AccessKeyId=U0Ujpek********&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=pD12XYLmGxKQ%2Bmkd6x7hAgQ7b1c%3D HTTP/1.1 ip: 10.200.98.220 user-agent: aliyun-sdk-java request: {"status": "200", "latency": "18204"} time: 05/Jan/2020:13:30:28
-
分隔字元模式解析
分隔字元模式解析外掛程式支援通過分隔字元將日誌內容結構化,解析為多個索引值對形式。
配置說明
-
參數說明
除通用配置參數外核心參數如下:
參數
描述
分隔符號
請根據日誌內容選擇正確的分隔字元,例如豎線(|)。
說明指定分隔字元為不可見字元時,需要尋找不可見字元在ASCII碼中對應的十六進位數,輸入的格式為
0x<不可見字元在ASCII碼中對應的十六進位數>。例如ASCII碼中排行為1的不可見字元為0x01。引用符
當日誌欄位內容中包含分隔字元時,需指定引用符進行包裹,被引用符包裹的內容會被Simple Log Service解析為一個完整欄位。請根據日誌格式選擇正確的引用符。
說明指定引用符為不可見字元時,需要尋找不可見字元在ASCII碼中對應的十六進位數,輸入的格式為
0x<不可見字元在ASCII碼中對應的十六進位數>。例如ASCII碼中排行為1的不可見字元為0x01。日誌抽取欄位
-
配置了日誌範例時,Simple Log Service會根據日誌範例及選擇的分隔字元提取日誌內容,並將其定義為Value,需為各個Value指定對應的Key。
-
未配置日誌範例時,無Value列表,需要根據實際日誌及分隔字元情況,輸入對應的Key。
Key只能包括字母、數字或底線(_),且只能以字母或底線(_)開頭。最大長度為128位元組。
允許部分欄位
日誌中提取出的Value數量小於Key數量,是否上傳日誌到Simple Log Service。選中允許部分欄位表示上傳。
例如日誌為
11|22|33|44,分隔字元為豎線(|),Key為A、B、C、D和E。-
如果選中允許部分欄位,則
E欄位的Value為空白,該日誌將被上傳到Simple Log Service。 -
如果未選中允許部分欄位,該日誌會被丟棄。
說明Linux Logtail 1.0.28及以上版本或Windows Logtail 1.0.28.0及以上版本支援配置分隔字元模式的允許部分欄位參數。
處理超出欄位方式
日誌中提取的Value數量大於Key數量時的處理方法。
-
展開:保留多餘的Value內容,分別添加到
__column$i__格式的欄位中,其中$i代表多餘欄位序號,從0開始計數。例如__column0__、__column1__。 -
保留:保留多餘的Value內容,並整體添加到名為
__column0__的欄位中。 -
丟棄:丟棄多餘的Value內容。
-
-
配置樣本
-
樣本一:單字元分隔字元
-
輸入日誌
05/May/2025:13:30:28,10.10.*.*,"POST /PutData?Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=******************************** HTTP/1.1",200,18204,aliyun-sdk-java -
外掛程式配置
參考功能入口配置,分隔字元使用半形逗號(,)且引用符為雙引號(")。
說明分隔字元:通過分隔字元分割日誌,例如定位字元(\t)、豎線(|)、空格、半形逗號(,)、半形分號(;)和不可見字元等單字元。分隔字元不支援為雙引號(")。
若雙引號(")作為欄位內容出現,需要進行轉義,即在日誌中處理為
""。Simple Log Service解析欄位時會自動還原,將""還原為"。例如分隔字元為半形逗號(,),引用符為雙引號("),且日誌欄位內部包含雙引號(")和半形逗號(,),需將包含半形逗號(,)的日誌欄位用引用符包裹,同時將日誌欄位中的雙引號(")轉義為""。處理後的日誌格式為:Chevy,"Venture ""Extended Edition, Very Large""","",該日誌可以被解析為3個欄位:Chevy、Venture "Extended Edition, Very Large"、空欄位。引用符:日誌欄位內容中包含分隔字元時,需指定引用符進行包裹,被引用符包裹的內容會被解析為一個完整欄位。引用符可設定為定位字元(\t)、豎線(|)、空格、半形逗號(,)、半形分號(;)和不可見字元等單字元。
例如分隔字元為半形逗號(,),引用符為雙引號("),日誌為
1997,"ac,moon",3000.00,該日誌被解析為3個欄位:1997、ac,moon、3000.00。 -
解析結果
ip:10.10.*.* request:POST /PutData?Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=******************************** HTTP/1.1 size:18204 status:200 time:05/May/2025:13:30:28 user_agent:aliyun-sdk-java
-
-
樣本二:多字元分隔字元
-
輸入日誌
05/May/2022:13:30:28&&10.200.**.**&&POST /PutData?Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=******************************** HTTP/1.1&&200&&18204&&aliyun-sdk-java -
外掛程式配置
參考功能入口配置,分隔字元使用(&&)且無需修改引用符,引用符預設顯示為雙引號。
重要多字元模式中,分隔字元包括2~3個字元(例如
||、&&&、^_^)。日誌解析根據分隔字元進行匹配,您無需使用引用符對日誌欄位進行包裹。但需要確保日誌欄位內容中不會出現分隔字元的完整匹配,否則會導致欄位誤分割。 -
解析結果
ip:10.200.**.** request:POST /PutData?Category=YunOsAccountOpLog&AccessKeyId=****************&Date=Fri%2C%2028%20Jun%202013%2006%3A53%3A30%20GMT&Topic=raw&Signature=******************************** HTTP/1.1 size:18204 status:200 time:05/May/2022:13:30:28 user_agent:aliyun-sdk-java
-
-
Nginx模式解析
Nginx模式外掛程式支援根據log_format中的定義將日誌內容結構化,解析為多個索引值對形式。
Nginx日誌簡介
配置說明
-
參數說明
除通用配置參數外核心參數如下:
參數名稱
說明
NGINX日志配置
Nginx設定檔中的日誌配置部分,以log_format開頭。例如:
log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$request_time $request_length ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent"';日志提取欄位
根據NGINX日志配置自動提取對應的日誌欄位(Key)。
-
配置樣本
-
輸入日誌
192.168.*.* - - [15/Apr/2025:16:40:00 +0800] "GET /nginx-logo.png HTTP/1.1" 0.000 514 200 368 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.*.* Safari/537.36" -
外掛程式配置
參考功能入口配置,NGINX日誌配置使用如下樣本:生產環境中,此處的
log_format必須與Nginx設定檔(通常位於 /etc/nginx/nginx.conf檔案中)中的定義保持一致。log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" $request_time $request_length'; -
解析結果
body_bytes_sent: 368 http_referer: - http_user_agent : Mozi11a/5.0 (Nindows NT 10.0; Win64; x64) AppleMebKit/537.36 (KHTML, like Gecko) Chrome/131.0.x.x Safari/537.36 remote_addr:192.168.*.* remote_user: - request_length: 514 request_method: GET request_time: 0.000 request_uri: /nginx-logo.png status: 200 time_local: 15/Apr/2025:16:40:00
-
Apache模式解析
Apache模式解析外掛程式支援根據Apache日誌設定檔中的定義將日誌內容結構化,解析為多個索引值對形式。
Apache日誌簡介
配置說明
-
參數說明
除通用配置參數外核心參數如下:
參數名稱
說明
日誌格式
根據Apache日誌設定檔中定義的日誌格式進行選擇,包括common、combined和自訂。
APACHE配置欄位
Apache設定檔中的日誌配置部分,通常以LogFormat開頭。
-
當配置日誌格式為common或combined時,此處會自動填滿對應格式的配置欄位,請確認是否和Apache設定檔中定義的格式一致。
-
當配置日誌格式為自訂時,請根據實際情況填寫,例如
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %D %f %k %p %q %R %T %I %O" customized。
日志提取欄位
根據APACHE配置欄位中的內容自動組建記錄檔欄位(key)。
-
-
配置樣本
-
輸入日誌
192.168.1.10 - - [08/May/2024:15:30:28 +0800] "GET /index.html HTTP/1.1" 200 1234 "https://www.example.com/referrer" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.X.X Safari/537.36" -
外掛程式配置
參考功能入口配置,日誌格式選擇combined。
-
解析結果
http_referer:https://www.example.com/referrer http_user_agent:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.X.X Safari/537.36 remote_addr:192.168.1.10 remote_ident:- remote_user:- request_method:GET request_protocol:HTTP/1.1 request_uri:/index.html response_size_bytes:1234 status:200 time_local:[08/May/2024:15:30:28 +0800]
-
IIS模式解析
IIS模式外掛程式支援根據IIS日誌格式定義將日誌內容結構化,解析為多個索引值對形式。
IIS日誌簡介
配置說明
-
參數說明
除通用配置參數外核心參數如下:
參數名稱
說明
日誌格式
選擇IIS伺服器日誌採用的日誌格式,包括IIS、NCSA和W3C。
IIS配置欄位
-
日誌格式為IIS或NCSA時,Log Service已預設設定了IIS配置欄位。
-
日誌格式為W3C日誌時,設定為IIS設定檔中
logExtFileFlags參數中的內容,例如:logExtFileFlags="Date, Time, ClientIP, UserName, SiteName, ComputerName, ServerIP, Method, UriStem, UriQuery, HttpStatus, Win32Status, BytesSent, BytesRecv, TimeTaken, ServerPort, UserAgent, Cookie, Referer, ProtocolVersion, Host, HttpSubStatus"-
IIS5設定檔預設路徑:
C:\WINNT\system32\inetsrv\MetaBase.bin。 -
IIS6設定檔預設路徑:
C:\WINDOWS\system32\inetsrv\MetaBase.xml。 -
IIS7設定檔預設路徑:
C:\Windows\System32\inetsrv\config\applicationHost.config。
-
日志提取欄位
根據IIS配置欄位中的內容自動組建記錄檔欄位(Key)。
-
-
配置樣本
-
輸入日誌
#Fields: date time s-sitename s-ip cs-method cs-uri-stem cs-uri-query s-port cs-username c-ip cs(User-Agent) sc-status sc-substatus sc-win32-status sc-bytes cs-bytes time-taken -
外掛程式配置
參考功能入口配置,日誌格式選擇IIS。
-
解析結果
c-ip: cs-username cs-bytes: sc-substatus cs-method: cs-method cs-uri-query: cs-uri-query cs-uri-stem: cs-uri-stem cs-username: s-port date: #Fields: s-computername: s-sitename s-ip: s-ip s-sitename: time sc-bytes: sc-status sc-status: c-ip sc-win32-status: cs (User-Agent) time: date time-taken: sc-win32-status
-
常見問題
Regex在測試載入器中正確,為何在Log Service中解析失敗?
請檢查以下常見問題:
-
日誌範例不匹配:確保在Logtail配置中使用的日誌範例與實際採集到的日誌格式完全一致,包括空格和特殊字元。
-
多格式日誌混雜:如果日誌源包含多種格式,單一的Regex可能無法全部匹配。建議開啟解析失敗時保留原始欄位,這樣即使部分日誌解析失敗,未經處理資料也不會丟失,便於後續排查或使用多個Logtail配置分別處理不同格式的日誌。
-
控制台與代碼轉義問題:從代碼中複製的Regex可能包含額外的轉義符(如
\\S+),在Log Service控制台配置時應使用單反斜線(\S+)。
配置資料解析後,如何查詢來自特定檔案的日誌?
採集時Log Service會自動為每條日誌添加一個名為 __tag__:__path__ 的中繼資料欄位,值為日誌的完整源檔案路徑。可在查詢分析語句中使用此欄位進行過濾。例如,查詢所有來自 /var/log/app/error.log 的日誌:* AND __tag__:__path__: /var/log/app/error.log。
修改索引配置後(例如為JSON欄位開啟統計),為何無法查詢到歷史資料?
Log Service的索引修改僅對新寫入的資料生效。對於已存在的歷史資料,需執行重建索引任務,才能使用新的索引配置進行查詢。
JSON日誌格式較複雜(如包含JSONArray)時如何處理?
當日誌欄位是一個JSON數組,且需要將數組中的每個元素拆分成獨立的日誌條目時,標準JSON解析外掛程式無法直接處理。
解決方案:
Log Service提供了展開JSON欄位外掛程式,專門用於處理此類情境。核心功能是“展開”或“拆分”指定的JSON數組欄位。
工作原理:通過指定展開深度,遍曆數組欄位,並將數組中的每個元素作為一條新的日誌產生。原始日誌中的其他欄位(非數群組成員)會被完整地複製到每一條新產生的日誌中。
對比樣本:
-
此操作會增加日誌條數。一條包含N個元素的數組日誌,會變成N條日誌。請在規劃日誌儲存和索引成本時考慮這一情況。
-
展開深度:JSON對象的展開層級。0表示完全展開(預設值),1表示當前層級,以此類推。
|
原始日誌 |
展開深度:0,並使用展開深度作為首碼 |
展開深度:1,並使用展開深度作為首碼 |
|
|
|
日誌格式複雜,既有普通文本,又內嵌了JSON字串,該如何解析?
可以通過組合使用多個外掛程式來解決。Log Service支援使用多個處理外掛程式,將前一個外掛程式的輸出作為後一個外掛程式的輸入進行關聯處理。
情境樣本:
假設應用日誌格式如下,包含時間、記錄層級等文本資訊,以及一個作為訊息體的JSON字串。
2025-11-12 10:30:15 INFO Request details: {"trace_id": "xyz-123", "user_id": 500, "action": "login"}
解析策略:在Logtail配置中按順序添加如下兩個外掛程式,並為第二個外掛程式正確指定原始欄位,就可以處理這種混合格式的日誌。這種鏈式處理的方式同樣適用於其他外掛程式組合。
-
使用正則解析外掛程式,提取出前面的文字欄位,並將內嵌的JSON字串完整地提取到一個獨立的欄位中。結果如下:
{ "log_time": "2025-11-12 10:30:15", "log_level": "INFO", "json_message": {"trace_id": "xyz-123", "user_id": 500, "action": "login"} } -
添加JSON解析外掛程式,將 `json_message` 欄位作為原始欄位,解析JSON欄位內容為其內部的索引值對。結果如下:
{ "log_time": "2025-11-12 10:30:15", "log_level": "INFO", "trace_id": "xyz-123", "user_id": 500, "action": "login" }
相關文檔
-
通過API介面配置Logtail流水線:
-
通過控制台配置處理外掛程式: