用途
该技能用于分析单条 MLflow trace，以回答用户关于该 trace 的查询。当用户提供 trace ID 并要求调试、调查、查找问题、根因分析时使用。
主要能力
- 读取并解析 MLflow trace 的完整结构，包括
info（元数据、评估）和data（span 树）。 - 识别 trace 状态、span 数量、错误 span、评估错误等健康信号。
- 分析 span 的输入、输出、状态、时序，定位执行偏离预期行为的位置。
- 解读评估（assessments）的反馈值、错误和 rationale，判断质量问题。
- 结合代码库进行根因分析：span 名称映射到函数，span 树镜像调用栈，span 输入输出对应函数参数与返回值。
使用方式
- 获取完整 trace 到文件（
mlflow traces get始终输出 JSON，无需--output标志）：
mlflow traces get --trace-id <ID> > /tmp/trace.json
- 处理文件，例如：
jq '.info.state' /tmp/trace.json
jq '.data.spans | length' /tmp/trace.json
建议获取完整 trace 并直接解析 JSON，而非使用 --extract-fields，因为该标志对嵌套 span 数据支持有限（如 span 输入/输出可能返回空对象）。
- 运行快速健康检查：
jq '{
state: .info.state,
span_count: (.data.spans | length),
error_spans: [.data.spans[] | select(.status.code == "STATUS_CODE_ERROR") | .name],
assessment_errors: [.info.assessments[] | select(.feedback.error) | .assessment_name]
}' /tmp/trace.json
- 若路径不匹配（结构可能因 MLflow 版本而异），可发现结构：
jq 'keys' /tmp/trace.json
jq '.data.spans[0] | keys' /tmp/trace.json
jq '.data.spans[0].status' /tmp/trace.json
关键 JSON 路径
| 内容 | jq 路径 |
|---|---|
| Trace 状态 | .info.state |
| 所有 span | .data.spans |
| 根 span | .data.spans[] | select(.parent_span_id == null) |
| Span 状态码 | .data.spans[].status.code（值：STATUS_CODE_OK、STATUS_CODE_ERROR、STATUS_CODE_UNSET） |
| Span 状态消息 | .data.spans[].status.message |
| Span 输入 | .data.spans[].attributes["mlflow.spanInputs"] |
| Span 输出 | .data.spans[].attributes["mlflow.spanOutputs"] |
| 评估 | .info.assessments |
| 评估名称 | .info.assessments[].assessment_name |
| 反馈值 | .info.assessments[].feedback.value |
| 反馈错误 | .info.assessments[].feedback.error |
| 评估 rationale | .info.assessments[].rationale |
注意：span 输入和输出以序列化 JSON 字符串存储在 attributes 中，而非顶层 span 字段。第三方 OpenTelemetry 客户端的 trace 可能使用不同属性名（如 GenAI Semantic Conventions、OpenInference 或自定义键），需检查原始 attributes 字典。
分析要点
state: OK不代表输出正确，仅表示无未处理异常。需检查评估中的质量信号；若无评估，则直接分析 trace 的输入、输出和中间 span 数据。- 解读评估值时务必参考 rationale。仅看值可能产生误导，例如
user_frustration评估值为"no"可能表示“未检测到挫败感”或“挫败感检查未通过”（即存在挫败感），取决于评分器配置。.rationale字段（顶层评估字段，非嵌套在.feedback下）解释值的上下文含义。 - 评估告诉你出了什么问题，span 告诉你问题在哪里。若有评估，用反馈/期望形成假设，再在 span 树中确认；若无评估，检查 span 输入/输出以识别执行偏离预期行为的位置。
- 评估错误不是 trace 错误。若评估有 error 字段，表示评估该 trace 的评分器或评判器失败，而非 trace 本身有问题。trace 可能完全正常，只是评估值不可靠。
- Span 时序揭示性能问题。父子 span 之间的间隙表示开销；重复的 span 名称表示重试；比较单个 span 持续时间以找出瓶颈。
- Token 使用量解释延迟和成本。在 trace 元数据（如
mlflow.trace.tokenUsage）或 span 属性（如mlflow.chat.tokenUsage）中查找。并非所有客户端都设置这些字段。输入 token 激增可能表示提示注入或上下文过大。
代码库关联
- Span 名称映射到函数。通常匹配用
@mlflow.trace装饰或用mlflow.start_span()包装的函数。自动记录的 span（LangChain、OpenAI 等）遵循框架约定（如ChatOpenAI、RetrievalQA）。 - Span 树镜像调用栈。若 span A 是 span B 的父级，则函数 A 调用了函数 B。
- Span 输入/输出对应函数参数/返回值。与代码逻辑比较可揭示函数是否按设计运行。
- Trace 显示发生了什么，代码显示为什么。检索器返回不相关结果可能追溯到错误的相似度阈值；不正确的 span 输入可能揭示错误的模型参数或代码中缺失的环境变量。
适用场景
- 用户提供 trace ID 并要求调试、调查、查找问题、根因分析。
- 需要定位 AI/ML 应用执行中的错误、性能瓶颈或质量问题。
- 需要结合代码库进行精确根因分析。
限制
- 分析依赖 trace 数据的完整性和结构，不同 MLflow 版本或第三方 OpenTelemetry 客户端的属性名可能不同。
- 评估错误仅表示评分器失败，不代表 trace 本身有问题。
- 并非所有客户端都设置 token 使用量字段。
- 复杂 agent 执行的 trace 可能超过 100KB，需重定向输出到文件，避免直接管道到
jq、head等命令，否则可能静默无输出。