retrieving-mlflow-traces

检索 MLflow 跟踪记录

按时间限制 Unity Catalog 搜索范围

搜索存储在 Unity Catalog 中的跟踪记录时，请在筛选字符串中加入 trace.timestamp_ms >= <start_time_ms>，并在已知时加入上限。按实验 ID、运行 ID、会话或其他条件搜索时也适用：较小的结果数量限制无法避免扫描完整的跟踪记录历史。在 Python 中，通过 filter_string 传递时间条件；mlflow.search_traces() 没有 start_time 参数。

使用用户要求的时间范围，或由运行或事件确定的时间范围。验证设置时，在执行带插桩的运行前立即记录时间。不要擅自将历史调查限制为最近一小时。如果无法确定相关时段，请在开始大范围 UC 搜索前询问。以下示例展示了单个筛选条件；在 UC 搜索中，请结合相关时间范围使用。

简要验证设置

验证新添加的插桩时，请遵循 instrumenting-with-mlflow-tracing 中的验证工作流。读取结果的墙钟时间限制为 60 秒；即使调用仍在内部重试，也要在到时后取消验证命令：通过已知跟踪 ID 获取一次，或执行一次有时间范围限制的搜索，并使用 --max-results 1（Python：max_results=1）。仅在找到明确且可快速修复的问题后重试一次，并且仍须在同一时间预算内完成。确认一条跟踪记录及其预期跨度后即停止。

如果读取结果缓慢或失败，请说明已验证的内容、尚未验证的内容、观察到的阻碍，以及用户需要采取的操作（例如配置缺失的 API 密钥、登录、获取权限，或解决数据仓库的可用性／容量问题）。不要仅为了完成设置验证而启动并行搜索，或改用直接 SQL、原始 REST、其他身份验证方式或反复运行 Agent。专门的检索或调试请求可能需要更广泛的调查；请保留用户要求的范围。

单次获取与搜索

根据已有信息选择合适的方法：

你有……	使用	命令
跟踪 ID	单次获取	mlflow traces get --trace-id <id>
会话／用户／筛选条件	搜索	mlflow traces search --experiment-id <id> --filter-string "..."

单次获取——当你有具体的跟踪 ID 时使用（例如来自 UI、日志或 API 响应）：

mlflow traces get --trace-id tr-69f72a3772570019f2f91b75b8b5ded9

搜索——当你需要根据条件查找跟踪记录时使用（会话、用户、状态、时间范围等）：

mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc'"

---

跟踪数据结构

• TraceInfo：trace_id、status（OK/ERROR）、timestamp_ms、execution_time_ms、tags、metadata、assessments（人工反馈、评估结果）
• Spans：操作树，包含 name、type、attributes、start_time、end_time

工作流

1. 检查 CLI 用法（必需）：mlflow traces search --help
2. 使用下方语法构建筛选查询
3. 使用适当的标志执行搜索
4. 如有需要，获取特定跟踪记录的详细信息

前提条件：检查 CLI 用法

mlflow traces search --help

始终先运行此命令，以获取与已安装 MLflow 版本相符的标志。

搜索跟踪记录

mlflow traces search 命令用于搜索 MLflow 实验中的跟踪记录。

按运行 ID 搜索

筛选与特定 MLflow 运行相关的跟踪记录：

# All traces for a run
mlflow traces search --run-id <run_id>

# Failed traces for a run
mlflow traces search --run-id <run_id> --filter-string "trace.status = 'ERROR'"

# Can combine with experiment-id
mlflow traces search --experiment-id 1 --run-id <run_id>

按会话或用户搜索（常用于调试）

在 MLflow UI 中调试问题时，按会话或用户 ID 筛选，以获取所有相关跟踪记录：

# All traces for a specific session (use backticks for special characters in key)
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123'"

# All traces for a specific user
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.user\` = 'user_456'"

# Failed traces in a session (for root cause analysis)
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123' AND trace.status = 'ERROR'"

# Session traces ordered by time (to see sequence of events)
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123'" --order-by "timestamp_ms ASC"

按状态搜索

mlflow traces search --experiment-id 1 --filter-string "trace.status = 'ERROR'"
mlflow traces search --experiment-id 1 --filter-string "trace.status = 'OK'"

按时间范围搜索

# Timestamps are in milliseconds since epoch
# Get current time in ms: $(date +%s)000
# Last hour: $(( $(date +%s)000 - 3600000 ))

mlflow traces search --experiment-id 1 --filter-string "trace.timestamp_ms > $(( $(date +%s)000 - 3600000 ))"

按执行时间搜索（慢速跟踪记录）

# Traces slower than 1 second
mlflow traces search --experiment-id 1 --filter-string "trace.execution_time_ms > 1000"

按标签和元数据搜索

# By tag
mlflow traces search --experiment-id 1 --filter-string "tag.environment = 'production'"

# By metadata
mlflow traces search --experiment-id 1 --filter-string "metadata.user_id = 'user_123'"

# Escape special characters in key names with backticks
mlflow traces search --experiment-id 1 --filter-string "tag.\`model-name\` = 'gpt-4'"
mlflow traces search --experiment-id 1 --filter-string "metadata.\`user.id\` = 'abc'"

按评估／反馈搜索

mlflow traces search --experiment-id 1 --filter-string "feedback.rating = 'positive'"

全文搜索

mlflow traces search --experiment-id 1 --filter-string "trace.text LIKE '%error%'"

分页

控制结果数量并逐页迭代：

# Limit results per page
mlflow traces search --experiment-id 1 --max-results 50

# Output includes "Next page token: <token>" if more results exist
# Use --page-token to fetch next page
mlflow traces search --experiment-id 1 --max-results 50 --page-token "eyJvZmZzZXQiOiA1MH0="

输出选项

# Output format (table or json)
mlflow traces search --experiment-id 1 --output json

# Include span details in output
mlflow traces search --experiment-id 1 --include-spans

# Order results
mlflow traces search --experiment-id 1 --order-by "timestamp_ms DESC"

检索单条跟踪记录

需要获取特定跟踪记录的详细信息时，请使用 mlflow traces get 命令。

mlflow traces get --trace-id <trace_id>

筛选语法

如需了解详细语法，请从文档中获取：

WebFetch(
  url: "https://mlflow.org/docs/latest/genai/tracing/search-traces.md",
  prompt: "Extract the filter syntax table showing supported fields, operators, and examples."
)

常用筛选条件：

• trace.status：OK、ERROR、IN_PROGRESS
• trace.execution_time_ms、trace.timestamp_ms：数值比较
• metadata.\mlflow.trace.session`、metadata.`mlflow.trace.user``：按会话／用户筛选
• tag.<key>、metadata.<key>：精确匹配或模式匹配
• span.name、span.type：精确匹配或模式匹配
• feedback.<name>、expectation.<name>：评估

模式运算符： LIKE、ILIKE（不区分大小写）、RLIKE（正则表达式）

Python API

关于 mlflow.search_traces()，请参阅：https://mlflow.org/docs/latest/genai/tracing/search-traces.md