ag2-telemetry

Telemetry — OpenTelemetry 插桩

适用场景

用户希望：

• 查看每轮 / 每次调用的延迟明细
• 按操作归因 Token 用量
• 将追踪数据发送到 Jaeger、Grafana Tempo、Datadog、Honeycomb、Langfuse 等
• 使用结构化 Span 而非打印语句，从端到端调试运行缓慢的 Agent

如果用户只是想快速在 stdout 中进行调试，请改为推荐 LoggingMiddleware（参见 ag2-middleware）。

安装

pip install "ag2[openai,tracing]"

必需。交付代码前请运行此安装命令。如果无法运行命令，请说明完整的 pip install 命令。

60 秒快速上手

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.middleware.builtin import TelemetryMiddleware

# 1. Configure OpenTelemetry
resource = Resource.create({"service.name": "ag2-quickstart"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# 2. Wire the middleware
agent = Agent(
    "assistant",
    prompt="You are a helpful assistant.",
    config=OpenAIConfig(model="gpt-4o-mini"),
    middleware=[
        TelemetryMiddleware(
            tracer_provider=tracer_provider,
            agent_name="assistant",
        ),
    ],
)

# 3. Run — spans emit automatically
import asyncio
asyncio.run(agent.ask("What is the capital of France?"))

用于生产环境时，将 ConsoleSpanExporter 替换为 OTLPSpanExporter（或你的后端导出器），并将 SimpleSpanProcessor 替换为 BatchSpanProcessor。

Span 层级结构

每次 ask() 都会生成一个包含子项的根 Span：

invoke_agent assistant
  ├── chat gpt-4o-mini              # LLM API call
  ├── execute_tool get_weather      # tool execution
  ├── chat gpt-4o-mini              # LLM call after tool result
  └── await_human_input assistant   # human-in-the-loop

Span 类型

每个 Span 都有一个 ag2.span.type 属性：

ag2.span.type	操作名称	钩子
agent	invoke_agent	on_turn — 完整轮次
llm	chat	on_llm_call — 每次大模型调用
tool	execute_tool	on_tool_execution — 每个工具
human_input	await_human_input	on_human_input — 人机协同（HITL）

语义属性（GenAI semconv）

Span 携带标准 OpenTelemetry GenAI 属性：

属性	Span	说明
gen_ai.operation.name	全部	invoke_agent / chat / execute_tool / await_human_input
gen_ai.agent.name	agent、human_input	Agent 名称
gen_ai.provider.name	agent、llm	自动检测（openai、anthropic 等）
gen_ai.request.model	agent、llm	例如 gpt-4o-mini
gen_ai.response.model	llm	从响应中解析
gen_ai.response.finish_reasons	llm	例如 ["stop"]、["tool_calls"]
gen_ai.usage.input_tokens	llm	提示词 Token 数
gen_ai.usage.output_tokens	llm	补全 Token 数
gen_ai.usage.cache_creation_input_tokens	llm	提示词缓存写入量（Anthropic）
gen_ai.usage.cache_read_input_tokens	llm	提示词缓存读取量（Anthropic、OpenAI、Gemini）
gen_ai.tool.name	tool	工具函数名称
gen_ai.tool.call.id	tool	工具调用 ID
gen_ai.tool.type	tool	始终为 function

内容捕获（默认开启）

默认情况下，消息内容、工具参数和结果都会包含在 Span 中。这有助于调试，但可能泄露敏感数据：

TelemetryMiddleware(
    tracer_provider=tracer_provider,
    agent_name="assistant",
    capture_content=False,   # omit messages, tool args, results
)

启用后会出现以下附加属性：

属性	Span	内容
gen_ai.input.messages	llm	JSON 请求消息
gen_ai.output.messages	llm	JSON 响应消息
gen_ai.tool.call.arguments	tool	工具参数（JSON）
gen_ai.tool.call.result	tool	工具结果
ag2.human_input.prompt	human_input	向用户展示的提示词
ag2.human_input.response	human_input	用户的响应

对于对隐私敏感的后端（或遥测数据会离开你的基础设施的任何场景），请设置 capture_content=False。

构造函数参考

参数	类型	默认值	说明
tracer_provider	TracerProvider | None	全局 Provider	OpenTelemetry TracerProvider
capture_content	bool	True	在 Span 中包含消息 / 工具内容
agent_name	str | None	"unknown"	用于 Span 属性的 Agent 名称
provider_name	str | None	None	Provider 覆盖值（未设置时自动检测）
model_name	str | None	None	模型覆盖值（未设置时自动检测）

后端集成

TelemetryMiddleware 使用标准的 OpenTelemetry，因此任何兼容 OTLP 的后端都能使用：

• Jaeger — OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
• Grafana Tempo — 使用相同的 OTLP 导出器，并将其指向 Tempo 网关
• Langfuse、Honeycomb、Datadog — 使用特定于供应商的导出器；Agent 端的设置相同

对于由容器编排的技术栈，此仓库包含一个 tracing/ 目录，其中提供了用于 otel-collector + Grafana Tempo 的 Docker-Compose 配置。

深入了解

• website/docs/user-guide/telemetry.mdx — 完整的属性表、配置和示例。
• tracing/ — 用于本地 otel-collector + Tempo + Grafana 的 Docker 设置。
• 有关其他中间件（日志记录、重试、历史记录限制），请参阅 ag2-middleware。

常见问题

• 在生产环境中使用 SimpleSpanProcessor + ConsoleSpanExporter — 这是同步操作，会阻塞每次 span 发出。在开发环境之外，请使用 BatchSpanProcessor 和真正的导出器（OTLP / Jaeger / 供应商）。
• 遥测数据中泄露内容 — 默认情况下，capture_content=True。对于涉及隐私的提示词（个人身份信息、凭据），请设置 capture_content=False，并且审核后端保留的数据。
• 忘记调用 trace.set_tracer_provider(...) — 如果不调用，传递给中间件的 tracer_provider 没问题，但自动插桩的第三方库可能会使用不同的 provider。
• 缺少 Token 用量 — gen_ai.usage.* 要求 provider 客户端在响应中提供用量信息。流式 provider 可能只在结束时才发出用量信息；如果未看到这些信息，请检查 provider 的响应格式。
• Span 层级未显示父子关系 — 你的导出器或后端可能需要启用 OTLP/HTTP 路径，而不仅是 OTLP/gRPC。请检查两者。
• 与 AG2 Classic 的跟踪文档进行比较 — 语义属性格式相同；不同之处仅在于 Agent 插桩方法（AG2 Classic 使用 instrument_agent() / instrument_llm_wrapper() / instrument_pattern()；AG2 使用 TelemetryMiddleware）。