从 OpenTelemetry 到 Langfuse：企业级 Agent 可观测性实践

引言

随着大语言模型（LLM）和智能体（Agent）在企业应用中的深入部署，可观测性（Observability）的重要性日益凸显。传统上，我们依赖OpenTelemetry（OTel）来监控微服务的指标、日志和链路追踪。然而，当应用的核心逻辑由LLM驱动，涉及复杂的提示词（Prompt）、模型调用、工具使用（Tool Use）和记忆（Memory）时，OTel提供的底层基础设施视图便显得力不从心。我们不仅需要知道“服务是否健康”，更需要理解“Agent的思考过程是否正确”、“决策依据是什么”以及“最终结果为何”。

本文将阐述如何从基于OpenTelemetry的传统可观测性，演进到针对Agent应用的、以Langfuse为代表的专用可观测性实践，并提供一套通用的实施框架。

原理要点

OpenTelemetry 的局限与补充

OpenTelemetry 是一个强大的可观测性框架，它通过统一的API、SDK和 Collector，收集分布式系统的 traces、metrics 和 logs。对于传统的HTTP服务、数据库调用，它能提供完整的调用链和性能分析。

但在LLM/Agent场景中，OTel的trace可能只记录了一次“调用LLM API”的HTTP请求，而丢失了关键的业务语义：

• 提示词内容：发送给模型的具体指令是什么？
• 模型响应：模型返回的完整文本是什么？
• 内部步骤：Agent是否进行了工具调用？调用了几次？参数是什么？
• 业务指标：提示词长度、Token消耗、用户满意度等。

因此，我们需要在OTel之上，或与之并行，引入一个能够捕获和存储这些高层语义信息的层。

Langfuse 的核心价值

Langfuse 是一个开源的LLM应用可观测性平台。它的核心设计目标是追踪LLM应用的完整上下文，而不仅仅是网络请求。它关注：

1. 追踪（Trace）：一个完整的用户会话或任务流程，可能包含多次LLM调用。
2. 会话（Session）：与特定用户或交互相关的多个追踪的集合。
3. 观察（Observation）：一次具体的LLM调用或Agent内部步骤，包含输入、输出、元数据（如模型名、Token数）。
4. 评分（Score）：对追踪或观察结果的人工或自动评估。

Langfuse 与 OTel 并非替代关系，而是互补。OTel 负责基础设施层的可观测性，Langfuse 负责应用业务层的可观测性。

实战步骤

步骤一：基础环境搭建与OTel集成

首先，确保你的应用已通过OTel SDK进行基础埋点。这通常涉及在应用启动时初始化OTel Tracer。

# 通用Python OTel初始化示例
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# 设置Tracer Provider
tracer_provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="
tracer_provider.add_span_processor(processor)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

步骤二：集成Langfuse SDK

在应用中引入Langfuse SDK，并在关键业务逻辑处进行埋点。

# 通用Python Langfuse集成示例
from langfuse import Langfuse

# 初始化Langfuse客户端
langfuse = Langfuse(
    host=" # 占位地址
    public_key="your-public-key",
    secret_key="your-secret-key"
)

# 创建一个追踪，代表一个完整的Agent任务
trace = langfuse.trace(name="user-assistant-interaction", user_id="user-123")

# 在Agent执行关键步骤时创建观察
with trace.span(name="llm-call-step-1") as span:
    # 模拟调用LLM
    prompt = "请总结以下文本：..."
    response = call_llm_api(prompt) # 你的LLM调用函数

    # 将关键信息记录到Langfuse观察中
    span.update(
        input=prompt,
        output=response,
        model="gpt-4",
        metadata={"token_count": len(response)}
    )

# 在任务结束时，可以添加评分
trace.update(score=4, name="user-satisfaction")

步骤三：关联OTel与Langfuse

为了获得更完整的视图，可以尝试将Langfuse的Trace ID与OTel的Span ID进行关联。这需要在OTel的Span中注入Langfuse的Trace ID，并在Langfuse的观察中记录OTel的Span ID。

# 在OTel Span中注入Langfuse Trace ID
with tracer.start_span("external-api-call") as otel_span:
    otel_span.set_attribute("langfuse.trace_id", trace.id)
    # ... 执行外部API调用

# 在Langfuse观察中记录OTel Span ID
span.update(
    input=prompt,
    output=response,
    metadata={"otel_span_id": otel_span.span_context.span_id}
)

步骤四：数据可视化与分析

通过Langfuse的Web UI，你可以查看：

• 所有追踪和观察的列表，按时间、名称、用户等过滤。
• 单个追踪的详细步骤分解，包括每次LLM调用的输入输出。
• 模型性能分析，如不同模型的Token消耗、延迟对比。
• 提示词版本管理和A/B测试。

常见坑与排查清单

1. 埋点粒度不当：
   • 坑：只在最外层调用LLM时埋点，丢失了Agent内部多步推理的细节。
   • 排查：检查Agent代码，确保每个工具调用、每个决策分支都创建了一个Langfuse span 或 observation。
2. 数据量过大导致成本激增：
   • 坑：无差别记录所有LLM调用的完整输入输出，尤其是长文本。
   • 排查：在Langfuse配置中设置采样率，或对长文本进行截断/摘要后再记录。利用Langfuse的metadata字段记录关键摘要信息。
3. OTel与Langfuse数据割裂：
   • 坑：两个系统独立运行，无法关联分析。例如，知道Langfuse中某个追踪慢，但不知道底层网络或数据库的延迟。
   • 排查：实施步骤三中的ID关联。确保OTel Collector和Langfuse实例都能访问到相同的关联标识。
4. 生产环境性能影响：
   • 坑：同步发送大量可观测性数据到OTel Collector和Langfuse，阻塞主业务线程。
   • 排查：使用OTel的异步导出器（BatchProcessor）。对于Langfuse，确保其SDK使用异步或后台线程发送数据。监控应用自身的CPU和内存使用率。
5. 敏感信息泄露：
   • 坑：无意中记录了用户隐私数据或敏感业务信息到Langfuse。
   • 排查：在埋点代码中增加过滤逻辑，或使用Langfuse的mask功能对特定字段进行脱敏。

小结

企业级Agent的可观测性是一个分层体系。OpenTelemetry构成了坚实的底层基石，负责监控基础设施的健康与性能。而Langfuse等专用工具则在此基础上，构建了面向LLM应用业务语义的观测层，让我们能够洞察Agent的“思考”与“决策”过程。

实践的关键在于互补与关联：不要抛弃OTel，而是将其与Langfuse结合，通过ID关联打通两层数据。同时，根据业务需求谨慎选择埋点粒度，平衡可观测性的深度与系统开销。通过这套实践，工程师不仅能确保Agent应用的稳定运行，更能持续优化其智能与效率。