MLflow追踪检索指南：单次获取与搜索命令详解

retrieving-mlflow-traces by mlflow/skills

82 周安装量

18 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mlflow/skills --skill retrieving-mlflow-traces

AI/机器学习开发运维监控

🇨🇳中文介绍

检索 MLflow 追踪

单次获取与搜索

根据您掌握的信息选择合适的方法：

您拥有...	使用	命令
追踪 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'"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

先决条件：检查 CLI 用法

mlflow traces search --help

始终首先运行此命令，以获取已安装 MLflow 版本的准确标志信息。

mlflow traces search 命令用于在 MLflow 实验中搜索追踪。

过滤与特定 MLflow 运行关联的追踪：

# 某个运行的所有追踪
mlflow traces search --run-id <run_id>

# 某个运行中失败的追踪
mlflow traces search --run-id <run_id> --filter-string "trace.status = 'ERROR'"

# 可以与 experiment-id 结合使用
mlflow traces search --experiment-id 1 --run-id <run_id>

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

从 MLflow UI 调试问题时，按会话或用户 ID 过滤以获取所有相关追踪：

# 特定会话的所有追踪（键名包含特殊字符时使用反引号）
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123'"

# 特定用户的所有追踪
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.user\` = 'user_456'"

# 某个会话中失败的追踪（用于根本原因分析）
mlflow traces search --experiment-id 1 --filter-string "metadata.\`mlflow.trace.session\` = 'session_abc123' AND trace.status = 'ERROR'"

# 按时间排序的会话追踪（查看事件序列）
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'"

# 时间戳是自纪元以来的毫秒数
# 获取当前时间（毫秒）：$(date +%s)000
# 过去一小时：$(( $(date +%s)000 - 3600000 ))

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

按执行时间（慢追踪）

# 执行时间超过 1 秒的追踪
mlflow traces search --experiment-id 1 --filter-string "trace.execution_time_ms > 1000"

按标签和元数据

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

# 按元数据
mlflow traces search --experiment-id 1 --filter-string "metadata.user_id = 'user_123'"

# 键名包含特殊字符时用反引号转义
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%'"

控制每页结果数量并遍历页面：

# 限制每页结果数
mlflow traces search --experiment-id 1 --max-results 50

# 如果还有更多结果，输出会包含 "Next page token: <token>"
# 使用 --page-token 获取下一页
mlflow traces search --experiment-id 1 --max-results 50 --page-token "eyJvZmZzZXQiOiA1MH0="

# 输出格式（table 或 json）
mlflow traces search --experiment-id 1 --output json

# 输出中包含 span 详细信息
mlflow traces search --experiment-id 1 --include-spans

# 对结果排序
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（正则表达式）

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

🇺🇸English

Retrieving MLflow Traces

Single Fetch vs Search

Choose the right approach based on what you have:

You have...	Use	Command
Trace ID	Single fetch	`mlflow traces get --trace-id <id>`
Session/user/filters	Search	`mlflow traces search --experiment-id <id> --filter-string "..."`

Single fetch - Use when you have a specific trace ID (e.g., from UI, logs, or API response):

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

Search - Use when you need to find traces by criteria (session, user, status, time range, etc.):

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

Trace Data Structure

TraceInfo : trace_id, status (OK/ERROR), timestamp_ms, execution_time_ms, tags, metadata, assessments (human feedback, evaluation results)
Spans : Tree of operations with name, type, attributes, start_time,

Workflow

Check CLI usage (required): mlflow traces search --help
Build filter query using syntax below
Execute search with appropriate flags
Retrieve details for specific traces if needed

Prerequisite: Check CLI Usage

mlflow traces search --help

Always run this first to get accurate flags for the installed MLflow version.

Searching Traces

The mlflow traces search command is used to search for traces in an MLflow experiment.

By Run ID

Filter traces associated with a specific MLflow run:

# 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>

By Session or User (Common for Debugging)

When debugging an issue from the MLflow UI, filter by session or user ID to get all related traces:

# 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"

By Status

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

By Time Range

# 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 ))"

By Execution Time (Slow Traces)

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

By Tags and Metadata

# 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'"

By Assessment/Feedback

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

Full Text Search

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

Pagination

Control result count and iterate through pages:

# 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 Options

# 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"

Retrieving Single Trace

When you need to retrieve details about a specific trace, use the mlflow traces get command.

mlflow traces get --trace-id <trace_id>

Filter Syntax

For detailed syntax, fetch from documentation:

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

Common filters:

trace.status: OK, ERROR, IN_PROGRESS
trace.execution_time_ms, trace.timestamp_ms: numeric comparison
metadata.\mlflow.trace.session, `metadata.`mlflow.trace.user: session/user filtering
tag.<key>, metadata.<key>: exact match or pattern
span.name, span.type: exact match or pattern
feedback.<name>, : assessments

Pattern operators: LIKE, ILIKE (case-insensitive), RLIKE (regex)

Python API

For mlflow.search_traces(), see: https://mlflow.org/docs/latest/genai/tracing/search-traces.md

Weekly Installs

Repository

mlflow/skills

GitHub Stars

First Seen

Feb 5, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli81

github-copilot81

codex80

opencode79

amp78

kimi-cli78

expectation.<name>

MLflow追踪检索指南：单次获取与搜索命令详解

🇨🇳中文介绍

检索 MLflow 追踪

单次获取与搜索

相关 Skills

追踪数据结构

工作流程

先决条件：检查 CLI 用法

搜索追踪

按运行 ID

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

按状态

按时间范围

按执行时间（慢追踪）

按标签和元数据

按评估/反馈

全文搜索

分页

输出选项

检索单个追踪

过滤器语法

Python API

🇺🇸English

Retrieving MLflow Traces

Single Fetch vs Search

Trace Data Structure

Workflow

Prerequisite: Check CLI Usage

Searching Traces

By Run ID

By Session or User (Common for Debugging)

By Status

By Time Range

By Execution Time (Slow Traces)

By Tags and Metadata

By Assessment/Feedback

Full Text Search

Pagination

Output Options

Retrieving Single Trace

Filter Syntax

Python API

最新 Skills