可观测性与 OpenTelemetry 集成

可观测性与 OpenTelemetry 集成

学习目标

本章要解决什么问题：AutoGen 如何集成 OpenTelemetry 实现 Agent 调用链路的可观测性。你将学到：

• 三个核心 Trace Span 的设计
• 事件日志（Event Log）与 Trace 的双轨架构
• 如何自定义 TracerProvider 接入 Jaeger 等后端

项目实践

三个核心 Span

AutoGen 在 Core 层定义了三个 Trace Span：

trace_create_agent_span(tracer, agent_type, metadata)
trace_invoke_agent_span(tracer, agent_id, message_type, metadata)
trace_tool_span(tracer, tool_name, arguments, metadata)

Span	触发时机	关键属性
CreateAgent	注册 Agent 工厂时	agent_type, provider
InvokeAgent	调用 Agent 消息处理方法时	agent_id, message_type, duration
Tool	执行工具调用时	tool_name, arguments

双轨架构：Trace + Event Log

两个系统的区别：

维度	Trace（OpenTelemetry）	Event Log（Python logging）
用途	调用链路分析	业务事件记录
后端	Jaeger, Grafana	JSON 文件, ELK
性能开销	低（采样）	中（每事件都记录）
可查询性	链路与耗时	事件内容和类型

消息级别事件

# 运行时记录的事件类型
MessageEvent              # 消息成功处理
MessageDroppedEvent       # 消息被丢弃（订阅不匹配等）
MessageHandlerExceptionEvent  # 消息处理异常
AgentConstructionExceptionEvent  # Agent 构建异常

每个事件包含：

• message_id：消息唯一标识
• sender / recipient：发送者和接收者
• delivery_stage：投递阶段
• exception：异常信息（仅异常事件）

接入自定义 TracerProvider

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.jaeger.thrift import JaegerExporter
from autogen_core import SingleThreadedAgentRuntime

jaeger_exporter = JaegerExporter(agent_host_name="localhost", agent_port=6831)
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(jaeger_exporter))

runtime = SingleThreadedAgentRuntime(tracer_provider=tracer_provider)

内部机制：SingleThreadedAgentRuntime 接受可选的 TracerProvider，如果提供则在每个 Span 创建时使用该 Provider。

问题与规避

Telemetry 性能开销

陷阱：每次消息处理都创建 Span，在高吞吐场景下可能增加显著延迟。

规避策略：

• 使用 BatchSpanProcessor 批量导出，而非逐个导出
• 配置采样率（如 10% 采样），减少 Span 数量
• 在生产环境中使用 NoOpTracerProvider 完全禁用

事件日志的存储增长

陷阱：结构化事件日志持续增长，占用磁盘空间。

规避策略：

• 使用 JSON 格式输出，配合日志轮转工具（logrotate）
• 仅在生产环境中启用 EVENT_LOGGER_NAME
• 对异常事件设置单独的日志文件，便于监控告警

设计取舍

为什么选 OpenTelemetry 而非自定义日志？

OpenTelemetry 的优势：

• 标准化接口：对接 Jaeger、Grafana、Datadog 等后端无需额外开发
• Trace 上下文：自动关联 Agent 调用链路
• 多语言支持：AutoGen 有 .NET 版本，OTel 提供跨语言一致性

代价：

• 增加了一个依赖（opentelemetry-api、opentelemetry-sdk）
• 用户需要配置 TracerProvider 才能使用

为什么 Trace 和 Event Log 分开？

Trace 适合回答”调用链中哪里慢了”，Event Log 适合回答”发生了什么业务事件”。两者的查询模型和优化方向不同，分开设计可以让各自专注于最佳实践。

参考来源

• OpenTelemetry Python — OpenTelemetry Python SDK
• 源码验证：autogen-core/_telemetry/（Trace 工具封装）
• 源码验证：autogen-core/logging.py（事件定义）