使用 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 及示例代码参阅对应文档：