一、OpenTelemetry 功能概述
OpenTelemetry（简称 OTel）是一个开源的可观测性框架，由云原生计算基金会（CNCF）维护，已成为云原生环境下遥测数据收集的事实标准。
核心功能
1. 统一的可观测性信号采集
OpenTelemetry 支持采集三类核心遥测数据：
- 链路（Traces）：记录请求在分布式系统中的完整调用路径，由多个跨度（Span）组成，用于发现性能瓶颈
- 指标（Metrics）：长期的数值测量结果（如CPU利用率、请求速率），适合实时监控和告警
- 日志（Logs）：特定时间点的离散事件记录，适合故障排查和调试
三者通过共享的上下文传播机制相互关联，提供完整的应用行为视图。
2. 厂商中立、可插拔架构
使用 OpenTelemetry API 完成一次代码插桩，即可将遥测数据导出到任意可观测性后端（Jaeger、Prometheus、商业产品等），切换后端无需修改应用代码。
3. 零代码（自动）插桩
支持无需修改源代码即可为流行的库和框架自动生成遥测数据，大幅降低接入成本。
4. OpenTelemetry Collector
提供可部署为代理（Agent）或网关（Gateway）的收集器服务，支持对遥测数据进行接收、处理、过滤和路由，拥有200+ 组件。
5. 多语言支持
提供 12+ 种语言的原生 SDK，包括 Java、Python、Go、JavaScript、.NET、Ruby、C++ 等。
6. 上下文传播
自动在服务边界间关联分布式追踪，使分布式上下文贯穿整个请求路径。
二、将 Agent 集成数据上报到 Langfuse
Langfuse 本身是一个 OpenTelemetry 后端，任何支持 OpenTelemetry SDK 的语言都可以通过 OTLP（OpenTelemetry Protocol）协议将追踪数据发送到 Langfuse。
核心原理
Langfuse 接收符合 OTLP 规范的遥测数据，通过标准 HTTP 协议（暂不支持 gRPC）将数据发送到 Langfuse 的 OTLP 端点：
https://cloud.langfuse.com/api/public/otel认证方式为 Basic Auth，使用项目的 Public Key 和 Secret Key 构建认证头。
两种主要集成方式
方式一：应用内直接集成（SDK 方式）
适用于大多数场景，在 Agent 应用中直接配置 OpenTelemetry SDK 导出到 Langfuse。
通用配置步骤：
-
获取 Langfuse 凭证：在 Langfuse 项目中获取 Public Key 和 Secret Key
-
配置环境变量（所有语言的 OTel SDK 都支持）：
bash
OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64编码的凭证>"- 在 Agent 执行时创建 Span ：对于 LLM 调用，在 Span 上设置
gen_ai.*属性（遵循 GenAI 语义约定），Langfuse 会自动将其识别为 Generation 类型，并提取模型名称、Token 用量和成本信息
各语言示例：
| 语言 | 集成方式 |
|---|---|
| Java | 使用 OpenTelemetry Java Agent 零代码插桩，通过环境变量配置即可；LLM 调用可配合 OpenLLMetry 实现自动插桩 |
| Go | 使用标准 OTel Go SDK，在 LLM 调用 Span 上设置 gen_ai.* 属性，或使用 OpenLIT 实现自动插桩 |
| Python | 使用 OpenTelemetry Python SDK，或通过 OpenLIT 等工具自动捕获 Agent 框架的操作 |
| C#/.NET | 使用 OTel .NET SDK，在 Activity 上设置 gen_ai.* 标签 |
示例：Python + AutoGen 集成：
python
# 1. 安装依赖
# pip install langfuse openlit autogen-agentchat autogen-ext[openai]
# 2. 配置环境变量
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_BASE_URL"] = "https://cloud.langfuse.com"
# 3. 初始化 OpenLIT 自动插桩
import openlit
openlit.init(tracer=langfuse._otel_tracer, disable_batch=True)方式二：通过 OpenTelemetry Collector 中转
若需要对遥测数据进行过滤、增强或路由到多个后端，可在应用与 Langfuse 之间部署 OpenTelemetry Collector 作为中间层。Collector 配置 Langfuse Exporter 后将数据转发至 Langfuse。
关键配置要点
- 端点地址 ：Langfuse OTLP 端点为
/api/public/otel，追踪路径为/api/public/otel/v1/traces - 协议：必须使用 OTLP over HTTP（protobuf 或 JSON），不支持 gRPC
- GenAI 语义约定 ：带有
gen_ai.*属性的 Span 在 Langfuse 中渲染为 Generation；其他 Span 作为普通 Observation - 用户/会话上下文 ：在 Span 上设置
user.id和session.id属性可关联用户和会话
在 Langfuse 中查看数据
数据上报成功后，可在 Langfuse 控制台查看：
- Trace 列表：所有 Agent 执行记录（时间戳、延迟、Token 用量）
- Trace 时间线：完整的 Span 层次结构（Agent 动作、LLM 调用、工具调用、规划步骤）
- 输入/输出详情：Prompt 和模型返回内容
- 分析仪表板：成本、延迟、使用趋势
总结
OpenTelemetry 提供了标准化的可观测性数据采集能力，而 Langfuse 作为 OTel 后端，使得任何支持 OTel 的 Agent 框架（无论是 Java、Python、Go 还是其他语言）都可以通过简单的环境变量配置或少量代码改动，将完整的 Agent 执行链路（LLM 调用、工具调用、规划步骤等）上报到 Langfuse 进行统一的可视化追踪和分析。