mlflow-trace-analysis

分析 MLflow 跟踪记录

使用跟踪记录 ID 或会话 ID、已配置的后端、报告的问题行为和预期结果。复用已获取的跟踪记录。对于多轮对话，请阅读会话分析。

前提条件

搜索未知跟踪记录 ID 前，请阅读跟踪记录检索，了解筛选条件、时间范围和分页。复用已获取的跟踪记录。如果未安装该技能，请使用搜索指南和已安装 CLI 的帮助信息。

优先使用现有证据。只有在没有可用跟踪记录时，才在安全的前提下通过常规的埋点入口复现一次；否则报告缺失的证据。仅在获得授权且 HUMAN 反馈关联到已识别的跟踪记录时，才记录该反馈。

步骤 1：获取跟踪记录

将完整 JSON 获取一次并保存到文件；通过 CLI 管道输出大量内容时，执行工具可能会截断输出。get 无需 --output 标志。诊断嵌套 span 时，避免使用 --extract-fields。

mlflow traces get --trace-id <TRACE_ID> > /tmp/trace.json

步骤 2：检查 span 树

总结状态、评估结果和父级链接：

jq '{state: .info.state,
     spans: [.data.spans[] | {span_id, parent_span_id, name, status}],
     error_spans: [.data.spans[] | select(.status.code == "STATUS_CODE_ERROR") | .name],
     assessments: .info.assessments}' /tmp/trace.json

步骤 3：读取反馈

形成假设前，先读取反馈的来源、值、顶层理由、有效性和范围。HUMAN 反馈描述的是报告的问题体验；请结合 span 进行佐证。LLM_JUDGE/CODE 反馈可能有误或配置不当。feedback.error 表示评分失败，而非应用程序失败；进行质量判断时，应排除报错或被覆盖的评判。真实的零值/false 值仍然有效。预期是期望输出的标签，而不是分数。

步骤 4：跟进输入和输出

从根节点开始，沿实际输入和输出追踪至第一个偏差，再检查下游影响。原始 MLflow span 的 I/O 通常是序列化 JSON，位于 attributes["mlflow.spanInputs"] / attributes["mlflow.spanOutputs"]；解读前请先解析。如果根节点是空包装器，请检查其后代。对于其他 OTel 来源或版本，请检查原始键，不要想当然地套用此架构。

步骤 5：检查错误和性能

检查异常事件和状态消息。OK 表示执行成功，不代表输出正确；STATUS_CODE_UNSET 本身并非错误。分析性能时，请区分外层包装器、重叠的子任务和未埋点的间隙；名称重复本身不能证明发生了重试。检查记录的 token 用量，不要臆测成本，也不要假设 token 激增就能证明发生了注入。

步骤 6：检查源代码

在相关源代码/配置可用时，将决定性 span 中观察到的数据与之关联。函数名称只是线索；自动记录的名称遵循框架约定。区分观察到的事实、可能的原因和缺失的证据。不要仅为诊断而修改代码、创建评分器或运行评估。

如需查看检索未命中、答案缺乏依据以及后续传播的示例，请参阅退款政策证据表。

验证

报告观察到的行为与预期行为、跟踪记录和决定性 span 的 ID、证据链、置信度以及最小可行的补救措施。应依据实际 span I/O 和反馈语义确认结论，而非仅凭预览。如果证据缺失，请说明需要哪些信息才能消除不确定性；不要将假设说成已确认的根本原因。

参考资料

• 字段、单位、CLI 与 SDK 表示形式、OTel 属性或评估结果的解读：跟踪记录结构。
• 有界批次、反复出现的故障或组件瓶颈：跨跟踪记录分析。
• 多轮传播：会话分析。
• 用户请求的实现：如果已安装 mlflow-agent-improvement，请将诊断结论和跟踪记录 ID 传给它；调查本身应止于证据和建议。