先說清楚這套標準目前的成熟度

在深入細節之前，有件事要老實講：OpenTelemetry 的 GenAI 語意慣例，截至目前仍處於 Development／Experimental 階段，尚未正式穩定發布。這代表屬性名稱、結構未來仍可能調整，不同 SDK 之間對同一個屬性的實作也可能存在落差（例如新舊命名並存的過渡期）。這篇會介紹這套標準的核心概念，但發布前務必查證當下最新狀態，不要把還在實驗階段的規格寫成已經定案的標準。

核心概念：用標準化屬性名稱描述 GenAI 操作

OpenTelemetry GenAI SIG（自 2024 年 4 月成立）定義了一套標準化的 gen_ai.* 屬性命名，目的是讓不同來源的遙測資料（不管是 OpenAI、Anthropic、還是 Gemini）能用同一套詞彙描述，避免每家廠商、每個框架各自發明一套屬性名稱，造成後端分析工具要為每個來源寫客製化解析邏輯。

常見的屬性包括：gen_ai.request.model（呼叫的模型名稱）、gen_ai.usage.input_tokens 與 gen_ai.usage.output_tokens（輸入輸出 Token 數）、gen_ai.response.finish_reasons（模型停止生成的原因）。

Span 的三層結構

依照這套慣例，一次 Agent 執行會產生一個階層式的 Span 結構：最外層是 invoke_agent（代表整次 Agent 呼叫），底下是一個或多個 chat（每一次 LLM 呼叫）與 execute_tool（每一次工具呼叫）子 Span。這個結構直接對應 Day2 談的「推理鏈」概念——一棵 Span 樹，就是一條完整的決策路徑。

一個重要的反模式：別把完整 Prompt 塞進屬性

有個常見的錯誤是把完整的 Prompt 與回應內容直接塞進 Span 的屬性（attribute）裡。屬性預設會被索引、有大小限制，而且會讓敏感內容（可能包含個資）直接暴露在你的可觀測性後端。GenAI 語意慣例的建議做法是把內容放進 Span 的事件（event）而非屬性——事件可以在 Collector 層級被過濾或丟棄，不需要改動應用程式碼就能控制敏感內容是否要保留。這個設計呼應主題一（GCP Security 系列）Day15 談過的 Sensitive Data Protection 精神：可觀測性系統本身，也需要資料治理。

跟 ADK 的內建整合

這是這個系列跟隊友 ADK 系列最直接的橋接點：Google Cloud Trace 官方文件已經提供「Instrument ADK applications with OpenTelemetry」的專門指引，代表用 ADK 建的 Agent，有機會透過內建的 instrumentation 直接產生符合規範的 Span，不需要從零手刻。如果你也在追隊友的 ADK 系列，這篇可以當作兩個系列之間的技術橋樑。

待實測提醒：ADK 的內建 OpenTelemetry instrumentation 實際涵蓋範圍與設定方式，請對照 Google Cloud Observability 官方文件「Instrument generative AI applications」 確認，並建議跟隊友一起實測驗證，確保兩個系列的技術描述一致。

這篇的檢查清單

• [ ] 是否已確認目前使用的 SDK 對 GenAI 語意慣例的支援程度，避免屬性名稱不一致造成查詢遺漏？
• [ ] 敏感內容（Prompt/Completion）是否已規劃放進事件而非屬性，並設計對應的過濾機制？
• [ ] 若使用 ADK 建構 Agent，是否已確認內建 instrumentation 的實際涵蓋範圍？

💡 關於作者
我是 Fngi，專注在 AI 安全與雲端資安領域。如果這篇對你有幫助，歡迎追蹤 Instagram @aid3fend，我在那裡分享更多 AI 資安的實務筆記與趨勢觀察。