OTTL 詳解:在 Collector 轉換與篩選遙測資料
了解 OTTL 陳述式、路徑和上下文,並用 Collector 範例修正舊狀態、刪除標頭及擷取路由分組。
服務換了埋點函式庫,請求的行為沒變,儀表板上的錯誤數卻可能變了。如果舊函式庫把每個 404 都算成錯誤,直接重設所有 404 Span 也會把用戶端的真實錯誤一起蓋掉。先確認要改的是哪一個 Span,以及它為什麼被標成錯誤。
OTTL(OpenTelemetry Transformation Language)是 Collector 用來檢查和處理遙測資料的語言。 transform processor 可改寫欄位,filter processor 則可用 OTTL 條件捨棄符合條件的資料。兩者都在 Collector 的結構化資料上運作。
OTTL 重點速覽
- 轉換陳述式呼叫一個編輯函式,也可以加上
where條件。 span.attributes["http.request.method"]、span.status.code等路徑指向上下文裡的欄位。- 常見用途包括改名、刪除、擷取資料和條件更新。
- 把規則移到不同處理階段時,逐項對照欄位、型別及失敗時的行為。
OTTL 能解決什麼問題?
遙測資料送往後端前,有時需要刪除擷取到的標頭,或將舊屬性名稱對齊語意慣例(英文)。知道狀態被誤判的原因時,也可以修正它。這些操作可用 OTTL 寫在 Collector 設定裡。埋點版本不同,HTTP 狀態碼可能在 http.status_code,也可能在 http.response.status_code。改名前先查實際送出的欄位。
管線裡的資料長什麼樣?
追蹤包含 Span 和 Span Event,指標包含資料點,日誌包含個別記錄。上下文決定正在處理哪種物件,以及可以存取哪些欄位。Span 上下文可以存取目前的 Span 和它的資源屬性。資源屬性是共用的,修改它可能影響同一資源下的其他記錄。
讀懂 OTTL 語法
陳述式
一條轉換陳述式呼叫一個編輯函式,並可接上 where 條件。同一組的陳述式依序執行。下例使用 Collector Contrib v0.162.0 的 Span 上下文。
set(span.attributes["app.http.response_class"], "2xx") where IsInt(span.attributes["http.response.status_code"]) and span.attributes["http.response.status_code"] >= 200 and span.attributes["http.response.status_code"] < 300
delete_key(span.attributes, "http.request.header.authorization")
運算式與常值
OTTL 支援布林、數字和字串常值,也支援 ==、!= 等比較運算,以及 and、or。列舉值依上下文而定,例如 Span 可以使用 STATUS_CODE_UNSET。若屬性型別不一定是整數,先用 IsInt 確認,再進行數值比較。
路徑與上下文
span.attributes["key"] 指向目前 Span 的屬性,resource.attributes["service.name"] 指向資源屬性。span.name 和 span.status.code 是 Span 的內建欄位。transform processor 可由有前綴的路徑推斷上下文,也可以透過群組的 context 明確指定。路徑、函式和列舉值都要在該上下文中可用。
條件
where 為真時才執行那條陳述式。群組還可以用 conditions 設定共同條件。清單中的多個條件以 OR 組合。若各項判斷都必須成立,應在同一條條件裡用 and 連接。
HTTP Span 的轉換範例
第一組用來修正原因已知的舊狀態對應。只有在上游確認舊規則把服務端回傳 4xx 當成設定 Error 的唯一理由時,才寫入範例的自訂屬性 app.legacy_http_status_error。若管線沒有這個約定,請略過第一組。依 HTTP 語意慣例,埋點沒有額外資訊時,服務端 4xx 的 Span 狀態應維持 Unset,用戶端 4xx 則建議設為 Error。HTTP Span 狀態慣例(英文)
processors:
transform:
error_mode: ignore
trace_statements:
- context: span
conditions:
- >-
span.kind == SPAN_KIND_SERVER
and span.status.code == STATUS_CODE_ERROR
and span.attributes["app.legacy_http_status_error"] == true
and IsInt(span.attributes["http.response.status_code"])
and span.attributes["http.response.status_code"] >= 400
and span.attributes["http.response.status_code"] < 500
statements:
- set(span.status.message, "")
- set(span.status.code, STATUS_CODE_UNSET)
- context: span
statements:
- delete_key(span.attributes, "http.request.header.cookie")
- set(span.cache["route_parts"], ExtractPatterns(span.attributes["url.path"], "^/api/(?P<group>orders|customers)(/|$)")) where IsString(span.attributes["url.path"])
- set(span.attributes["app.route_group"], span.cache["route_parts"]["group"]) where span.cache["route_parts"]["group"] != nil
第二組會刪除指定的 Span 屬性。Cookie 若也出現在資源、Span Event 或日誌內文,要另外處理。ExtractPatterns 會傳回由具名擷取群組組成的映射,沒有符合的值時傳回空映射。後續陳述式讀取其中的 group,寫入自訂字串欄位,保留 http.route 的原值。
要讓規則執行,須將 transform 加進實際的 service.pipelines.traces.processors 清單。更多範例見 OTTL 實戰手冊(簡體中文)。
選擇在哪一層轉換
已在 Collector 執行的規則,可以繼續放在匯出前。若改用 DataKit 的觀測雲 Pipeline(簡體中文) 處理日誌,需用 Platypus 函式重寫,再用相同的資料比較輸出。欄位移除、型別轉換和失敗處理要各自驗證。先分清楚哪一層負責移除敏感資訊和欄位改名,再查後端實際收到什麼。敏感值如果到後段才被移除,前面的階段仍會接觸原值。
常見問題
OTTL 和 filter processor 有什麼差別? OTTL 是語言。transform processor 用它修改欄位,filter processor 用它判斷哪些 Span 或日誌等記錄應被捨棄。若篩選條件用到改寫後的欄位,請在同一管線先執行 transform。
OTTL 的處理成本有多高? 取決於規則執行次數、資料量和操作類型。每筆都跑正規表示式或剖析 JSON 會消耗 CPU。修改規則或處理位置時,可比較輸送量、處理延遲及 Collector 的資源用量。
陳述式執行失敗時會怎樣? 本文版本的 transform 預設為 ignore,會記錄執行時錯誤並繼續。silent 也會繼續,但不記錄該錯誤。propagate 會把錯誤回傳給管線,導致該批資料被捨棄。無法剖析的陳述式屬於設定錯誤。移除敏感資訊時若使用 ignore,也要核對失敗的樣本是否還帶著原值。
觀測雲 Pipeline 可以直接執行 OTTL 嗎? Pipeline 使用 Platypus 指令碼。依對應函式和資料型別改寫規則,再用同一批樣本核對處理結果。
延伸閱讀
- 上一篇 用 OCB 建置自訂 Collector(英文)
- 下一篇 OTLP 協定詳解
- 相關文章 OTTL 實戰手冊(簡體中文) · OpenTelemetry 語意慣例(英文) · 可觀測性技術指南
參考資料 OTTL 語法 v0.162.0(英文) · 觀測雲 OpenTelemetry 接入文件(簡體中文) · DataKit Pipeline(簡體中文) · DataKit 文件(簡體中文)
