Langfuse v4 排障指南：精准定位 Observation 级问题

一个智能运维Agent处理告警的典型工作流：它会先识别告警类型，随后并行查询指标数据、日志、分布式链路追踪、发布记录和工单系统；过程中可能调用RAG检索知识库、生成根因假设、触发工具执行、甚至派发子Agent进行风险检查，最终通过LLM-as-a-Judge对输出质量进行评估。

许多团队在将Agent首次接入真实业务时，会本能地采取一个关键步骤：将整条调用链完整记录到trace中。这至关重要，没有trace，就无法洞察一次回答背后的完整执行过程。

然而，当Agent逻辑真正复杂起来后，trace会迅速从清晰的“证据链”演变为令人困扰的“长卷轴”。表面一次用户请求，内部可能包含数十乃至数百个操作。如果可观测性仍停留在“打开一条trace手动向下滚动”的模式，故障排查体验将急剧恶化：

• 定位最慢的模型调用，需要先猜测哪条trace可疑。
• 查找失败的工具调用，必须逐一手动展开子节点。
• 分析某个检索器是否频繁超时，必须从请求维度绕回进行聚合计算。
• 执行线上评测，只能评估整个workflow，难以精准聚焦关键步骤。
• 按用户、会话、环境等维度聚合分析时，常发现这些关键字段仅挂在trace上，操作层无法直接关联。

这不仅是“界面不友好”的问题，其根源在于数据模型的粒度从根本上已不匹配。

Langfuse v4 Fast Preview值得重点关注，正是因为它将这个问题向前推进了一步：它不再将trace作为主要分析对象，而是将每一次模型调用、检索、工具执行、Agent步骤都提升为统一的“观察点”（observations）。trace依然存在，但其角色更像一个关联ID，用于将一组observation串联起来。

这一变化传递的信号非常明确：生产级LLM应用的可观测性，正从“请求级可见”转向“操作级可查询”。

Trace不够细，问题就会藏起来

在传统后端服务中，一次HTTP请求通常对应一条结构相对稳定的调用链。但Agent的执行路径并非固定。模型可能根据上下文动态决定是否调用工具，工具的结果又会反过来影响下一轮推理。RAG的召回数量、模型的重试、子Agent的分工、人工确认的介入、评测的采样，都会让同一个入口请求产生形态各异的执行轨迹。

这导致一个常见错觉：我们已经有了trace，因此具备了可观测性。但在实际排障中，工程师关心的往往不是“这条请求整体发生了什么”，而是更具体、更聚焦的问题：

• 过去30分钟，哪个模型调用延迟最高？
• 哪个工具的错误率最突出？
• 哪类检索步骤引入了最多的上下文？
• 哪个Agent步骤消耗了最多的token？
• 特定用户的会话中，失败是否都集中在同一个工具上？
• 新提示词上线后，忠实度（groundedness）评分下降具体发生在哪一步？

这些问题的共性是：它们天然发生在“操作”层面，而非“请求”层面。如果系统必须先定位trace，再展开其内部结构进行查找，排障就会退化为手工翻阅一棵棵调用树。数据量小时尚可忍受；一旦Agent链路变长、变复杂，trace就会从一个清晰的视图，变成一个需要费力挖掘的“容器”，而非分析问题的直接“入口”。

变化：Observation成为一等公民

Langfuse v4的核心变化可概括为：将原本分散在trace和observation上的数据，收敛到observation级别，使每一次具体操作都能被直接查询、过滤、聚合和评分。

这带来了几个关键的工程含义。

首先，trace无需承载过多业务字段。user_id、session_id、metadata、tags等维度，需要传播到每一个observation上。这样，当需要查询“某个用户的所有慢调用”时，就不再需要对observation和trace进行额外的关联查询。

其次，输入输出应尽量落在具体操作上。一次Agent运行的最终答案固然重要，但排障时更关键的是每一步的细节：输入内容、输出结果、调用的模型、耗时、token消耗、是否调用工具、工具返回是否异常。

第三，评测也需要下沉。许多线上LLM-as-a-Judge的评估，不应只给整条trace打一个总分。例如在RAG场景中，“检索结果是否相关”、“回答是否忠于上下文”、“工具调用参数是否安全”，这些评分更适合挂在具体的observation上。

这不是要删除trace，而是重新分工：

• trace_id 用于串联一次完整运行。
• observation 用于表达一次具体操作。
• metadata 用于过滤和聚合。
• score 用于表达质量判断。
• session_id 用于跨多次请求还原用户上下文。

从这个角度看，Langfuse v4的“observation-first”理念，不仅是一个UI调整，更是提醒开发者需要重新设计Agent的遥测数据结构。

埋点时先定义操作字典

许多Agent项目埋点混乱，根源在于初期未对“操作”进行清晰命名。建议在应用侧先定义一份最小化的操作字典，避免在trace数据膨胀后再回头补救。

observations:
  - name: agent.plan
    type: span
    purpose: 生成任务计划
  - name: retrieval.runbook.search
    type: retrieval
    purpose: 检索历史预案和复盘
  - name: tool.prometheus.query
    type: tool
    purpose: 查询指标
  - name: generation.root_cause_summary
    type: generation
    purpose: 生成根因分析
  - name: eval.answer_groundedness
    type: score
    purpose: 判断回答是否忠于证据

命名需稳定，粒度需克制。避免将每一次自然语言描述都塞进observation name，也不应将所有工具调用笼统地命名为tool_call。稳定命名的价值在于，后续可直接基于这些名称创建保存视图、仪表盘、告警规则和评测任务。

例如，一个智能运维Agent至少应能让工程师快速查看以下视图：

• 所有生成类操作，按总成本降序排列。
• 所有检索类操作，且延迟超过2秒的。
• 名为tool.prometheus.query且级别为ERROR的操作。
• 名为generation.root_cause_summary的操作，按使用的模型分组统计。
• 当前会话中，所有级别为WARN或ERROR的操作。

这些查询不应依赖人工翻阅trace。它们应是值班工程师打开系统后，能直接点击的一键入口。

属性传播要尽早做

在Langfuse v4中，一个关键的迁移动作是将trace级别的属性传播到observation。Python SDK v4中，可使用propagate_attributes()将用户、会话、版本、标签和metadata下发到当前上下文中的所有子observations。

from langfuse import observe, propagate_attributes

@observe(name="incident-agent-run")
def handle_alert(alert: dict, user_id: str, session_id: str):
    with propagate_attributes(
        trace_name="incident-triage",
        user_id=user_id,
        session_id=session_id,
        version="2026-04-29",
        metadata={
            "env": "prod",
            "agent": "incident-triage",
            "service": alert["service"],
            "tenant": alert["tenant"],
        },
        tags=["agent", "sre", "prod"],
    ):
        runbooks = retrieve_runbooks(alert)
        metrics = query_prometheus(alert)
        return summarize_root_cause(alert, runbooks, metrics)

这里最容易踩的坑是调用时机过晚。如果前几个模型调用已经发生，之后才传播user_id或session_id，那么早期的observations将缺失这些字段。后续按用户、会话、租户进行聚合分析时，数据就会天然缺失一块。

另一个边界是，metadata不应承载大块的业务数据。适合放入的是那些可过滤、可聚合、低基数或受控基数的字段，例如环境、Agent名称、服务名、租户、风险等级、版本号。而完整的提示词、工具返回结果、检索内容、用户输入等高敏感或大体积内容，应根据合规和成本策略单独处理。

用OpenTelemetry接入时，别只转发所有span

许多团队已部署OpenTelemetry Collector，希望将Agent的观测数据统一接入现有链路。这个思路正确，但需注意两点。

若直接通过OTLP协议写入Langfuse v4 Fast Preview，需要带上v4的ingestion header：

export OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${AUTH_STRING},x-langfuse-ingestion-version=4"

若使用Collector，可在exporter配置中添加header：

exporters:
  otlphttp/langfuse:
    endpoint: "https://cloud.langfuse.com/api/public/otel"
    headers:
      Authorization: "Basic ${AUTH_STRING}"
      x-langfuse-ingestion-version: "4"

但更重要的是，需要选择哪些span应进入LLM可观测性系统。Agent运行时确实涉及HTTP请求、数据库查询、队列、缓存、浏览器自动化以及内部RPC调用。问题是，若将所有底层span不加筛选地灌入，表面上数据更完整，实际上会带来三个副作用：

1. 噪声增大：关键的LLM操作容易被基础设施span淹没。
2. 成本上升：观测系统的存储和查询压力会增加。
3. 权限管理更复杂：底层span可能携带不应进入LLM平台的敏感字段。

更稳妥的方式是，将LLM应用的核心操作打成清晰的observation，同时保留跳转到通用APM（应用性能监控）系统的关联字段。

Langfuse observation:
   name = generation.root_cause_summary
   trace_id = ...
   session_id = ...
   model = ...
   token_usage = ...
   cost = ...
   apm_trace_id = ...

APM trace:
   http.request
   db.query
   redis.get
   queue.publish

这样分工明确：LLM平台负责回答“Agent的哪一步在质量、成本、延迟上出现了异常”，而APM系统负责回答“底层的系统组件为何变慢或出错”。

评测应该跟着操作粒度走

Agent评测最常见的误区，是仅评估最终答案。最终答案当然要评，但它无法定位问题具体出在哪里。

一个错误的回答可能源于多种原因：检索未召回关键文档；检索召回了，但重排序顺序不当；上下文过长，模型忽略了核心证据；工具参数错误，获取了错误时间窗口的数据；子Agent总结时丢失了约束条件；最终生成时编造了无证据的结论。

若仅在trace末尾挂一个总分，修复路径仍然是模糊的。

更实用的做法是将评测拆解到关键的observation上：

evaluators:
  - target: retrieval.runbook.search
    score: retrieval_relevance
    type: categorical
    values: ["good", "partial", "bad"]
  - target: tool.prometheus.query
    score: parameter_safety
    type: boolean
  - target: generation.root_cause_summary
    score: groundedness
    type: numeric
    range: [0, 1]
  - target: generation.root_cause_summary
    score: needs_human_review
    type: boolean

在开发阶段，可用experiments比较不同的提示词、模型、检索参数或工具策略；上线后，则将少量高价值的evaluator放到observation级别，持续监控真实流量。

这样做的好处是，质量问题能被定位到具体层面：

• 不再是笼统的“这个Agent最近变差了”。
• 而是“runbook检索的partial比例上升了”。
• 或“Prometheus查询参数安全检查失败次数增加了”。
• 或“同一模型下，忠实度降低的问题集中在某个服务上”。

这才是工程团队能够直接着手处理的具体问题。

落地时的迁移顺序

如果已有线上运行的Agent，不建议一次性重写所有埋点。可按以下顺序推进：

1. 列出核心的workflow。
2. 为每个workflow定义5到10个关键的observation。
3. 统一observation的name、type、metadata、tags规范。
4. 尽早传播user_id、session_id、环境、Agent名称、版本号等属性。
5. 为模型调用、检索、工具调用补齐延迟、token消耗、成本、状态等字段。
6. 建立3个核心的保存视图：慢调用、失败的工具、高成本的模型调用。
7. 先将一两个关键的evaluator迁移到observation级别。
8. 再考虑扩展experiments、仪表盘、告警和自动回归测试。

这里的核心不是“把数据打满”，而是先让团队能够回答排障时最高频的那几个问题。

以智能运维Agent为例，可先聚焦：

• 告警类型识别是否稳定？
• 检索是否召回了正确的runbook？
• 指标查询是否命中了正确的服务和时间窗口？
• 根因总结是否忠于证据？
• 人工审批前的风险判断是否过于宽松？

将这些关键点观测清楚后，再逐步扩展到更多的工具和子Agent。

边界：Observation-first不是万能药

Observation-first解决的是查询和分析粒度的问题，但它不会自动解决Agent的可靠性问题。落地时有几个边界需要守住。

第一，不要把observation表当作日志桶。LLM可观测性系统应保留对模型、检索、工具和评测有意义的字段。大段的系统日志、完整的文档内容、原始的用户隐私数据，不应无脑地塞入。

第二，trace仍然重要。当需要还原一次完整事故、理解模型为何连续做出几个决策、检查子Agent之间如何交接时，trace的树状结构仍是最自然的叙事方式。Observation-first只是让日常的筛查和聚合不再被trace这个“容器”卡住。

第三，命名和标签比工具本身更重要。如果observation的名字今天叫search_docs，明天叫rag_lookup，后天又叫knowledge_tool_call，那么再好的数据表也聚合不出稳定的结论。

第四，评测要控制成本和偏差。Observation级别的evaluator更细，但也更容易变得数量庞大。在生产环境中，应优先评估高风险、高成本、高影响的步骤，并结合采样、阈值和人工复核，避免让评测本身变成新的成本负担和噪声来源。

真正改变的是排障入口

Agent进入生产环境后，最怕的不是“完全不可见”，而是“看起来什么数据都有，但排障仍然要靠人工翻阅”。

Langfuse v4的observation-first理念指出的方向很直接：不要把一次Agent运行仅仅看作一条请求；要把它拆解成一组可命名、可查询、可评分、可聚合的具体操作。

这会改变团队的埋点习惯：

• 从问：“这条trace里面发生了什么？”
• 到问：“哪一类observation正在变慢、变贵、变差？”

对于智能运维、RAG、客服Agent、代码Agent这类长链路应用来说，这个变化非常实际。因为生产环境的问题通常不会直接告诉你“我在第17层节点里”。它只会表现为延迟上升、成本异常、答案质量下降、工具调用错误、用户追问增多。

能否快速将这些症状定位到具体的observation，正在成为LLM应用工程能力的关键组成部分。