关于 mlflow-trace-retrieval
用于按 ID 获取或按条件搜索 MLflow trace 的 skill，涵盖时间范围、分页、结果验证及大型输出的处理。
主要功能
- 01按 ID 获取 trace
- 02按筛选条件和时间范围搜索
- 03保存完整 JSON 输出
- 04处理分页令牌
- 05验证查询范围与覆盖情况
适用场景
- 01检查已知 ID 的 trace
- 02查找事故时间范围内的 trace
- 03查看状态、延迟、会话或 span 数据
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/mlflow-trace-retrieval确认已加载。
详细介绍
检索 MLflow 跟踪记录
步骤 1：选择检索方式
重用已配置的跟踪 URI、实验、提供的跟踪 ID 或筛选条件，以及事件/运行时间范围。对于所选操作，请通过 mlflow traces get --help 或 mlflow traces search --help 检查已安装 CLI 的标志。
对于 Databricks UC 跟踪记录，请先阅读 Databricks 跟踪设置：检索跟踪记录需要已配置的 SQL 仓库和工作区身份验证。请勿用直接 SQL、原始 REST 或粘贴的令牌代替缺失的仓库访问权限。
步骤 2：获取或搜索
如果有 ID，直接获取。先将完整 JSON 保存到文件，再进行解析，以免大型输出被工具截断。get 已经会输出 JSON；无需使用 --output 标志。
mlflow traces get --trace-id <TRACE_ID> > /tmp/trace.json
如果没有 ID，请搜索所选实验和指定的时间范围：
mlflow traces search --experiment-id <EXPERIMENT_ID> \
--filter-string 'metadata.`mlflow.trace.session` = "<SESSION_ID>" AND trace.timestamp_ms >= <START_MS> AND trace.timestamp_ms <= <END_MS>' \
--order-by 'timestamp_ms ASC' --max-results 50 --output json > /tmp/traces.json
- 执行前请替换占位符。每次 UC 搜索都需要
trace.timestamp_ms下限；已知上限时也要添加。 - 按实验/运行/会话检索时也需要时间范围：较小的结果数量限制无法限制表扫描范围。
- 使用用户指定的历史时间范围或事件/运行时间戳，切勿默默改用最近一小时。若时间段未知，请先询问，再进行范围较大的 UC 搜索。
筛选条件
使用 AND 组合谓词；确认已安装的后端/版本支持相应运算符。
| 选择条件 | 谓词或标志 |
|---|---|
| 运行 | --run-id <RUN_ID>（与时间范围组合使用） |
| 状态 | trace.status = 'ERROR'（也可使用 OK、IN_PROGRESS） |
| 时间/延迟 | trace.timestamp_ms >= 1700000000000、trace.execution_time_ms > 1000（毫秒） |
| 会话/用户 | metadata.`mlflow.trace.session` = 'abc'、metadata.`mlflow.trace.user` = 'user1' |
| 标签/元数据 | tag.environment = 'production'、metadata.`user.id` = 'abc' |
| Span | span.name = 'lookup'、span.type = 'RETRIEVER' |
| 评估结果 | feedback.rating = 'positive'、expectation.<name> = <value> |
| 文本 | trace.text LIKE '%error%' |
字段名中的特殊字符用反引号括起来。在 shell 命令中，将外层表达式放在单引号内，如上所示；或者在双引号内转义反引号，以防止命令替换。请分别转义筛选值；不要将不可信值插入 shell 语法。允许使用模式匹配的情况下，LIKE、ILIKE 和 RLIKE 均支持模式匹配；有关字段/运算符的确切支持情况，请参阅搜索文档。
需要详细信息时使用 --include-spans；否则，请在搜索后获取选定的 ID。检查实际架构后，可以使用 --extract-fields 减少搜索输出，但嵌套的 span 输入/输出可能会被省略：诊断时请使用完整跟踪记录。继续使用固定的筛选条件/排序方式，通过 --page-token 跟进返回的续页令牌；报告有限样本时，应明确标注为样本，而非全部匹配结果。
Python 替代方案
trace = mlflow.get_trace(trace_id)
# Or search when the ID is unknown:
traces = mlflow.search_traces(
locations=[experiment_id],
filter_string=f"trace.timestamp_ms >= {start_ms} AND trace.timestamp_ms <= {end_ms}",
max_results=50, return_type="list", include_spans=True,
)
请检查已安装版本的函数签名；较早版本可能使用 experiment_ids。search_traces() 没有 start_time 关键字参数。请通过 filter_string 设置时间戳谓词。
验证
- 对于设置回读，请在运行前立即记录时间；如有设置验证，请遵循该流程。
确认返回的 ID、实验/位置、时间窗口和筛选条件与请求一致；区分无匹配结果、查询失败和页面结果不完整。返回 ID/输出文件以及任何覆盖范围限制。不要仅凭状态 OK 推断质量。
仅针对新添加的检测：强制执行 60 秒墙钟时间期限，包括刷新/回读/内部重试，并在期限到时终止命令。获取一个已捕获的 ID，或执行一次受运行时间限制且 max_results=1 的搜索。检查预期跨度以及实际输入/输出。只有在原预算内完成快速、明确的修复后，才能最多重试一次。遇到身份验证/提供商密钥/权限/数据仓库阻碍时停止，并报告失败的操作和所需前置条件。不得并行搜索、重复运行 Agent、直接执行 SQL、使用原始 REST 或回退到其他身份验证方式。此设置限制不取代专门检索/调查请求的范围。