归因分析-Agent 观测与优化 AgentLoop(AgentLoop)-阿里云帮助中心

归因分析功能基于 AI Agent Trace 的性能、成本和调用链特征，以二维分布图展示 Trace，并比较异常 Trace 与基线 Trace 的特征差异，帮助您快速识别异常样本集中出现的应用、Agent、模型、工具调用和 Token 消耗特征。

归因分析支持按 Trace 筛选数据，也支持从智能聚类的指定主题发起分析。您可以在分布图中框选需要关注的 Trace，查看异常组与基线组之间差异较大的特征，并继续下钻 Trace 详情或使用智能分析能力获取诊断建议。

说明

归因结果描述的是异常组与基线组之间的特征分布差异，用于提供排查线索，不代表特征与异常之间存在确定的因果关系。

前提条件

已开通云监控 2.0 服务并创建工作空间。
已将 AI Agent 的可观测数据接入当前工作空间。有关 AI Agent 可观测数据接入方式，请参见AI Agent可观测接入总览。
所选时间范围内存在包含 Trace ID、耗时、TTFT、Token 或缓存指标的 Trace 数据。
如需按聚类结果分析，需先创建 Trace 聚类任务，并至少完成一次包含有效主题的运行。
如需使用智能生成分析或深度分析，需具备 STAROps 智能分析能力的使用权限。

操作路径

登录云监控 2.0 控制台，选择目标工作空间，在左侧导航栏选择AI Agent 可观测，进入聚类与归因页面。

您可以通过以下方式使用归因分析：

独立分析：进入归因分析区域，选择按 Trace 搜索或按聚类搜索。
从智能聚类下钻：在 Trace 聚类结果中打开目标主题详情，然后单击归因分析。系统将自动带入当前聚类任务、运行记录、主题和运行时间范围。

分析流程

归因分析的基本流程如下：

选择参与分析的 Trace 范围。
选择性能或成本分析目标。
在二维分布图中观察 Trace 分布，并框选需要排查的区域。
将框选区域中的 Trace 作为对比组，与当前范围内的其他 Trace 进行对比分析。
查看智能分析、Top 归因维度和异常 Trace，继续下钻调用链详情。

选择分析范围

归因分析支持按 Trace 搜索和按聚类搜索两种方式。

按 Trace 搜索

按 Trace 搜索基于当前页面的查询时间范围读取 Trace。您可以使用以下字段缩小分析范围。

筛选字段	说明
AI 应用	按 Trace 经过的应用筛选数据，适用于分析指定应用中的异常请求。
AI Agent	按 Trace 调用的 Agent 筛选数据，适用于聚焦特定 Agent 的执行情况。
技能	按 Trace 调用的 Skill 筛选数据，适用于分析特定 Skill 相关的性能或成本问题。

筛选字段支持搜索、多选、全选和清空。一个 Trace 只要包含选中的值，即可匹配对应条件。配置多个筛选字段时，系统同时应用这些条件；各字段的候选值会根据其他已选条件联动更新。

按聚类搜索

按聚类搜索用于分析某个智能聚类主题内部的 Trace。依次选择以下内容：

参数	说明
任务	选择 Trace 聚类任务。
运行记录	选择任务下包含有效聚类结果的运行记录。
主题	选择当前运行中的一个主题。主题选项同时展示该主题包含的 Trace 数量。
运行时间范围	系统使用所选运行的数据时间范围读取聚类结果，无需单独配置。

从智能聚类主题详情进入归因分析时，任务、运行记录和主题由系统自动固定，避免分析过程中切换上下文导致数据口径变化。

说明

按聚类搜索使用聚类运行的数据时间范围，不使用归因页面或控制台当前选择的全局时间范围。

选择分析目标

页面根据分析类型提供可选的二维指标组合。选择分析类型和维度后，系统会自动更新分布图的横轴、纵轴及指标单位。

不同分析类型适用于不同的排查方向：

性能分析：用于观察响应时延、首 Token 返回、模型输出效率等性能特征。
成本分析：用于观察 Token 使用和缓存利用等资源消耗特征。

可选维度可能随产品能力演进而调整，请以页面实际展示为准。

页面中的查询数量用于控制本次分布分析读取的 Trace 数量。

调大查询数量可以覆盖更多 Trace，但会增加查询和对比分析耗时。数据量较大时，建议先通过时间范围、应用、Agent、Skill 或聚类主题缩小范围，再逐步调大查询数量。

查看 Trace 二维分布

完成范围和维度选择后，页面通过二维散点图展示 Trace 分布：

每个点表示一条 Trace。
横轴和纵轴由当前选择的分析维度决定。
将鼠标悬停在点上，可以查看 Trace ID 和两个维度的指标值。
单击某个点，可以打开 Trace 详情，查看完整调用链、Span 层级和输入输出信息。
在图中拖拽，可以框选需要进一步分析的 Trace。

如果某条 Trace 缺少当前维度所需的指标，或者指标值无效，该 Trace 不会显示在当前分布图中。因此，图中的 Trace 数量可能小于查询数量或聚类主题中的 Trace 总数。

框选异常 Trace

在二维分布图中拖拽框选需要排查的区域。框选完成后，页面展示以下信息：

对比组包含的 Trace 数量。
对比组横轴指标的平均值。
对比组纵轴指标的平均值。
用于复制所选 Trace ID 的入口。
对比分析操作。

框选区域中的 Trace 作为对比组，当前查询范围内未命中框选区域的其他 Trace 作为基线组。单击对比分析后，系统比较两组 Trace 的特征分布，并按差异度生成归因结果。

框选前，请先确认当前横轴和纵轴的名称、单位及指标方向，再根据业务目标选择异常区域。不同指标对异常的判断方向可能不同，不能统一认为数值越大越异常，也不应固定使用某个象限作为异常区域。

说明

框选区域由用户定义。系统不会自动将某个象限认定为异常。框选范围不合理时，对比结果可能无法反映实际问题。

查看归因结果

完成对比分析后，页面展示智能生成分析和 Top 归因维度。按 Trace 搜索时，还会展示异常 Trace 明细。

智能生成分析

系统基于差异度较高的归因条件，生成面向 Agent 研发和运维人员的分析摘要。摘要通常包含：

当前性能或成本异常的主要特征。
对比组中满足特征条件的 Trace 占比。
基线组中满足相同条件的 Trace 占比。
建议优先关注的调用链、Token、模型、工具或用户维度。

智能生成分析用于总结已有归因结果，不会替代原始对比数据。建议结合 Top 归因维度和 Trace 详情验证结论。

Top 归因维度

Top 归因维度按对比组与基线组之间的分布差异度排序。页面优先展示差异较明显的候选维度，存在更多结果时，可以展开查看。

每个归因维度包含以下信息：

字段	说明
特征条件	当前特征、比较操作符和阈值或枚举值，例如“工具名称包含某工具”或“输入 Token 大于某个值”。
差异度	特征条件在对比组和基线组中的覆盖比例差异。差异越大，该条件区分两组样本的能力越强。
对比组样本	对比组中满足条件的 Trace 数量和占比。
基线组样本	基线组中满足相同条件的 Trace 数量和占比。

可能参与归因的特征包括：

特征类别	归因维度示例
调用范围	User ID、经过的应用、经过的 Agent。
模型与工具	使用的模型、使用的工具。
调用复杂度	LLM 轮次数、Agent 调用次数、工具调用次数。
错误情况	LLM 错误次数、工具错误次数。
Token 与上下文	输入 Token、输出 Token、单次 LLM 调用最大输入 Token。
响应耗时	Trace 耗时、LLM 平均响应时间、工具平均响应时间、TTFT。
工具返回	工具平均返回长度、工具最大返回长度。

实际展示的特征取决于分析类型、搜索方式以及 Trace 数据中是否存在对应字段。

说明

差异度不是故障贡献率，也不能直接证明根因。例如，“异常组更常使用某模型”只能说明该模型在异常组中更集中，仍需结合模型参数、上下文和 Trace 详情继续验证。

异常 Trace 明细

使用按 Trace 搜索完成对比分析后，页面展示框选 Trace 的代表性明细，包括：

字段	说明
Trace ID	Trace 的唯一标识。单击可以打开 Trace 详情。
Session ID	Trace 所属的会话标识。
起始时间	Trace 的开始时间。
耗时	Trace 的整体执行耗时。
LLM 轮次数	Trace 中的 LLM 调用次数。
输入 Token 消耗	Trace 中所有 LLM 调用的输入 Token 总量。
输出 Token 消耗	Trace 中所有 LLM 调用的输出 Token 总量。
工具调用次数	Trace 中的工具调用总数。
工具错误次数	Trace 中执行失败的工具调用数量。

明细支持分页和调整每页数量。单击 Trace ID 后，可以结合当前归因时间范围查看完整调用链。

深度分析

归因分析用于发现异常组与基线组之间的特征差异。如果需要在这些线索基础上进一步定位问题根因，建议使用STAROps 深入分析。

单击深度分析后，系统会从当前框选范围中选取 Trace 样本，并将样本及其工作空间、分析时间范围传递给 STAROps。STAROps 会深入分析这些 Trace 的完整调用链和 Agent 运行推理轨迹，结合任务推进过程、Span 层级、LLM 和工具调用顺序、重试与错误信息、耗时以及 Token 使用情况，帮助定位更具体的问题环节和可能原因。

智能生成分析和深度分析由 STAROps 提供并计费。使用前，请参见STAROps billing。

分析建议

首次使用时，建议先选择较小的查询数量，确认分布和指标范围后再逐步扩大查询数量。
对比组和基线组都应包含足够数量的 Trace。样本过少时，个别 Trace 的特征可能被放大。
优先关注差异度高、对比组覆盖率高且基线组覆盖率低的条件。
对枚举特征使用“集中出现”“更常经过”或“更常使用”进行解释，不要直接表述为根因。
对数值特征应保留原始比较符和阈值。例如，小于某个值不应改写为偏高。
修改筛选条件、分析类型、指标维度或聚类主题后，需要重新框选并执行对比分析。
最终判断应结合 Trace 详情、模型配置、工具返回、错误信息和版本变更共同完成。

常见使用场景

慢 Trace 定位：选择与响应时延相关的性能维度，比较 LLM 响应时间、工具响应时间、调用轮次和错误情况。
模型输出性能分析：选择与首 Token 返回或模型输出效率相关的性能维度，分析模型、输入 Token 和 LLM 调用链特征。
Token 成本优化：选择与 Token 使用或缓存利用相关的成本维度，分析上下文规模和模型使用情况。
工具链异常分析：观察异常组是否集中使用某个工具，或者工具调用次数、错误次数、返回长度和平均耗时是否存在明显差异。
Agent 与应用范围定位：判断异常 Trace 是否集中经过某个应用、Agent、模型、工具或用户。
聚类主题内诊断：从智能聚类主题详情发起归因，仅比较同一业务主题中的 Trace，减少不同用户意图对指标的干扰。

常见问题

为什么分布图中的 Trace 数少于查询数量？

查询数量表示读取上限。缺少当前横轴或纵轴指标、指标为空或指标值无效的 Trace 会被过滤，因此实际展示数量可能更少。

为什么没有归因结果？

可能原因包括：

框选区域没有命中有效 Trace。
对比组或基线组样本过少。
两组 Trace 的可用特征差异不明显。
当前 Trace 缺少模型、工具、Token 或耗时等归因字段。
所选时间范围、聚类运行或主题中没有有效数据。

建议调整框选范围、扩大查询数量，或者缩小到更明确的应用、Agent、Skill 或聚类主题后重试。

归因结果是否等同于根因？

不等同。归因结果用于说明异常组与基线组之间哪些特征具有明显分布差异，可以帮助缩小排查范围，但不能直接证明问题根因。

如果需要进一步定位根因，建议框选具有代表性的异常 Trace 后使用STAROps 深入分析。STAROps 会基于框选的 Trace 样本继续分析完整调用链和 Agent 运行推理轨迹，并结合 Trace 详情、任务推进过程、错误信息和运行指标提供更深入的诊断线索。最终结论仍建议结合日志、配置和版本变化进行验证。