链路追踪

当一次应用、工作流或知识库调用出现结果错误、响应缓慢、Token 消耗异常或执行失败时，仅查看最终结果通常无法判断问题发生在哪一步。链路追踪会记录一次执行中的调用关系、输入输出、耗时、Token 和状态，帮助你从整条执行过程定位到具体调用。

本页将帮助你完成以下任务：

• 找到一次具体执行对应的 Trace；
• 读懂 Trace、Span 和 Span 树；
• 排查执行失败、结果错误、响应缓慢和 Token 消耗过高；
• 修复问题后验证结果；
• 安全地查看和分享链路数据。

一、先判断应该查看哪里

应用日志、链路追踪和统计分析关注的范围不同：

你要解决的问题	建议入口
某位用户反馈某次回答不正确	先查应用日志，定位用户、会话或消息
想知道模型、知识检索、工具或工作流中的哪一步有问题	链路追踪
想查看一次执行各调用步骤的输入、输出、耗时和 Token	链路追踪
想判断错误或性能问题是否普遍发生	统计分析
想观察一段时间内的调用量、错误量和 Token 趋势	统计分析

推荐排查顺序：

应用日志定位目标请求 → 链路追踪分析单次执行 → 统计分析判断影响范围

应用日志与统计分析的具体用法，分别参见日志与分析和统计分析。

二、核心概念

2.1 Trace：一次完整执行

Trace 是一次端到端执行的观测记录。例如：

• 用户在应用中发送一次消息；
• 试运行一次工作流；
• 发起一次知识库检索；
• 单独调用一次模型。

每条 Trace 都有唯一的 Trace ID，用于准确识别这一次执行。链路列表中的服务名称、入口类型、Token、运行时长、状态和时间，都是这条 Trace 的整体信息。

2.2 Span：执行中的一次操作

Span 是 Trace 中记录的一次具体操作，例如工作流执行、提示词处理、模型调用或知识检索。每个 Span 都有自己的 Span ID、类型、状态、耗时、输入和输出。

多个 Span 按调用关系组成 Span 树：

• Root Span 是整条 Trace 的入口；
• 子 Span 表示入口执行过程中继续发生的调用；
• 父 Span 的耗时通常包含其子 Span 的运行时间；
• 一个工作流画布节点可能产生一个或多个 Span。

因此，Span 不等于工作流画布上的业务节点。链路列表虽然以“工作流（8 个节点）”等形式展示数量，但这里表示本次 Trace 记录的 Span 数，不一定等于画布上的节点数。

2.3 三种 ID 的区别

标识	含义	用途
Trace ID	一次完整执行的唯一标识	搜索并定位整条链路
Span ID	一次具体操作的唯一标识	定位模型调用、检索或其他具体步骤
Root Span ID	入口 Span 的标识	确认整条链路的起点

向其他人员提交问题时，优先提供 Trace ID、问题发生时间和服务名称；需要定位到具体调用时，再补充 Span ID。

三、进入链路追踪

在左侧菜单中进入 应用观测 → 链路追踪。工作流试运行、应用调试等执行完成后，Trace 会立即出现在链路列表中，不需要等待数据同步。

工作流试运行页面会显示整体耗时和 Token，但不会直接展示 Trace ID。进入链路追踪后，可以根据服务名称、执行时间、耗时和 Token 找到对应记录。

四、查找目标 Trace

页面顶部提供服务、Span 类型、时间范围、Trace ID 和状态筛选。设置条件后点击 立即查询，点击 重置条件可恢复默认。

4.1 已知 Trace ID

将完整 Trace ID 粘贴到 Trace ID 输入框并立即查询。这是最准确的定位方式，不受服务重名或同一时间存在多次调用的影响。

API 调用返回了 trace_id 时，应优先使用该值查询。

4.2 不知道 Trace ID

按以下顺序缩小范围：

1. 在 服务 中选择应用、工作流或知识库；
2. 将 时间范围缩小到问题发生时间；
3. 根据问题表现选择正常或异常状态；
4. 结合列表中的 Token、运行时长和时间确认目标记录。

如果刚完成执行却没有找到记录，先检查当前工作空间、服务、时间范围、Span 类型和状态条件，再点击列表右上角 刷新。Trace 写入不存在等待延迟，不需要反复等待同步。

4.3 Span 类型怎样筛选

Span 类型按 Trace 的入口 Span 类型筛选，而不是搜索 Trace 内部是否包含某类子 Span。

例如，选择“模型调用”后，列表只显示入口类型为模型调用的 Trace。一个入口类型为工作流的 Trace，即使其内部包含模型调用 Span，也不会出现在结果中。

因此：

• 查完整工作流执行时选择“工作流”；
• 查独立模型调用时选择“模型调用”；
• 查独立知识检索时选择“检索”；
• 不确定入口类型时保持“全部”。

4.4 链路列表怎么看

列	含义
Trace ID	本次执行的唯一标识，可复制
服务名称	产生本次执行的应用、工作流或知识库
Span 类型	入口类型及本次 Trace 的 Span 数
Token 数量	本次执行汇总的 Token
运行时长	本次执行从开始到结束的整体耗时
状态	正常或异常
时间	本次执行的开始时间
详情	打开 Trace 详情

服务类型和入口类型不是同一个概念。例如，一个应用内部采用工作流编排时，可以显示“服务类型：应用、入口类型：工作流”。

五、读懂 Trace 详情

点击链路列表中的 详情。页面分为顶部概览、左侧 Span 树、中间运行数据与元数据、右侧 Span 属性四部分。

5.1 顶部概览

顶部展示整条 Trace 的：

• 服务名称和状态；
• 总耗时和总 Token；
• Trace ID 与 Root Span ID；
• Span 数；
• 服务类型与入口类型；
• 开始时间。

这里适合确认“当前打开的是不是目标执行”，以及快速判断整体是否异常、是否耗时或 Token 偏高。

5.2 Span 树

Span 树按父子关系展示本次执行记录的调用步骤。每个 Span 通常显示名称、类型、耗时，涉及模型调用时还会显示 Token。

点击任一 Span，中间和右侧区域会切换为该 Span 的数据。排查时应沿树逐层展开，而不是只查看 Root Span。

页面中可能出现工作流、Agent、图执行、lambda 函数、提示词、模型调用、检索等类型。类型用于说明当前记录的操作性质；实际可见类型取决于本次执行包含的能力。

5.3 运行数据

运行数据展示当前 Span 已记录的：

• 输入：该操作实际收到的数据；
• 输出：该操作实际产生的数据；
• 错误：异常 Span 的错误信息。

输入和输出支持 文本 / JSON 两种视图。数据结构较深时，优先使用 JSON 视图核对字段层级、变量值和数组内容。

5.4 元数据

元数据用于查看当前 Span 的业务标签和系统标签，例如应用、工作流、服务、运行环境和错误信息。

元数据不是工作流的输入变量。它主要用于确认调用属于哪个业务对象、关联其他日志，以及读取系统记录的错误信息。

5.5 Span 属性

右侧展示当前 Span 的状态、Span ID、类型、原始名称、耗时、开始时间和 Token。

涉及模型调用时，通常可以看到：

• 输入 Token；
• 输出 Token；
• 总 Token。

非模型调用或在模型调用前就失败的 Span，Token 可能为 0。

六、排查执行失败

6.1 定位真正的错误来源

一项底层调用失败后，上层工作流或 Agent 也可能显示异常。因此，红色 Span 不一定都是根因。

建议按以下顺序排查：

1. 在列表中将状态筛选为 异常；
2. 打开目标 Trace；
3. 在 Span 树中找到异常分支；
4. 沿父子关系找到最具体、且包含有效错误信息的 Span；
5. 查看该 Span 的错误、输入和元数据；
6. 判断上层异常是根因还是错误传播结果。

6.2 知识检索失败示例

下图中的 Trace 只有一个“检索”Span，错误为“模型配置请求失败”，Token 为 0。

这表示请求在检索依赖的模型配置阶段已经失败，没有进入后续正常检索过程，也没有产生模型 Token。此时应检查知识库依赖的模型配置，而不是先调整用户问题或检索阈值。

6.3 根据错误类型返回配置位置

Trace 中发现的问题	优先检查
模型配置或模型调用失败	模型管理、应用或工作流中的模型配置
知识检索失败或无结果	知识库、Embedding/Rerank 模型、检索配置
工具调用参数错误	工具配置及上游变量映射
接口调用失败	接口资源的地址、鉴权、参数和调试结果
工作流条件走错	选择器条件及参与判断的变量
代码执行失败	代码节点输入、返回结构和错误信息
Agent 重复调用工具	提示词、工具描述、最大步数和编排逻辑

七、排查结果不正确

“状态正常”只表示执行完成，不代表业务结果一定正确。结果不符合预期时，应找出数据从哪一步开始偏离。

建议沿执行方向依次核对：

1. Root Span 的输入是否与用户实际输入一致；
2. 工作流变量是否正确传入；
3. 条件分支是否符合预期；
4. 知识检索是否返回了相关内容；
5. 工具或接口是否收到正确参数；
6. 模型调用的输入中是否包含所需上下文；
7. 最终输出是否正确引用上游结果。

如果某个 Span 的输入已经错误，继续向上游查找；如果输入正确但输出错误，则重点检查当前 Span 的配置。

八、排查响应缓慢

打开目标 Trace 后，先看顶部总耗时，再沿 Span 树寻找耗时集中的具体调用。

8.1 不要把父子耗时相加

父 Span 的耗时通常包含子 Span。截图中的工作流、图执行和模型调用都显示约 5.27 秒，这不代表三段调用合计约 15.81 秒，而是同一段执行在不同层级的记录。

正确方法是：

1. 从 Root Span 开始找到耗时最长的子分支；
2. 继续展开，直到找到最具体的模型、检索、工具或代码调用；
3. 结合输入数据量和调用配置判断原因。

8.2 常见耗时来源

耗时集中位置	常见原因
模型调用	模型响应慢、输入上下文过长、输出较长
知识检索	文档量大、向量化或重排模型较慢
工具/接口	外部服务响应慢、网络异常、重试
循环或 Agent	调用次数过多、停止条件不清晰
代码节点	处理数据量大或代码逻辑耗时

九、排查 Token 消耗过高

Trace 顶部和 Root Span 展示整次执行的汇总 Token；具体模型调用 Span 展示该调用的 Token。

9.1 不要重复累计

上层 Span 可能汇总下层模型调用的 Token。不要把父 Span 和子 Span 的 Token 全部相加，否则会重复计算。

• 查看整次执行用量：以 Trace 顶部或 Root Span 为准；
• 分析具体模型调用：选择“模型调用”Span，查看其输入、输出和 Token。

9.2 常见原因

• 系统提示词或上下文过长；
• 知识库一次返回的内容过多；
• 对话历史保留过长；
• 模型输出过长；
• Agent 重复调用模型或工具；
• 循环次数超出预期；
• 同一问题被重复处理。

分析时同时观察输入 Token、输出 Token 和模型调用次数，避免只根据总 Token 判断。

十、修复后验证

定位问题后，不要只修改配置就结束。建议完成以下闭环：

1. 记录原 Trace ID、输入、错误、耗时和 Token；
2. 返回对应模块修改配置；
3. 使用相同或等价输入重新执行；
4. 打开新 Trace；
5. 对比出错 Span、最终输出、整体耗时和 Token；
6. 确认问题已经解决且没有引入新的异常。

一次结果正常只能证明当前测试通过。涉及正式业务时，还应结合统计分析观察一段时间内的错误和性能变化。

十一、历史 Trace 与删除行为

Trace 是已经产生的历史观测记录。删除原应用或工作流后，已有 Trace 不会随之消失，仍可在链路列表中查看服务名称、执行时间、状态和详情。

删除业务对象不等于删除其中已经记录的输入输出。清理应用或工作流前，仍需按照数据管理要求处理历史观测数据。

十二、数据安全与权限

Trace 的运行数据可能包含：

• 用户输入和模型输出；
• 提示词和工作流变量；
• 知识库召回内容；
• 工具或接口参数；
• 用户、会话、应用和工作空间标识；
• 医疗业务数据或患者敏感信息。

查看链路追踪及其操作权限由管理员在「角色管理」中分配。使用时应遵守以下要求：

• 仅向排障所需人员提供访问权限；
• 分享截图或复制运行数据前先检查并脱敏；
• 不在公开文档、外部工单或无权限群组中粘贴完整运行数据；
• 不传播 API Key、Token、请求头或其他凭证；
• 排障时只使用解决问题所需的最少数据；
• 删除应用或工作流后，不要假设其历史 Trace 已被删除。