AgentLoop：使用 OpenTelemetry GenAI Utils 進行 LLM 應用接入

業務情境

隨著大語言模型（LLM）與 AI Agent 應用的快速普及，可觀測性對 AI 應用開發與營運越來越重要。Agent 與 MCP（Model Context Protocol）工具的多輪互動、推理引擎（如 vLLM、SGLang）的調度鏈路，以及 Token 消耗與首 Token 延遲（TTFT）等關鍵計量，都需要統一採集和分析。ARMS 應用監控已針對典型 GenAI 情境提供開箱即用的探針能力——基於 MCP 協議實現端到端全鏈路追蹤展示了 Python 探針如何零代碼接入 LangChain Agent 與 MCP Server 的完整調用鏈，對 vLLM/SGLang 推理引擎進行可觀測則覆蓋推理引擎的請求級 Span、gen_ai.latency.* 延遲屬性以及 TTFT/TPOT 等指標。然而，自研架構、多語言混合架構或需要精細控制 Span 內容的情境，仍需通過業務代碼手動 instrument LLM 調用、Agent 編排、Tool 執行等操作。GenAI Utils 正是為這類情境設計的工具庫。

GenAI Utils 與應用監控探針互補而非替代：探針以零代碼或低代碼方式自動 instrument 已知架構（如 LangChain、vLLM、MCP 協議等），適合標準化部署；GenAI Utils 通過業務代碼顯式調用 Handler API，適合自研 Agent 架構、需要自訂 Span 屬性、或探針尚未覆蓋的整合情境。兩者產出的遙測資料遵循同一套 GenAI 語義約定，可通過 ARMS 控制台或任意 OpenTelemetry 相容後端統一分析。

方案架構

GenAI Utils 是一組面向產生式 AI 操作的共用遙測工具庫，核心職責是將 LLM 推理、Agent 調用、Embedding、Tool 執行、Retrieval 等操作映射為符合 OpenTelemetry GenAI 語義約定（Semantic Conventions） 的標準 Span、Event 與指標，並提供統一的生命週期管理 API（如 start / stop / fail）。

OpenTelemetry 社區首先在 Python 生態發布了參考實現 opentelemetry-util-genai，隨後 Java、Go、Node.js 等語言也提供了遵循相同 API 設計與語義約定的對等實現。

典型資料流如下：

業務代碼 + GenAI Utils（產生 Span）
        ↓
OpenTelemetry SDK / Exporter（配置存取點與鑒權）
        ↓
ARMS 可觀測鏈路 OpenTelemetry 版
        ↓
ARMS 控制台調用鏈分析

準備工作

GenAI Utils 負責產生符合語義約定的 Span 與指標，但要將資料上報至 ARMS 可觀測鏈路 OpenTelemetry 版並在控制台查看，還需完成 OpenTelemetry SDK / Exporter 的配置。在編寫業務代碼前，完成以下準備：

1. 開通可觀測鏈路 OpenTelemetry 版服務。

2. 擷取對應地區的存取點網域名稱、連接埠及鑒權 Token。

3. 配置 OpenTelemetry SDK 或 Collector，將 Trace 資料通過 OTLP 等協議上報至 ARMS。

上述接入流程、各地區 Endpoint 說明、連接埠與協議對應關係，以及 OpenTelemetry SDK / Collector 的配置方式，參考接入指南。該文檔涵蓋：

• 準備工作：存取點網域名稱、連接埠、鑒權 Token 擷取方式

• OpenTelemetry 接入說明：基於 OpenTelemetry SDK / Collector 的資料上報配置。

• 其他用戶端接入方式（Jaeger、Zipkin、SkyWalking 等）

若應用部署在阿里雲之外，還需按接入指南開放相應連接埠與網域名稱存取權限。

快速開始（Python 樣本）

Python 是 OpenTelemetry 生態中 GenAI Utils 的首發語言，API 設計也被其他語言實現所參考。以下樣本展示如何通過 TelemetryHandler 為一次 LLM 調用採集標準 GenAI Span。

安裝 GenAI Utils 及其依賴的 OpenTelemetry SDK 與 Exporter 包：

pip install opentelemetry-util-genai

from opentelemetry.util.genai.handler import get_telemetry_handler
from opentelemetry.util.genai.types import InputMessage, LLMInvocation, OutputMessage, Text

handler = get_telemetry_handler()

invocation = LLMInvocation(
    provider="openai",
    request_model="gpt-4o-mini",
    input_messages=[
        InputMessage(role="user", parts=[Text(content="用一句話解釋 OpenTelemetry。")]),
    ],
)
with handler.llm(invocation) as inv:
    # 此處調用真實模型 API
    inv.output_messages = [
        OutputMessage(
            role="assistant",
            parts=[Text(content="OpenTelemetry 是用於可觀測性的開放標準與實現。")],
            finish_reason="stop",
        )
    ]
    inv.input_tokens = 10
    inv.output_tokens = 20

接入步驟可概括為：安裝依賴 → 初始化 OpenTelemetry Provider → 建立 Handler → 用 with handler.llm(...) 包裹業務調用。若需採集更多操作類型或配置訊息內容採集策略，參考對應語言的詳細文檔。

驗證資料上報

運行範例程式碼後，登入 ARMS 控制台，在調用鏈分析頁面查看上報的 GenAI Span。Span 中應包含 gen_ai.system、gen_ai.request.model、gen_ai.usage.* 等標準屬性，與代碼中設定的 provider、request_model 及 Token 用量相對應。

各語言 GenAI Utils 文檔入口

各語言實現遵循相同的語義約定與 Handler API 設計模式，安裝步驟、完整 API 及範例程式碼參閱對應文檔：