前面已经把业务问答拆成 Trace 与 Observations。现在假设同一套 Agent 给出了错误计划，我们不再重讲数据模型，直接用执行树定位第一个偏离用户目标的步骤。
记录实际走过的路
执行树必须记录实际发生的路径，包括被跳过的分支、并行查询、重试和降级。上一章的拆分原则继续适用：只为模型决策、检索、外部工具和可解释的业务转折建立节点，名称写业务动作。手动埋点时，在当前父节点的上下文里创建子节点：
from langfuse import get_client
langfuse = get_client()
with langfuse.start_as_current_observation(
name="analyze-campaign-anomaly",
as_type="agent",
input={"question": question},
) as agent:
with langfuse.start_as_current_observation(
name="query-campaign-metrics",
as_type="tool",
input={"date": "yesterday"},
) as tool:
rows = query_metrics(date="yesterday")
tool.update(output={"row_count": len(rows)})
answer = generate_answer(rows)
agent.update(output={"answer": answer})
代码只展示父子关系。真实接入还应把模型调用记录为 generation，并写入模型名称、消息、Token 和必要参数。使用上下文管理器的好处是结束时间和父节点关系不容易遗漏；如果改用手动创建方式，正常、异常和提前返回路径都要显式结束 Observation。
完成一次测试后，先别急着看答案。检查这次请求是否只有一棵执行树，工具和模型是否挂在正确父节点下，关键输入输出能否看见。所有节点平铺成互不相干的记录，往往是上下文没有传播；只看到根节点，则要检查框架回调或关键函数的埋点是否生效。
打开 Trace 后先看哪里
拿到一棵完整的树，排查就有了顺序。先看根节点的用户输入、最终输出、状态和总耗时，确认打开的是目标请求，也把症状说准确。这里的问题是“选错计划”，而不是“接口失败”。执行成功只说明流程跑完，不说明回答正确。
接着扫一遍执行树和时间线。树告诉你系统经过了哪些步骤，时间线告诉你哪些步骤并行、哪里发生等待。此时只找明显异常：缺失的检索、重复的工具调用、意外进入的降级分支、未结束的节点，或者耗时远超其他步骤的调用。不要一上来逐字阅读所有 Prompt，那通常既慢又容易被最后一个错误吸引注意力。
随后沿数据流往下走：
用户问题
→ 意图和时间范围
→ 检索到的业务口径
→ 工具名称与参数
→ 工具返回的数据
→ 交给模型的上下文
→ 最终回答
每走一步，只问一句：到这里，信息是否还支持用户原来的目标？
假设意图节点正确识别了“消耗异常”，工具输入却把昨天解析成了前天，那么第一个偏离点已经出现。后面的模型即使没有任何幻觉，也会基于错误日期给出错误答案。反过来，如果参数和返回数据都正确，模型却忽略了“只统计启用计划”的口径，才应该检查 Prompt、上下文组织和模型生成。
这套读法比按组件猜故障更可靠。工具报错时查依赖、权限和参数；工具成功但结果不符合业务预期时查数据源和口径；上游都正确而 Generation 偏离时再查模型。答案正确但响应很慢时，转到第 5 章的延迟与关键路径分析。
一次排查的产物应当是一条可验证的因果假设，例如：“路由表把 rate_limits 映射成了 billing，导致检索和工具选择错误。”修复后用同一问题重跑，确认偏离点消失。只写“模型效果不好”无法验证，也无法指导修改。
不知道 Trace ID 时怎么找
真实反馈往往只有一句模糊描述：“上午有个客户查询昨日投放，页面提示数据查询失败。”这时不要从海量记录里翻页，也不要先赌某个关键词。先用结构化条件缩小范围：时间、环境、用户或租户、Session、任务名称、步骤类型、错误级别和版本。剩下少量候选记录后，再用输入输出中的短语确认。
顺序之所以重要，是因为稳定字段比自然语言可靠。同一个问题可能有多种说法，错误提示也可能经过改写；userId、sessionId、environment 和场景名称更适合作为定位坐标。全文搜索适合“记得说过什么，但不记得编号”，不能补救缺失或口径混乱的字段。
在 Langfuse 的 Traces 或 Observations 表中，可以通过侧边栏组合筛选。v4 数据模型还提供 Filter Search Bar，例如：
environment:production level:ERROR type:TOOL startTime:>2026-08-18
多个条件默认使用 AND。数值与时间字段支持 >、>=、<、<=，文本支持通配符，前置 - 表示排除，嵌套元数据可以写成 metadata.region:cn。查找生产环境里耗时超过两秒的工具步骤，可以输入：
env:production type:TOOL latency:>2
裸词或短语会搜索 ID、名称、输入和输出，也可以用 output:"预算不足" 限定范围。v4 的全文检索按词匹配且忽略大小写，多词查询要求连续出现；error 不会自动命中 errors。Filter Search Bar 属于 Langfuse v4 数据模型能力。新建 Cloud 组织默认使用 v4；仍处于兼容期的旧组织可能保留切换入口。Langfuse Cloud 将在 2026-11-16 只运行 v4，届时移除遗留 API、功能和 ingestion 路径。自托管实例需要运行 v4，具体状态以项目页面和兼容矩阵为准。
筛选状态会进入 URL，适合把同一个结果集发给协作者；反复使用的条件可保存为 Saved View。分享时留意时间范围，绝对时间比“最近一小时”更容易复现当时现场。
如果仍然搜不到，回头检查时区、环境字段、身份字段是否真的上报，目标文本位于 input、output 还是 metadata，以及筛选条件是否互相排斥。观测平台只能查询收到的数据。工具参数没有记录、节点关系错误或生产与测试环境混在一起，搜索框再强也还原不了现场。
排查顺序可以稳定下来：先把动态执行记录成树，再从症状出发寻找最早偏离点；不知道目标记录时，先用稳定字段缩小范围，再用内容确认。Langfuse 提供了具体界面和查询语法，换成其他平台，排查逻辑依然成立。
参考资料
系列目录：AI 应用可观测性与评估