操指南)
維護(hù)日志鏈路的朋友大概率都遇到過(guò)這種場(chǎng)景應(yīng)用明明打的是標(biāo)準(zhǔn)JSON到了Kibana里一看有的字段變成了一長(zhǎng)串嵌套路徑有的關(guān)鍵字段被Filebeat自帶字段覆蓋了還有一堆調(diào)試用的冗余字段把索引空間撐得很大。標(biāo)題里拆出來(lái)的本質(zhì)上是三個(gè)需求去掉JSON日志里的部分屬性、把嵌套JSON拍平、按業(yè)務(wù)需求拆分JSON里的內(nèi)容。這篇就圍繞這三個(gè)問(wèn)題用Filebeat完整走一遍配置、排錯(cuò)和落地思路。先說(shuō)清楚這篇內(nèi)容解決什么不依賴Logstash、不寫ES端復(fù)雜管道盡可能用Filebeat自帶的解析能力和處理器processor完成JSON日志的采集、字段裁剪、扁平化與拆分。適合正在用Elastic Stack做日志平臺(tái)、被同事吐槽“Kibana里字段沒(méi)法看”的開(kāi)發(fā)者也適合剛接手Filebeat、想知道json.keys_under_root和decode_json_fields到底怎么選的新手。1. 項(xiàng)目概述與需求拆解1.1 標(biāo)題背后的三個(gè)核心需求表面看這只是“Filebeat采集JSON日志”但結(jié)合實(shí)際運(yùn)維場(chǎng)景訴求其實(shí)非常具體。第一是“去掉部分屬性”。業(yè)務(wù)日志里經(jīng)?；烊氪罅坎槐匾膬?nèi)容調(diào)試用的堆棧、內(nèi)部上下文字段、請(qǐng)求鏈路里的大對(duì)象。如果全部寫入Elasticsearch存儲(chǔ)成本會(huì)漲索引mapping也會(huì)被這些臟字段撐出一堆動(dòng)態(tài)映射。所以要做字段裁剪。第二是“JSON日志扁平化”。默認(rèn)情況下Filebeat把JSON解析后如果內(nèi)容里還有嵌套對(duì)象進(jìn)入ES后會(huì)形成嵌套結(jié)構(gòu)比如context.orderId、context.userId。這帶來(lái)的問(wèn)題是查詢時(shí)要寫很長(zhǎng)路徑Kibana可視化里字段展示很別扭Painless腳本里取字段也要寫完整路徑。把嵌套路徑拍平成orderId、userId這類頂層字段就是所謂的扁平化。第三是“拆分JSON日志”。這個(gè)詞最容易產(chǎn)生歧義。一種理解是把嵌套對(duì)象里的字段拆出來(lái)變成獨(dú)立頂層字段這其實(shí)和扁平化是一回事另一種理解是日志內(nèi)容里有一個(gè)數(shù)組數(shù)組里每個(gè)元素代表一條獨(dú)立業(yè)務(wù)事件要把一條日志拆成多條記錄。這兩種“拆分”的實(shí)現(xiàn)方式完全不同后面會(huì)分別說(shuō)清楚。1.2 為什么這件事要用Filebeat做日志從產(chǎn)生到進(jìn)入Elasticsearch一共有四個(gè)可以干預(yù)處理的位置應(yīng)用自身、Filebeat、Logstash、ES的Ingest Pipeline。應(yīng)用自身處理是最理想的但現(xiàn)實(shí)很骨感日志格式由業(yè)務(wù)代碼決定采集鏈路的維護(hù)者往往改不動(dòng)別人的代碼或者改一發(fā)版要排很久。Logstash雖然處理能力強(qiáng)但中間多一跳組件部署、監(jiān)控、維護(hù)都多一攤事。ES的Ingest Pipeline要占ES節(jié)點(diǎn)CPU日志量一大容易拖慢寫入。Filebeat的優(yōu)勢(shì)在于資源占用極小配置靈活自帶的processor已經(jīng)能覆蓋絕大多數(shù)JSON處理需求。對(duì)中小規(guī)模業(yè)務(wù)來(lái)說(shuō)直接在Filebeat里把解碼、裁剪、扁平化都做完是性價(jià)比最高的方案數(shù)據(jù)在傳輸前就瘦身了帶寬和存儲(chǔ)都省。1.3 明確處理鏈路與輸出目標(biāo)為了后面演示不跑偏先把目標(biāo)鏈路定下來(lái)Filebeat讀取特定目錄下的日志文件按行解析JSON刪除明確不需要的冗余字段對(duì)嵌套對(duì)象做扁平化將業(yè)務(wù)時(shí)間戳轉(zhuǎn)換為timestamp最后輸出到Elasticsearch。整條鏈路只依賴Filebeat本身不引入Logstash。這個(gè)鏈路里最關(guān)鍵的是搞清楚每個(gè)處理動(dòng)作的順序因?yàn)閜rocessor是按順序執(zhí)行的前一個(gè)的輸出就是后一個(gè)的輸入。順序錯(cuò)了結(jié)果會(huì)千奇百怪。這個(gè)點(diǎn)我會(huì)在后面的實(shí)戰(zhàn)配置里反復(fù)強(qiáng)調(diào)。2. Filebeat環(huán)境與配置基礎(chǔ)2.1 filebeat.yml的配置層級(jí)展開(kāi)配置之前先把Filebeat的配置模型講清楚。filebeat.yml里四個(gè)核心層級(jí)filebeat.inputs定義從哪讀、parsers或input配置項(xiàng)定義怎么解析、processors定義事件進(jìn)入輸出之前怎么加工、output定義最終發(fā)到哪。一個(gè)不錯(cuò)的類比是工廠流水線input是原料入口parser是拆箱機(jī)processor是流水線上的一組工位去雜質(zhì)、貼標(biāo)簽、改包裝output是出貨口。每個(gè)工位按順序工作前面工位的產(chǎn)物就是后面工位的輸入。2.2 兩種JSON解碼方式對(duì)比Filebeat處理JSON日志常見(jiàn)的解碼方式有三種很多人一上來(lái)就混用導(dǎo)致結(jié)果莫名其妙。第一種是log input的json配置項(xiàng)經(jīng)典但偏老。配置寫法是filebeat.inputs: - type: log paths: - /var/log/app/*.log json.keys_under_root: true json.overwrite_keys: true json.add_error_key: true json.message_key: messagejson.keys_under_root: true表示把JSON最外層字段直接放到事件的根級(jí)別json.overwrite_keys: true表示如果業(yè)務(wù)JSON里有字段和Filebeat自帶字段同名允許覆蓋json.add_error_key: true表示解析失敗時(shí)加一個(gè)error字段便于排查。第二種是filestream input的ndjson parser這是新版本推薦的方式filebeat.inputs: - type: filestream id: app-json-logs paths: - /var/log/app/*.log parsers: - ndjson: target: overwrite_keys: true add_error_key: truefilestream input是Filebeat 7.x開(kāi)始重點(diǎn)發(fā)展的事件流式采集方式但它不支持log input的json.*配置改用parsers里的ndjson。target設(shè)為空字符串效果等同于json.keys_under_root: true。第三種是用decode_json_fields processor這是最靈活的方式也是我比較推薦的方式processors: - decode_json_fields: fields: [message] target: overwrite_keys: true它做的事情是把事件里message字段的內(nèi)容當(dāng)作JSON解析然后按target參數(shù)決定放哪里。與input級(jí)json配置最大的區(qū)別是decode_json_fields是processor可以和其他processor任意組合也可以用條件判斷控制它只對(duì)某些事件生效。三種方式的取舍用表格看更直觀對(duì)比項(xiàng)log input的json配置filestream的ndjson parserdecode_json_fields processor適用inputlogfilestream兩者都可用作用時(shí)機(jī)input讀取階段input讀取階段事件處理階段能否與其他processor自由組合受限受限可以能否對(duì)部分事件生效否否可以版本趨勢(shì)老項(xiàng)目常見(jiàn)新項(xiàng)目推薦通用實(shí)際項(xiàng)目中我的習(xí)慣是老版本存量配置用json.keys_under_root不動(dòng)它新寫的配置統(tǒng)一用filestream input加decode_json_fields processor這樣處理邏輯都集中在一個(gè)地方排查問(wèn)題不用翻好幾個(gè)配置段。2.3 processor執(zhí)行順序的關(guān)鍵性processors數(shù)組里的順序就是執(zhí)行順序這一點(diǎn)極其重要。舉個(gè)例子如果你先做drop_fields刪掉message字段再做decode_json_fields去解message這時(shí)message已經(jīng)沒(méi)了decode會(huì)跳過(guò)或報(bào)錯(cuò)。反過(guò)來(lái)先decode把message里的內(nèi)容解析成字段再drop_fields刪掉冗余字段邏輯才是通的。我在真實(shí)項(xiàng)目里見(jiàn)過(guò)最典型的錯(cuò)誤是在decode_json_fields之前加了一個(gè)rename把message改名了結(jié)果decode_json_fields找不到字段整個(gè)JSON解析靜默失敗原始字符串原封不動(dòng)進(jìn)了ES。排查流程走了好久最后發(fā)現(xiàn)就是一行配置順序的問(wèn)題。2.4 字段保留策略的隱藏風(fēng)險(xiǎn)當(dāng)JSON字段被放到事件根級(jí)別后事件里會(huì)同時(shí)存在三類字段Filebeat內(nèi)部字段timestamp、metadata、host、log、agent等、業(yè)務(wù)字段、可能存在的ECS字段。做字段裁剪前必須清楚哪些字段是ES和Kibana運(yùn)行依賴的。比如include_fields白名單如果fields列表里忘了timestamp那么timestamp會(huì)在處理中被過(guò)濾掉日志寫入ES后時(shí)間軸直接亂掉。這個(gè)坑很多人踩過(guò)而且排查難度高因?yàn)閿?shù)據(jù)能進(jìn)ES看起來(lái)一切正常就是Kibana時(shí)間不對(duì)。做白名單保留時(shí)默認(rèn)把timestamp、log、host這類系統(tǒng)字段帶上再刪業(yè)務(wù)字段會(huì)穩(wěn)妥很多。3. JSON日志扁平化核心實(shí)操3.1 為什么日志要扁平化拿一條實(shí)際日志舉例原始JSON長(zhǎng)這樣{ timestamp: 2024-01-15T10:30:00Z, level: INFO, logger: OrderService, message: 訂單創(chuàng)建成功, context: { orderId: ORD-12345, userId: 10086 } }如果不做扁平化context整體會(huì)作為一個(gè)嵌套對(duì)象進(jìn)入ESKibana字段列表里看到的就是context.orderId、context.userId查詢要寫完整點(diǎn)號(hào)路徑建看板時(shí)要一層層展開(kāi)。如果業(yè)務(wù)里嵌套三層四層mapping會(huì)越來(lái)越亂動(dòng)態(tài)映射產(chǎn)生的字段也會(huì)暴漲。扁平化的目標(biāo)是讓context.orderId變成orderId這樣的頂層字段或者至少變成帶前綴的扁平字段讓查詢和展示都直觀。3.2 target: 實(shí)現(xiàn)的是“淺扁平化”很多人誤以為decode_json_fields的target設(shè)為空字符串就能把所有嵌套層級(jí)都拍平。實(shí)際上target: 只是把JSON最外層的字段提升到事件根級(jí)別。打個(gè)比方它拆掉了外包裝箱但里面的小盒子還在。對(duì)于只有一層嵌套的場(chǎng)景例如JSON里所有字段本來(lái)就在頂層那target: 確實(shí)夠用。但如果JSON里本身有嵌套對(duì)象比如context字段下還有orderIdtarget: 之后context還是嵌套對(duì)象并沒(méi)有真正展開(kāi)。這是“淺扁平化”和“深度扁平化”的區(qū)別。3.3 深度扁平化script processor遞歸展平要實(shí)現(xiàn)真正的深度扁平化Filebeat的script processor可以派上用場(chǎng)。這個(gè)processor支持JavaScript可以對(duì)事件做任意操作。下面是我在項(xiàng)目里驗(yàn)證過(guò)的一段遞歸展平腳本processors: - script: lang: javascript source: function flattenNode(node, prefix, output) { for (var key in node) { if (!node.hasOwnProperty(key)) continue; var fullKey prefix ? prefix _ key : key; var value node[key]; if (value ! null typeof value object !Array.isArray(value)) { flattenNode(value, fullKey, output); } else { output[fullKey] value; } } } function process(event) { var doc event.Get(); if (doc[context] ! undefined) { var flat {}; flattenNode(doc[context], ctx, flat); for (var k in flat) { event.Put(k, flat[k]); } event.Delete(context); } }這段腳本的意圖是把context對(duì)象里的所有嵌套字段遞歸展開(kāi)新字段名用下劃線拼接比如context.orderId變成ctx_orderIdcontext.userId變成ctx_userId然后把原始的context字段刪除。注意Filebeat script processor的JavaScript API和Elasticsearch的script processor不一樣這里用的event.Get、event.Put、event.Delete是Filebeat事件對(duì)象的原生方法。寫腳本時(shí)先看對(duì)應(yīng)版本的文檔不同大版本之間API可能有調(diào)整。3.4 關(guān)于扁平化字段名的關(guān)鍵認(rèn)知這里有個(gè)特別容易踩的知識(shí)點(diǎn)如果你想拍平字段新字段名里千萬(wàn)別帶點(diǎn)號(hào)。比如把context.orderId改名為context.orderId還是原來(lái)那個(gè)名字這在ES里依然會(huì)被當(dāng)作嵌套路徑處理等于白干。真正要做到扁平化字段名里不能有點(diǎn)號(hào)分隔符要么用下劃線要么用自定義前綴。這個(gè)道理類似文件路徑a/b/c是路徑分隔a_b_c就是一個(gè)普通文件名。ES的字段名機(jī)制也一樣點(diǎn)號(hào)就是路徑分隔符。理解了這一點(diǎn)你就知道為什么很多人“扁平化”之后Kibana里還是嵌套結(jié)構(gòu)。3.5 扁平化后的字段名沖突處理扁平化時(shí)最常見(jiàn)的沖突是兩條嵌套路徑展平后使用了同一個(gè)字段名。例如context.orderId和data.orderId如果都直接展平成orderId后寫的事件會(huì)覆蓋先寫的字段。穩(wěn)妥的做法是帶上前綴。我上面的腳本生成ctx_orderId就是把所有字段都加了ctx前綴這樣從context里出來(lái)的字段天然不會(huì)和日志頂層的orderId沖突。如果業(yè)務(wù)上有多個(gè)嵌套對(duì)象需要展開(kāi)建議分別為它們?cè)O(shè)置不同的前綴干脆避免沖突別指望ES能幫你智能合并。4. 去掉部分屬性三種方案的對(duì)比與選型4.1 黑名單方案drop_fields直接刪最簡(jiǎn)單的裁剪手段是drop_fields寫法很直接processors: - drop_fields: fields: [extra_verbose_data, context.items] ignore_missing: trueignore_missing: true表示字段不存在時(shí)不會(huì)報(bào)錯(cuò)這在處理多格式日志時(shí)很重要不然某個(gè)字段在這個(gè)事件里沒(méi)有整個(gè)processor會(huì)報(bào)異常。這個(gè)方案的適用場(chǎng)景是字段總量可控你明確知道哪些字段是多余的。比如日志里有一個(gè)巨大的extra_verbose調(diào)試字段直接刪掉最省事。需要注意drop_fields刪嵌套字段時(shí)要寫的是事件里的實(shí)際路徑。如果前面已經(jīng)做了扁平化原來(lái)的context.orderId已經(jīng)變成ctx_orderId了這時(shí)候再寫context.orderId肯定刪不到東西。4.2 白名單方案include_fields只留需要的字段特別多、真正用的沒(méi)幾個(gè)時(shí)相反的做法更高效只保留關(guān)心的字段。processors: - include_fields: fields: [timestamp, log, host, level, logger, message, ctx_orderId, ctx_userId]白名單的好處是業(yè)務(wù)日志里以后新增了字段也不會(huì)自動(dòng)進(jìn)入ES索引mapping非常干凈不會(huì)出現(xiàn)動(dòng)態(tài)字段泛濫。代價(jià)是每次想看一個(gè)新字段都要改配置靈活性差一些。這里我必須再次強(qiáng)調(diào)include_fields的列表一定要帶上timestamp、log、host這些系統(tǒng)字段。我自己就吃過(guò)虧第一次配白名單時(shí)只想著留業(yè)務(wù)字段結(jié)果時(shí)間字段被過(guò)濾掉了Kibana里所有日志的時(shí)間全亂了排查了很久才定位到是這個(gè)原因。4.3 服務(wù)端方案ES Ingest Pipeline如果處理邏輯希望集中在ES端可以在Elasticsearch里建一個(gè)ingest pipelinePUT _ingest/pipeline/app-log-json { processors: [ { remove: { field: extra_verbose_data } }, { rename: { field: context.orderId, target_field: ctx_orderId } } ] }然后在Filebeat的output里引用output.elasticsearch: hosts: [http://localhost:9200] index: order-app-%{yyyy.MM.dd} pipeline: app-log-json這個(gè)方案的優(yōu)勢(shì)在于邏輯集中在ES端多個(gè)采集器過(guò)來(lái)都能復(fù)用同一套處理規(guī)則改一次全鏈路生效。劣勢(shì)也明顯冗余字段已經(jīng)通過(guò)網(wǎng)絡(luò)傳到了ES白白占用帶寬而且ingest節(jié)點(diǎn)在高峰期的CPU開(kāi)銷不可忽視。4.4 方案對(duì)比與選型建議方案執(zhí)行位置節(jié)省傳輸帶寬新增字段自動(dòng)保留適合場(chǎng)景drop_fieldsFilebeat是是明確知道要?jiǎng)h哪些字段include_fieldsFilebeat是否需改配置字段極多且只需要少數(shù)幾個(gè)ES Ingest PipelineES否是多采集器復(fù)用同一套規(guī)則我的經(jīng)驗(yàn)是中小規(guī)模日志鏈路優(yōu)先全用Filebeat處理。先decode再drop_fields刪明確冗余的字段如果字段確實(shí)太雜改用include_fields白名單但一定把系統(tǒng)字段帶上。單日志量非常大的場(chǎng)景建議把復(fù)雜的字段重命名和類型轉(zhuǎn)換放到ES pipeline里Filebeat只做最基礎(chǔ)的解碼和裁剪降低Beat端的CPU壓力。5. JSON日志拆分字段拆分與事件拆分5.1 先搞清楚“拆分”指什么“拆分JSON日志”這個(gè)詞確實(shí)容易讓人犯迷糊。我基于實(shí)際需求把它拆成兩類。第一類是字段拆分把嵌套對(duì)象里的字段拆出來(lái)變成頂層字段。比如context里的orderId拆成ctx_orderId這個(gè)本質(zhì)上就是前文講的扁平化只是換了種說(shuō)法。第二類是事件拆分日志里有一個(gè)JSON數(shù)組數(shù)組中每個(gè)元素代表一條獨(dú)立業(yè)務(wù)事件希望一條日志變成多條記錄進(jìn)入ES。比如訂單日志里orders數(shù)組包含多筆訂單你想讓每筆訂單成為一條獨(dú)立日志。這兩種需求的技術(shù)路徑完全不同下面分開(kāi)講。5.2 字段拆分的實(shí)現(xiàn)思路字段拆分完全可以在Filebeat內(nèi)用script processor完成。比如下面這段腳本把orders數(shù)組里每個(gè)元素展開(kāi)成order_0_id、order_0_amount這樣的字段processors: - script: lang: javascript source: function process(event) { var orders event.Get(orders); if (orders Array.isArray(orders)) { for (var i 0; i orders.length; i) { event.Put(order_ i _id, orders[i].orderId); event.Put(order_ i _amount, orders[i].amount); } event.Delete(orders); } }這樣做的前提是數(shù)組長(zhǎng)度相對(duì)固定。因?yàn)閿?shù)組一旦變成order_0_id、order_1_id這種固定字段ES的mapping會(huì)隨數(shù)組長(zhǎng)度動(dòng)態(tài)增加字段如果長(zhǎng)度不可控mapping會(huì)很難看字段會(huì)無(wú)限膨脹。所以字段拆分只適合數(shù)組長(zhǎng)度有限且穩(wěn)定的場(chǎng)景。5.3 事件拆分的正確姿勢(shì)Filebeat加Logstash把一條日志拆成多條記錄Filebeat本身沒(méi)有這個(gè)能力這是它的邊界。要完成事件拆分標(biāo)準(zhǔn)方案是Filebeat把原日志原樣發(fā)給Logstash由Logstash的split filter處理。Logstash配置示例input { beats { port 5044 } } filter { json { source message target body } split { field [body][orders] target order } mutate { remove_field [body, message] } } output { elasticsearch { hosts [http://localhost:9200] index order-detail-%{yyyy.MM.dd} } }split filter的工作原理可以這樣理解父事件進(jìn)來(lái)了orders數(shù)組有幾個(gè)元素它就復(fù)制出幾個(gè)事件副本每個(gè)副本里把orders數(shù)組的某個(gè)元素賦值到order字段上同時(shí)保留父事件的其他字段。最后用mutate把body、message這些中間字段刪掉輸出的就是干凈的獨(dú)立訂單事件。這里有一個(gè)業(yè)務(wù)上的取舍事件拆分后每條日志攜帶的上下文比如請(qǐng)求ID、用戶ID會(huì)被復(fù)制到每條記錄中這會(huì)讓存儲(chǔ)膨脹但查詢體驗(yàn)好很多。如果業(yè)務(wù)上查詢單筆訂單時(shí)不想關(guān)聯(lián)回父日志這個(gè)代價(jià)是值得的。5.4 拆分后的索引設(shè)計(jì)建議事件拆分后數(shù)據(jù)量通常比原來(lái)多好幾倍。寫入ES時(shí)要注意兩點(diǎn)一是給拆分后的事件設(shè)置合理的索引分片數(shù)不要沿用父日志的索引配置二是在輸出端盡量讓ES做冪等寫入用業(yè)務(wù)訂單號(hào)做文檔ID避免重復(fù)采集時(shí)產(chǎn)生重復(fù)文檔。如果不想為拆分額外維護(hù)一套Logstash也可以在應(yīng)用端直接修改日志結(jié)構(gòu)把數(shù)組在日志產(chǎn)生時(shí)就打成多條獨(dú)立JSON行。這個(gè)方案最干凈但前提是你能改業(yè)務(wù)代碼。6. 完整實(shí)戰(zhàn)配置一個(gè)可復(fù)現(xiàn)的Demo6.1 演示日志樣例為了把配置講具體模擬一份訂單應(yīng)用日志存到/var/log/app/order-app.log{timestamp: 2024-01-15T10:30:00Z, level: INFO, logger: OrderService, message: 訂單創(chuàng)建成功, context: {orderId: ORD-12345, userId: 10086}, items: [SKU001, SKU002], extra_verbose: {traceId: trace-01, stack: ...}}這份日志包含了我們要演示的所有處理點(diǎn)timestamp需要轉(zhuǎn)成timestampcontext需要扁平化extra_verbose需要?jiǎng)h除items數(shù)組要保持原樣。6.2 filebeat.yml完整配置下面是一份可直接復(fù)用的完整配置filebeat.inputs: - type: filestream id: order-app-log paths: - /var/log/app/order-app.log parsers: - ndjson: target: overwrite_keys: true add_error_key: true processors: - timestamp: field: timestamp layouts: - 2006-01-02T15:04:05Z - 2006-01-02T15:04:05.999Z timezone: Asia/Shanghai ignore_failure: true - drop_fields: fields: [extra_verbose] ignore_missing: true - script: lang: javascript source: function flattenNode(node, prefix, output) { for (var key in node) { if (!node.hasOwnProperty(key)) continue; var fullKey prefix ? prefix _ key : key; var value node[key]; if (value ! null typeof value object !Array.isArray(value)) { flattenNode(value, fullKey, output); } else { output[fullKey] value; } } } function process(event) { var doc event.Get(); if (doc[context] ! undefined) { var flat {}; flattenNode(doc[context], ctx, flat); for (var k in flat) { event.Put(k, flat[k]); } event.Delete(context); } } output.elasticsearch: hosts: [http://localhost:9200] index: order-app-%{yyyy.MM.dd}配置里要解釋幾個(gè)關(guān)鍵點(diǎn)。timestamp processor的layouts用的是Go時(shí)間布局格式不是Java的yyyy-MM-dd格式。Go格式里2006代表年、01代表月、02代表日、15代表小時(shí)、04代表分鐘、05代表秒。這是Filebeat和Logstash時(shí)間格式最大的不同很多人第一次用都會(huì)在這里翻車。ignore_failure: true的含義是時(shí)間解析失敗時(shí)processor不會(huì)讓整個(gè)事件處理中斷而是繼續(xù)往下走。這在實(shí)際生產(chǎn)環(huán)境里很有用因?yàn)榕紶枙?huì)出現(xiàn)一條格式異常的日志你不能因?yàn)橐粭l臟數(shù)據(jù)把整批事件都堵住。drop_fields放在timestamp之后沒(méi)有依賴關(guān)系但放在decode之后是關(guān)鍵因?yàn)閑xtra_verbose是解析后的字段不是原始日志行里的路徑。script processor的flattenNode遞歸函數(shù)會(huì)生成ctx_orderId、ctx_userId這些帶前綴的扁平字段然后刪除原始的context對(duì)象。如果context里還有更深層的嵌套這個(gè)遞歸函數(shù)會(huì)繼續(xù)往下展開(kāi)直到所有非對(duì)象字段都變成頂層字段。6.3 啟動(dòng)與驗(yàn)證步驟寫完配置先別急著上生產(chǎn)本地跑通再說(shuō)。三個(gè)命令很實(shí)用filebeat test config -c filebeat.yml filebeat test output -c filebeat.yml filebeat -e -c filebeat.yml第一條檢查配置語(yǔ)法第二條檢查output連接是否可用第三條前臺(tái)運(yùn)行并輸出日志。如果處理邏輯復(fù)雜我習(xí)慣先把output改成console做本地調(diào)試output.console: pretty: true這樣可以直觀看到每個(gè)事件經(jīng)過(guò)processors之后長(zhǎng)什么樣確認(rèn)字段都對(duì)了再把output切回elasticsearch。這個(gè)調(diào)試手法幫我省了大量去Kibana刷index的時(shí)間。6.4 驗(yàn)證結(jié)果與字段對(duì)比經(jīng)過(guò)上面配置處理后原始日志字段會(huì)變成這樣原始字段路徑處理后字段處理方式timestamptimestamp、timestamptimestamp processor轉(zhuǎn)換context.orderIdctx_orderIdscript processor扁平化context.userIdctx_userIdscript processor扁平化extra_verbose已刪除drop_fieldsitemsitems原樣保留level、logger、message原樣保留根級(jí)字段在Kibana的Discover頁(yè)面里如果索引模板已經(jīng)生成打開(kāi)字段列表就能看到ctx_orderId、ctx_userId這些頂層字段不再有context這個(gè)嵌套對(duì)象。items作為數(shù)組字段保留方便后續(xù)做聚合分析。7. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄7.1 日志解析失敗卻沒(méi)有任何報(bào)錯(cuò)最常見(jiàn)的現(xiàn)象是原始日志明明是JSON寫入ES后message字段還是完整字符串或者干脆多了一個(gè)error字段。原因通常是add_error_key沒(méi)開(kāi)啟解析失敗的信息被Filebeat吞掉了。排查時(shí)先做的不是改配置而是用console output直接看Filebeat內(nèi)部事件長(zhǎng)什么樣output.console: pretty: true如果事件里的message還是原始字符串說(shuō)明decode_json_fields根本沒(méi)匹配到那個(gè)字段檢查fields寫的對(duì)不對(duì)。如果事件里有很多error字段說(shuō)明JSON解析失敗把日志原文復(fù)制出來(lái)用格式化工具檢查一下多半是日志里混了多行JSON或者非JSON文本。7.2 時(shí)間字段被覆蓋或丟失Kibana日志時(shí)間全是Filebeat采集時(shí)刻的實(shí)時(shí)時(shí)間而不是業(yè)務(wù)日志本身的時(shí)間。這個(gè)問(wèn)題的根源是沒(méi)有配置timestamp processor或者配置了但field寫錯(cuò)了又或者字段在include_fields時(shí)被誤刪。把業(yè)務(wù)時(shí)間字段轉(zhuǎn)成timestamp是JSON日志處理的標(biāo)準(zhǔn)動(dòng)作。同時(shí)記得如果業(yè)務(wù)字段里也有一個(gè)timestamp或類似字段decode時(shí)overwrite_keys開(kāi)啟后業(yè)務(wù)字段也可能反過(guò)來(lái)覆蓋系統(tǒng)時(shí)間導(dǎo)致時(shí)間錯(cuò)亂。這種情況建議把業(yè)務(wù)時(shí)間字段rename成一個(gè)業(yè)務(wù)專屬名比如event_time再用timestamp processor轉(zhuǎn)系統(tǒng)時(shí)間。7.3 嵌套字段依然存在扁平化沒(méi)生效我在實(shí)際項(xiàng)目中經(jīng)歷過(guò)這種場(chǎng)景按照網(wǎng)上教程配置了decode_json_fields的target: 以為能完全展平結(jié)果context還是嵌套在ES里。原因前文已經(jīng)說(shuō)過(guò)target: 只是拆外包裝要完全展開(kāi)必須用遞歸腳本。還有一個(gè)隱蔽問(wèn)題如果腳本生成的字段名里帶了點(diǎn)號(hào)比如直接寫成ctx.orderId那么ES仍然會(huì)把它當(dāng)作嵌套路徑。字段名里只要有點(diǎn)號(hào)在ES里就是層級(jí)結(jié)構(gòu)。檢查腳本生成的字段名確認(rèn)沒(méi)有點(diǎn)號(hào)。7.4 processor順序?qū)е碌脑幃惤Y(jié)果processor順序的問(wèn)題是排查成本最高的因?yàn)楹芏噱e(cuò)誤很隱蔽。比如先做了include_fields把message以外的業(yè)務(wù)字段全刪了然后decode_json_fields再去解析message解析出來(lái)的字段當(dāng)然也沒(méi)了因?yàn)槭录皇Ｏ耺essage一個(gè)字段。經(jīng)驗(yàn)法則是先做decode再做rename再做字段裁剪再做時(shí)間轉(zhuǎn)換最后做輸出相關(guān)處理。按這個(gè)順序排能避開(kāi)80%的processor順序問(wèn)題。7.5 script processor的性能隱患最后講一個(gè)很多人忽略的點(diǎn)script processor用的是JavaScript引擎解釋執(zhí)行開(kāi)銷遠(yuǎn)高于原生processor。日志量小無(wú)所謂但一天幾億條日志時(shí)如果每條都要跑一段遞歸展平腳本Filebeat的CPU會(huì)明顯吃緊。我踩過(guò)這個(gè)坑之后的實(shí)踐原則是能用原生processordecode_json_fields、drop_fields、rename、timestamp解決的絕不寫腳本腳本只處理真正無(wú)法用原生能力完成的邏輯。如果日志量真的很大把復(fù)雜處理盡量往ES Ingest Pipeline或Logstash移讓Filebeat只做最輕量的采集和裁剪。還有一種更徹底的思路找業(yè)務(wù)方溝通讓他們?cè)谳敵鋈罩厩熬桶袹SON結(jié)構(gòu)拍平。比如日志里直接輸出orderId而不是輸出context對(duì)象讓采集端再去拆。很多團(tuán)隊(duì)繞了一大圈做扁平化最后發(fā)現(xiàn)讓業(yè)務(wù)改一下日志結(jié)構(gòu)比任何采集端處理都干凈高效。我這里多分享一句個(gè)人體會(huì)Filebeat的processor能力很強(qiáng)但不代表所有事情都適合在Beat端做。學(xué)會(huì)判斷什么該在Filebeat做、什么該給Logstash、什么該留給ES pipeline比背一堆配置參數(shù)重要得多。日志鏈路每多一個(gè)處理環(huán)節(jié)排查鏈路就多一分復(fù)雜度能用最簡(jiǎn)單方案解決的別為了炫技堆復(fù)雜處理。 Filebeat JSON日志處理：字段裁剪、扁平化與拆分實(shí)操指南
維護(hù)日志鏈路的朋友大概率都遇到過(guò)這種場(chǎng)景應(yīng)用明明打的是標(biāo)準(zhǔn)JSON到了Kibana里一看有的字段變成了一長(zhǎng)串嵌套路徑有的關(guān)鍵字段被Filebeat自帶字段覆蓋了還有一堆調(diào)試用的冗余字段把索引空間撐得很大。標(biāo)題里拆出來(lái)的本質(zhì)上是三個(gè)需求去掉JSON日志里的部分屬性、把嵌套JSON拍平、按業(yè)務(wù)需求拆分JSON里的內(nèi)容。這篇就圍繞這三個(gè)問(wèn)題用Filebeat完整走一遍配置、排錯(cuò)和落地思路。先說(shuō)清楚這篇內(nèi)容解決什么不依賴Logstash、不寫ES端復(fù)雜管道盡可能用Filebeat自帶的解析能力和處理器processor完成JSON日志的采集、字段裁剪、扁平化與拆分。適合正在用Elastic Stack做日志平臺(tái)、被同事吐槽“Kibana里字段沒(méi)法看”的開(kāi)發(fā)者也適合剛接手Filebeat、想知道json.keys_under_root和decode_json_fields到底怎么選的新手。1. 項(xiàng)目概述與需求拆解1.1 標(biāo)題背后的三個(gè)核心需求表面看這只是“Filebeat采集JSON日志”但結(jié)合實(shí)際運(yùn)維場(chǎng)景訴求其實(shí)非常具體。第一是“去掉部分屬性”。業(yè)務(wù)日志里經(jīng)?；烊氪罅坎槐匾膬?nèi)容調(diào)試用的堆棧、內(nèi)部上下文字段、請(qǐng)求鏈路里的大對(duì)象。如果全部寫入Elasticsearch存儲(chǔ)成本會(huì)漲索引mapping也會(huì)被這些臟字段撐出一堆動(dòng)態(tài)映射。所以要做字段裁剪。第二是“JSON日志扁平化”。默認(rèn)情況下Filebeat把JSON解析后如果內(nèi)容里還有嵌套對(duì)象進(jìn)入ES后會(huì)形成嵌套結(jié)構(gòu)比如context.orderId、context.userId。這帶來(lái)的問(wèn)題是查詢時(shí)要寫很長(zhǎng)路徑Kibana可視化里字段展示很別扭Painless腳本里取字段也要寫完整路徑。把嵌套路徑拍平成orderId、userId這類頂層字段就是所謂的扁平化。第三是“拆分JSON日志”。這個(gè)詞最容易產(chǎn)生歧義。一種理解是把嵌套對(duì)象里的字段拆出來(lái)變成獨(dú)立頂層字段這其實(shí)和扁平化是一回事另一種理解是日志內(nèi)容里有一個(gè)數(shù)組數(shù)組里每個(gè)元素代表一條獨(dú)立業(yè)務(wù)事件要把一條日志拆成多條記錄。這兩種“拆分”的實(shí)現(xiàn)方式完全不同后面會(huì)分別說(shuō)清楚。1.2 為什么這件事要用Filebeat做日志從產(chǎn)生到進(jìn)入Elasticsearch一共有四個(gè)可以干預(yù)處理的位置應(yīng)用自身、Filebeat、Logstash、ES的Ingest Pipeline。應(yīng)用自身處理是最理想的但現(xiàn)實(shí)很骨感日志格式由業(yè)務(wù)代碼決定采集鏈路的維護(hù)者往往改不動(dòng)別人的代碼或者改一發(fā)版要排很久。Logstash雖然處理能力強(qiáng)但中間多一跳組件部署、監(jiān)控、維護(hù)都多一攤事。ES的Ingest Pipeline要占ES節(jié)點(diǎn)CPU日志量一大容易拖慢寫入。Filebeat的優(yōu)勢(shì)在于資源占用極小配置靈活自帶的processor已經(jīng)能覆蓋絕大多數(shù)JSON處理需求。對(duì)中小規(guī)模業(yè)務(wù)來(lái)說(shuō)直接在Filebeat里把解碼、裁剪、扁平化都做完是性價(jià)比最高的方案數(shù)據(jù)在傳輸前就瘦身了帶寬和存儲(chǔ)都省。1.3 明確處理鏈路與輸出目標(biāo)為了后面演示不跑偏先把目標(biāo)鏈路定下來(lái)Filebeat讀取特定目錄下的日志文件按行解析JSON刪除明確不需要的冗余字段對(duì)嵌套對(duì)象做扁平化將業(yè)務(wù)時(shí)間戳轉(zhuǎn)換為timestamp最后輸出到Elasticsearch。整條鏈路只依賴Filebeat本身不引入Logstash。這個(gè)鏈路里最關(guān)鍵的是搞清楚每個(gè)處理動(dòng)作的順序因?yàn)閜rocessor是按順序執(zhí)行的前一個(gè)的輸出就是后一個(gè)的輸入。順序錯(cuò)了結(jié)果會(huì)千奇百怪。這個(gè)點(diǎn)我會(huì)在后面的實(shí)戰(zhàn)配置里反復(fù)強(qiáng)調(diào)。2. Filebeat環(huán)境與配置基礎(chǔ)2.1 filebeat.yml的配置層級(jí)展開(kāi)配置之前先把Filebeat的配置模型講清楚。filebeat.yml里四個(gè)核心層級(jí)filebeat.inputs定義從哪讀、parsers或input配置項(xiàng)定義怎么解析、processors定義事件進(jìn)入輸出之前怎么加工、output定義最終發(fā)到哪。一個(gè)不錯(cuò)的類比是工廠流水線input是原料入口parser是拆箱機(jī)processor是流水線上的一組工位去雜質(zhì)、貼標(biāo)簽、改包裝output是出貨口。每個(gè)工位按順序工作前面工位的產(chǎn)物就是后面工位的輸入。2.2 兩種JSON解碼方式對(duì)比Filebeat處理JSON日志常見(jiàn)的解碼方式有三種很多人一上來(lái)就混用導(dǎo)致結(jié)果莫名其妙。第一種是log input的json配置項(xiàng)經(jīng)典但偏老。配置寫法是filebeat.inputs: - type: log paths: - /var/log/app/*.log json.keys_under_root: true json.overwrite_keys: true json.add_error_key: true json.message_key: messagejson.keys_under_root: true表示把JSON最外層字段直接放到事件的根級(jí)別json.overwrite_keys: true表示如果業(yè)務(wù)JSON里有字段和Filebeat自帶字段同名允許覆蓋json.add_error_key: true表示解析失敗時(shí)加一個(gè)error字段便于排查。第二種是filestream input的ndjson parser這是新版本推薦的方式filebeat.inputs: - type: filestream id: app-json-logs paths: - /var/log/app/*.log parsers: - ndjson: target: overwrite_keys: true add_error_key: truefilestream input是Filebeat 7.x開(kāi)始重點(diǎn)發(fā)展的事件流式采集方式但它不支持log input的json.*配置改用parsers里的ndjson。target設(shè)為空字符串效果等同于json.keys_under_root: true。第三種是用decode_json_fields processor這是最靈活的方式也是我比較推薦的方式processors: - decode_json_fields: fields: [message] target: overwrite_keys: true它做的事情是把事件里message字段的內(nèi)容當(dāng)作JSON解析然后按target參數(shù)決定放哪里。與input級(jí)json配置最大的區(qū)別是decode_json_fields是processor可以和其他processor任意組合也可以用條件判斷控制它只對(duì)某些事件生效。三種方式的取舍用表格看更直觀對(duì)比項(xiàng)log input的json配置filestream的ndjson parserdecode_json_fields processor適用inputlogfilestream兩者都可用作用時(shí)機(jī)input讀取階段input讀取階段事件處理階段能否與其他processor自由組合受限受限可以能否對(duì)部分事件生效否否可以版本趨勢(shì)老項(xiàng)目常見(jiàn)新項(xiàng)目推薦通用實(shí)際項(xiàng)目中我的習(xí)慣是老版本存量配置用json.keys_under_root不動(dòng)它新寫的配置統(tǒng)一用filestream input加decode_json_fields processor這樣處理邏輯都集中在一個(gè)地方排查問(wèn)題不用翻好幾個(gè)配置段。2.3 processor執(zhí)行順序的關(guān)鍵性processors數(shù)組里的順序就是執(zhí)行順序這一點(diǎn)極其重要。舉個(gè)例子如果你先做drop_fields刪掉message字段再做decode_json_fields去解message這時(shí)message已經(jīng)沒(méi)了decode會(huì)跳過(guò)或報(bào)錯(cuò)。反過(guò)來(lái)先decode把message里的內(nèi)容解析成字段再drop_fields刪掉冗余字段邏輯才是通的。我在真實(shí)項(xiàng)目里見(jiàn)過(guò)最典型的錯(cuò)誤是在decode_json_fields之前加了一個(gè)rename把message改名了結(jié)果decode_json_fields找不到字段整個(gè)JSON解析靜默失敗原始字符串原封不動(dòng)進(jìn)了ES。排查流程走了好久最后發(fā)現(xiàn)就是一行配置順序的問(wèn)題。2.4 字段保留策略的隱藏風(fēng)險(xiǎn)當(dāng)JSON字段被放到事件根級(jí)別后事件里會(huì)同時(shí)存在三類字段Filebeat內(nèi)部字段timestamp、metadata、host、log、agent等、業(yè)務(wù)字段、可能存在的ECS字段。做字段裁剪前必須清楚哪些字段是ES和Kibana運(yùn)行依賴的。比如include_fields白名單如果fields列表里忘了timestamp那么timestamp會(huì)在處理中被過(guò)濾掉日志寫入ES后時(shí)間軸直接亂掉。這個(gè)坑很多人踩過(guò)而且排查難度高因?yàn)閿?shù)據(jù)能進(jìn)ES看起來(lái)一切正常就是Kibana時(shí)間不對(duì)。做白名單保留時(shí)默認(rèn)把timestamp、log、host這類系統(tǒng)字段帶上再刪業(yè)務(wù)字段會(huì)穩(wěn)妥很多。3. JSON日志扁平化核心實(shí)操3.1 為什么日志要扁平化拿一條實(shí)際日志舉例原始JSON長(zhǎng)這樣{ timestamp: 2024-01-15T10:30:00Z, level: INFO, logger: OrderService, message: 訂單創(chuàng)建成功, context: { orderId: ORD-12345, userId: 10086 } }如果不做扁平化context整體會(huì)作為一個(gè)嵌套對(duì)象進(jìn)入ESKibana字段列表里看到的就是context.orderId、context.userId查詢要寫完整點(diǎn)號(hào)路徑建看板時(shí)要一層層展開(kāi)。如果業(yè)務(wù)里嵌套三層四層mapping會(huì)越來(lái)越亂動(dòng)態(tài)映射產(chǎn)生的字段也會(huì)暴漲。扁平化的目標(biāo)是讓context.orderId變成orderId這樣的頂層字段或者至少變成帶前綴的扁平字段讓查詢和展示都直觀。3.2 target: 實(shí)現(xiàn)的是“淺扁平化”很多人誤以為decode_json_fields的target設(shè)為空字符串就能把所有嵌套層級(jí)都拍平。實(shí)際上target: 只是把JSON最外層的字段提升到事件根級(jí)別。打個(gè)比方它拆掉了外包裝箱但里面的小盒子還在。對(duì)于只有一層嵌套的場(chǎng)景例如JSON里所有字段本來(lái)就在頂層那target: 確實(shí)夠用。但如果JSON里本身有嵌套對(duì)象比如context字段下還有orderIdtarget: 之后context還是嵌套對(duì)象并沒(méi)有真正展開(kāi)。這是“淺扁平化”和“深度扁平化”的區(qū)別。3.3 深度扁平化script processor遞歸展平要實(shí)現(xiàn)真正的深度扁平化Filebeat的script processor可以派上用場(chǎng)。這個(gè)processor支持JavaScript可以對(duì)事件做任意操作。下面是我在項(xiàng)目里驗(yàn)證過(guò)的一段遞歸展平腳本processors: - script: lang: javascript source: function flattenNode(node, prefix, output) { for (var key in node) { if (!node.hasOwnProperty(key)) continue; var fullKey prefix ? prefix _ key : key; var value node[key]; if (value ! null typeof value object !Array.isArray(value)) { flattenNode(value, fullKey, output); } else { output[fullKey] value; } } } function process(event) { var doc event.Get(); if (doc[context] ! undefined) { var flat {}; flattenNode(doc[context], ctx, flat); for (var k in flat) { event.Put(k, flat[k]); } event.Delete(context); } }這段腳本的意圖是把context對(duì)象里的所有嵌套字段遞歸展開(kāi)新字段名用下劃線拼接比如context.orderId變成ctx_orderIdcontext.userId變成ctx_userId然后把原始的context字段刪除。注意Filebeat script processor的JavaScript API和Elasticsearch的script processor不一樣這里用的event.Get、event.Put、event.Delete是Filebeat事件對(duì)象的原生方法。寫腳本時(shí)先看對(duì)應(yīng)版本的文檔不同大版本之間API可能有調(diào)整。3.4 關(guān)于扁平化字段名的關(guān)鍵認(rèn)知這里有個(gè)特別容易踩的知識(shí)點(diǎn)如果你想拍平字段新字段名里千萬(wàn)別帶點(diǎn)號(hào)。比如把context.orderId改名為context.orderId還是原來(lái)那個(gè)名字這在ES里依然會(huì)被當(dāng)作嵌套路徑處理等于白干。真正要做到扁平化字段名里不能有點(diǎn)號(hào)分隔符要么用下劃線要么用自定義前綴。這個(gè)道理類似文件路徑a/b/c是路徑分隔a_b_c就是一個(gè)普通文件名。ES的字段名機(jī)制也一樣點(diǎn)號(hào)就是路徑分隔符。理解了這一點(diǎn)你就知道為什么很多人“扁平化”之后Kibana里還是嵌套結(jié)構(gòu)。3.5 扁平化后的字段名沖突處理扁平化時(shí)最常見(jiàn)的沖突是兩條嵌套路徑展平后使用了同一個(gè)字段名。例如context.orderId和data.orderId如果都直接展平成orderId后寫的事件會(huì)覆蓋先寫的字段。穩(wěn)妥的做法是帶上前綴。我上面的腳本生成ctx_orderId就是把所有字段都加了ctx前綴這樣從context里出來(lái)的字段天然不會(huì)和日志頂層的orderId沖突。如果業(yè)務(wù)上有多個(gè)嵌套對(duì)象需要展開(kāi)建議分別為它們?cè)O(shè)置不同的前綴干脆避免沖突別指望ES能幫你智能合并。4. 去掉部分屬性三種方案的對(duì)比與選型4.1 黑名單方案drop_fields直接刪最簡(jiǎn)單的裁剪手段是drop_fields寫法很直接processors: - drop_fields: fields: [extra_verbose_data, context.items] ignore_missing: trueignore_missing: true表示字段不存在時(shí)不會(huì)報(bào)錯(cuò)這在處理多格式日志時(shí)很重要不然某個(gè)字段在這個(gè)事件里沒(méi)有整個(gè)processor會(huì)報(bào)異常。這個(gè)方案的適用場(chǎng)景是字段總量可控你明確知道哪些字段是多余的。比如日志里有一個(gè)巨大的extra_verbose調(diào)試字段直接刪掉最省事。需要注意drop_fields刪嵌套字段時(shí)要寫的是事件里的實(shí)際路徑。如果前面已經(jīng)做了扁平化原來(lái)的context.orderId已經(jīng)變成ctx_orderId了這時(shí)候再寫context.orderId肯定刪不到東西。4.2 白名單方案include_fields只留需要的字段特別多、真正用的沒(méi)幾個(gè)時(shí)相反的做法更高效只保留關(guān)心的字段。processors: - include_fields: fields: [timestamp, log, host, level, logger, message, ctx_orderId, ctx_userId]白名單的好處是業(yè)務(wù)日志里以后新增了字段也不會(huì)自動(dòng)進(jìn)入ES索引mapping非常干凈不會(huì)出現(xiàn)動(dòng)態(tài)字段泛濫。代價(jià)是每次想看一個(gè)新字段都要改配置靈活性差一些。這里我必須再次強(qiáng)調(diào)include_fields的列表一定要帶上timestamp、log、host這些系統(tǒng)字段。我自己就吃過(guò)虧第一次配白名單時(shí)只想著留業(yè)務(wù)字段結(jié)果時(shí)間字段被過(guò)濾掉了Kibana里所有日志的時(shí)間全亂了排查了很久才定位到是這個(gè)原因。4.3 服務(wù)端方案ES Ingest Pipeline如果處理邏輯希望集中在ES端可以在Elasticsearch里建一個(gè)ingest pipelinePUT _ingest/pipeline/app-log-json { processors: [ { remove: { field: extra_verbose_data } }, { rename: { field: context.orderId, target_field: ctx_orderId } } ] }然后在Filebeat的output里引用output.elasticsearch: hosts: [http://localhost:9200] index: order-app-%{yyyy.MM.dd} pipeline: app-log-json這個(gè)方案的優(yōu)勢(shì)在于邏輯集中在ES端多個(gè)采集器過(guò)來(lái)都能復(fù)用同一套處理規(guī)則改一次全鏈路生效。劣勢(shì)也明顯冗余字段已經(jīng)通過(guò)網(wǎng)絡(luò)傳到了ES白白占用帶寬而且ingest節(jié)點(diǎn)在高峰期的CPU開(kāi)銷不可忽視。4.4 方案對(duì)比與選型建議方案執(zhí)行位置節(jié)省傳輸帶寬新增字段自動(dòng)保留適合場(chǎng)景drop_fieldsFilebeat是是明確知道要?jiǎng)h哪些字段include_fieldsFilebeat是否需改配置字段極多且只需要少數(shù)幾個(gè)ES Ingest PipelineES否是多采集器復(fù)用同一套規(guī)則我的經(jīng)驗(yàn)是中小規(guī)模日志鏈路優(yōu)先全用Filebeat處理。先decode再drop_fields刪明確冗余的字段如果字段確實(shí)太雜改用include_fields白名單但一定把系統(tǒng)字段帶上。單日志量非常大的場(chǎng)景建議把復(fù)雜的字段重命名和類型轉(zhuǎn)換放到ES pipeline里Filebeat只做最基礎(chǔ)的解碼和裁剪降低Beat端的CPU壓力。5. JSON日志拆分字段拆分與事件拆分5.1 先搞清楚“拆分”指什么“拆分JSON日志”這個(gè)詞確實(shí)容易讓人犯迷糊。我基于實(shí)際需求把它拆成兩類。第一類是字段拆分把嵌套對(duì)象里的字段拆出來(lái)變成頂層字段。比如context里的orderId拆成ctx_orderId這個(gè)本質(zhì)上就是前文講的扁平化只是換了種說(shuō)法。第二類是事件拆分日志里有一個(gè)JSON數(shù)組數(shù)組中每個(gè)元素代表一條獨(dú)立業(yè)務(wù)事件希望一條日志變成多條記錄進(jìn)入ES。比如訂單日志里orders數(shù)組包含多筆訂單你想讓每筆訂單成為一條獨(dú)立日志。這兩種需求的技術(shù)路徑完全不同下面分開(kāi)講。5.2 字段拆分的實(shí)現(xiàn)思路字段拆分完全可以在Filebeat內(nèi)用script processor完成。比如下面這段腳本把orders數(shù)組里每個(gè)元素展開(kāi)成order_0_id、order_0_amount這樣的字段processors: - script: lang: javascript source: function process(event) { var orders event.Get(orders); if (orders Array.isArray(orders)) { for (var i 0; i orders.length; i) { event.Put(order_ i _id, orders[i].orderId); event.Put(order_ i _amount, orders[i].amount); } event.Delete(orders); } }這樣做的前提是數(shù)組長(zhǎng)度相對(duì)固定。因?yàn)閿?shù)組一旦變成order_0_id、order_1_id這種固定字段ES的mapping會(huì)隨數(shù)組長(zhǎng)度動(dòng)態(tài)增加字段如果長(zhǎng)度不可控mapping會(huì)很難看字段會(huì)無(wú)限膨脹。所以字段拆分只適合數(shù)組長(zhǎng)度有限且穩(wěn)定的場(chǎng)景。5.3 事件拆分的正確姿勢(shì)Filebeat加Logstash把一條日志拆成多條記錄Filebeat本身沒(méi)有這個(gè)能力這是它的邊界。要完成事件拆分標(biāo)準(zhǔn)方案是Filebeat把原日志原樣發(fā)給Logstash由Logstash的split filter處理。Logstash配置示例input { beats { port 5044 } } filter { json { source message target body } split { field [body][orders] target order } mutate { remove_field [body, message] } } output { elasticsearch { hosts [http://localhost:9200] index order-detail-%{yyyy.MM.dd} } }split filter的工作原理可以這樣理解父事件進(jìn)來(lái)了orders數(shù)組有幾個(gè)元素它就復(fù)制出幾個(gè)事件副本每個(gè)副本里把orders數(shù)組的某個(gè)元素賦值到order字段上同時(shí)保留父事件的其他字段。最后用mutate把body、message這些中間字段刪掉輸出的就是干凈的獨(dú)立訂單事件。這里有一個(gè)業(yè)務(wù)上的取舍事件拆分后每條日志攜帶的上下文比如請(qǐng)求ID、用戶ID會(huì)被復(fù)制到每條記錄中這會(huì)讓存儲(chǔ)膨脹但查詢體驗(yàn)好很多。如果業(yè)務(wù)上查詢單筆訂單時(shí)不想關(guān)聯(lián)回父日志這個(gè)代價(jià)是值得的。5.4 拆分后的索引設(shè)計(jì)建議事件拆分后數(shù)據(jù)量通常比原來(lái)多好幾倍。寫入ES時(shí)要注意兩點(diǎn)一是給拆分后的事件設(shè)置合理的索引分片數(shù)不要沿用父日志的索引配置二是在輸出端盡量讓ES做冪等寫入用業(yè)務(wù)訂單號(hào)做文檔ID避免重復(fù)采集時(shí)產(chǎn)生重復(fù)文檔。如果不想為拆分額外維護(hù)一套Logstash也可以在應(yīng)用端直接修改日志結(jié)構(gòu)把數(shù)組在日志產(chǎn)生時(shí)就打成多條獨(dú)立JSON行。這個(gè)方案最干凈但前提是你能改業(yè)務(wù)代碼。6. 完整實(shí)戰(zhàn)配置一個(gè)可復(fù)現(xiàn)的Demo6.1 演示日志樣例為了把配置講具體模擬一份訂單應(yīng)用日志存到/var/log/app/order-app.log{timestamp: 2024-01-15T10:30:00Z, level: INFO, logger: OrderService, message: 訂單創(chuàng)建成功, context: {orderId: ORD-12345, userId: 10086}, items: [SKU001, SKU002], extra_verbose: {traceId: trace-01, stack: ...}}這份日志包含了我們要演示的所有處理點(diǎn)timestamp需要轉(zhuǎn)成timestampcontext需要扁平化extra_verbose需要?jiǎng)h除items數(shù)組要保持原樣。6.2 filebeat.yml完整配置下面是一份可直接復(fù)用的完整配置filebeat.inputs: - type: filestream id: order-app-log paths: - /var/log/app/order-app.log parsers: - ndjson: target: overwrite_keys: true add_error_key: true processors: - timestamp: field: timestamp layouts: - 2006-01-02T15:04:05Z - 2006-01-02T15:04:05.999Z timezone: Asia/Shanghai ignore_failure: true - drop_fields: fields: [extra_verbose] ignore_missing: true - script: lang: javascript source: function flattenNode(node, prefix, output) { for (var key in node) { if (!node.hasOwnProperty(key)) continue; var fullKey prefix ? prefix _ key : key; var value node[key]; if (value ! null typeof value object !Array.isArray(value)) { flattenNode(value, fullKey, output); } else { output[fullKey] value; } } } function process(event) { var doc event.Get(); if (doc[context] ! undefined) { var flat {}; flattenNode(doc[context], ctx, flat); for (var k in flat) { event.Put(k, flat[k]); } event.Delete(context); } } output.elasticsearch: hosts: [http://localhost:9200] index: order-app-%{yyyy.MM.dd}配置里要解釋幾個(gè)關(guān)鍵點(diǎn)。timestamp processor的layouts用的是Go時(shí)間布局格式不是Java的yyyy-MM-dd格式。Go格式里2006代表年、01代表月、02代表日、15代表小時(shí)、04代表分鐘、05代表秒。這是Filebeat和Logstash時(shí)間格式最大的不同很多人第一次用都會(huì)在這里翻車。ignore_failure: true的含義是時(shí)間解析失敗時(shí)processor不會(huì)讓整個(gè)事件處理中斷而是繼續(xù)往下走。這在實(shí)際生產(chǎn)環(huán)境里很有用因?yàn)榕紶枙?huì)出現(xiàn)一條格式異常的日志你不能因?yàn)橐粭l臟數(shù)據(jù)把整批事件都堵住。drop_fields放在timestamp之后沒(méi)有依賴關(guān)系但放在decode之后是關(guān)鍵因?yàn)閑xtra_verbose是解析后的字段不是原始日志行里的路徑。script processor的flattenNode遞歸函數(shù)會(huì)生成ctx_orderId、ctx_userId這些帶前綴的扁平字段然后刪除原始的context對(duì)象。如果context里還有更深層的嵌套這個(gè)遞歸函數(shù)會(huì)繼續(xù)往下展開(kāi)直到所有非對(duì)象字段都變成頂層字段。6.3 啟動(dòng)與驗(yàn)證步驟寫完配置先別急著上生產(chǎn)本地跑通再說(shuō)。三個(gè)命令很實(shí)用filebeat test config -c filebeat.yml filebeat test output -c filebeat.yml filebeat -e -c filebeat.yml第一條檢查配置語(yǔ)法第二條檢查output連接是否可用第三條前臺(tái)運(yùn)行并輸出日志。如果處理邏輯復(fù)雜我習(xí)慣先把output改成console做本地調(diào)試output.console: pretty: true這樣可以直觀看到每個(gè)事件經(jīng)過(guò)processors之后長(zhǎng)什么樣確認(rèn)字段都對(duì)了再把output切回elasticsearch。這個(gè)調(diào)試手法幫我省了大量去Kibana刷index的時(shí)間。6.4 驗(yàn)證結(jié)果與字段對(duì)比經(jīng)過(guò)上面配置處理后原始日志字段會(huì)變成這樣原始字段路徑處理后字段處理方式timestamptimestamp、timestamptimestamp processor轉(zhuǎn)換context.orderIdctx_orderIdscript processor扁平化context.userIdctx_userIdscript processor扁平化extra_verbose已刪除drop_fieldsitemsitems原樣保留level、logger、message原樣保留根級(jí)字段在Kibana的Discover頁(yè)面里如果索引模板已經(jīng)生成打開(kāi)字段列表就能看到ctx_orderId、ctx_userId這些頂層字段不再有context這個(gè)嵌套對(duì)象。items作為數(shù)組字段保留方便后續(xù)做聚合分析。7. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄7.1 日志解析失敗卻沒(méi)有任何報(bào)錯(cuò)最常見(jiàn)的現(xiàn)象是原始日志明明是JSON寫入ES后message字段還是完整字符串或者干脆多了一個(gè)error字段。原因通常是add_error_key沒(méi)開(kāi)啟解析失敗的信息被Filebeat吞掉了。排查時(shí)先做的不是改配置而是用console output直接看Filebeat內(nèi)部事件長(zhǎng)什么樣output.console: pretty: true如果事件里的message還是原始字符串說(shuō)明decode_json_fields根本沒(méi)匹配到那個(gè)字段檢查fields寫的對(duì)不對(duì)。如果事件里有很多error字段說(shuō)明JSON解析失敗把日志原文復(fù)制出來(lái)用格式化工具檢查一下多半是日志里混了多行JSON或者非JSON文本。7.2 時(shí)間字段被覆蓋或丟失Kibana日志時(shí)間全是Filebeat采集時(shí)刻的實(shí)時(shí)時(shí)間而不是業(yè)務(wù)日志本身的時(shí)間。這個(gè)問(wèn)題的根源是沒(méi)有配置timestamp processor或者配置了但field寫錯(cuò)了又或者字段在include_fields時(shí)被誤刪。把業(yè)務(wù)時(shí)間字段轉(zhuǎn)成timestamp是JSON日志處理的標(biāo)準(zhǔn)動(dòng)作。同時(shí)記得如果業(yè)務(wù)字段里也有一個(gè)timestamp或類似字段decode時(shí)overwrite_keys開(kāi)啟后業(yè)務(wù)字段也可能反過(guò)來(lái)覆蓋系統(tǒng)時(shí)間導(dǎo)致時(shí)間錯(cuò)亂。這種情況建議把業(yè)務(wù)時(shí)間字段rename成一個(gè)業(yè)務(wù)專屬名比如event_time再用timestamp processor轉(zhuǎn)系統(tǒng)時(shí)間。7.3 嵌套字段依然存在扁平化沒(méi)生效我在實(shí)際項(xiàng)目中經(jīng)歷過(guò)這種場(chǎng)景按照網(wǎng)上教程配置了decode_json_fields的target: 以為能完全展平結(jié)果context還是嵌套在ES里。原因前文已經(jīng)說(shuō)過(guò)target: 只是拆外包裝要完全展開(kāi)必須用遞歸腳本。還有一個(gè)隱蔽問(wèn)題如果腳本生成的字段名里帶了點(diǎn)號(hào)比如直接寫成ctx.orderId那么ES仍然會(huì)把它當(dāng)作嵌套路徑。字段名里只要有點(diǎn)號(hào)在ES里就是層級(jí)結(jié)構(gòu)。檢查腳本生成的字段名確認(rèn)沒(méi)有點(diǎn)號(hào)。7.4 processor順序?qū)е碌脑幃惤Y(jié)果processor順序的問(wèn)題是排查成本最高的因?yàn)楹芏噱e(cuò)誤很隱蔽。比如先做了include_fields把message以外的業(yè)務(wù)字段全刪了然后decode_json_fields再去解析message解析出來(lái)的字段當(dāng)然也沒(méi)了因?yàn)槭录皇Ｏ耺essage一個(gè)字段。經(jīng)驗(yàn)法則是先做decode再做rename再做字段裁剪再做時(shí)間轉(zhuǎn)換最后做輸出相關(guān)處理。按這個(gè)順序排能避開(kāi)80%的processor順序問(wèn)題。7.5 script processor的性能隱患最后講一個(gè)很多人忽略的點(diǎn)script processor用的是JavaScript引擎解釋執(zhí)行開(kāi)銷遠(yuǎn)高于原生processor。日志量小無(wú)所謂但一天幾億條日志時(shí)如果每條都要跑一段遞歸展平腳本Filebeat的CPU會(huì)明顯吃緊。我踩過(guò)這個(gè)坑之后的實(shí)踐原則是能用原生processordecode_json_fields、drop_fields、rename、timestamp解決的絕不寫腳本腳本只處理真正無(wú)法用原生能力完成的邏輯。如果日志量真的很大把復(fù)雜處理盡量往ES Ingest Pipeline或Logstash移讓Filebeat只做最輕量的采集和裁剪。還有一種更徹底的思路找業(yè)務(wù)方溝通讓他們?cè)谳敵鋈罩厩熬桶袹SON結(jié)構(gòu)拍平。比如日志里直接輸出orderId而不是輸出context對(duì)象讓采集端再去拆。很多團(tuán)隊(duì)繞了一大圈做扁平化最后發(fā)現(xiàn)讓業(yè)務(wù)改一下日志結(jié)構(gòu)比任何采集端處理都干凈高效。我這里多分享一句個(gè)人體會(huì)Filebeat的processor能力很強(qiáng)但不代表所有事情都適合在Beat端做。學(xué)會(huì)判斷什么該在Filebeat做、什么該給Logstash、什么該留給ES pipeline比背一堆配置參數(shù)重要得多。日志鏈路每多一個(gè)處理環(huán)節(jié)排查鏈路就多一分復(fù)雜度能用最簡(jiǎn)單方案解決的別為了炫技堆復(fù)雜處理。