retrieving-mlflow-traces

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Retrieving MLflow Traces

检索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):

bash

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

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

bash

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

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

你拥有...	使用方法	命令
Trace ID	单次获取	`mlflow traces get --trace-id <id>`
会话/用户/筛选条件	搜索	`mlflow traces search --experiment-id <id> --filter-string "..."`

单次获取 - 当你有特定的Trace ID时使用（例如来自UI、日志或API响应）：

bash

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

搜索 - 当你需要通过条件（会话、用户、状态、时间范围等）查找Trace时使用：

bash

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

Trace Data Structure

Trace数据结构

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
```
,
```
end_time
```

TraceInfo：
```
trace_id
```
、
```
status
```
（OK/ERROR）、
```
timestamp_ms
```
、
```
execution_time_ms
```
、
```
tags
```
、
```
metadata
```
、
```
assessments
```
（人工反馈、评估结果）
Spans：操作树，包含
```
name
```
、
```
type
```
、
```
attributes
```
、
```
start_time
```
、
```
end_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

检查CLI用法（必填）：
```
mlflow traces search --help
```
使用以下语法构建筛选查询
使用适当的标志执行搜索
如有需要，检索特定Trace的详细信息

Prerequisite: Check CLI Usage

前提条件：检查CLI用法

bash

mlflow traces search --help

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

bash

mlflow traces search --help

请始终先运行此命令，以获取与已安装MLflow版本匹配的准确标志。

Searching Traces

搜索Traces

The

mlflow traces search

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

mlflow traces search

命令用于在MLflow实验中搜索Traces。

By Run ID

按Run ID筛选

Filter traces associated with a specific MLflow run:

bash

undefined

筛选与特定MLflow run关联的Traces：

bash

undefined

All traces for a run

某个run的所有Traces

mlflow traces search --run-id <run_id>

Failed traces for a run

某个run中失败的Traces

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

Can combine with experiment-id

可与experiment-id结合使用

mlflow traces search --experiment-id 1 --run-id <run_id>

undefined

mlflow traces search --experiment-id 1 --run-id <run_id>

undefined

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:

bash

undefined

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

bash

undefined

All traces for a specific session (use backticks for special characters in key)

特定会话的所有Traces（键名含特殊字符时使用反引号）

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

All traces for a specific user

特定用户的所有Traces

mlflow traces search --experiment-id 1 --filter-string "metadata.`mlflow.trace.user` = 'user_456'"

Failed traces in a session (for root cause analysis)

会话中失败的Traces（用于根本原因分析）

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)

按时间排序的会话Traces（查看事件序列）

mlflow traces search --experiment-id 1 --filter-string "metadata.`mlflow.trace.session` = 'session_abc123'" --order-by "timestamp_ms ASC"

undefined

mlflow traces search --experiment-id 1 --filter-string "metadata.`mlflow.trace.session` = 'session_abc123'" --order-by "timestamp_ms ASC"

undefined

By Status

按状态筛选

bash

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

bash

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

按时间范围筛选

bash

undefined

bash

undefined

Timestamps are in milliseconds since epoch

时间戳为自纪元以来的毫秒数

Get current time in ms: $(date +%s)000

获取当前时间（毫秒）：$(date +%s)000

Last hour: $(( $(date +%s)000 - 3600000 ))

过去一小时：$(( $(date +%s)000 - 3600000 ))

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

undefined

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

undefined

By Execution Time (Slow Traces)

按执行时间筛选（慢Traces）

bash

undefined

bash

undefined

Traces slower than 1 second

执行时间超过1秒的Traces

mlflow traces search --experiment-id 1 --filter-string "trace.execution_time_ms > 1000"

undefined

mlflow traces search --experiment-id 1 --filter-string "trace.execution_time_ms > 1000"

undefined

By Tags and Metadata

按标签和元数据筛选

bash

undefined

bash

undefined

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

undefined

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

undefined

By Assessment/Feedback

按评估/反馈筛选

bash

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

bash

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

Full Text Search

全文搜索

bash

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

bash

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

Pagination

分页

Control result count and iterate through pages:

bash

undefined

控制结果数量并遍历分页：

bash

undefined

Limit results per page

限制每页结果数

mlflow traces search --experiment-id 1 --max-results 50

Output includes "Next page token: <token>" if more results exist

如果还有更多结果，输出会包含“Next page token: <token>”

Use --page-token to fetch next page

使用--page-token获取下一页

mlflow traces search --experiment-id 1 --max-results 50 --page-token "eyJvZmZzZXQiOiA1MH0="

undefined

mlflow traces search --experiment-id 1 --max-results 50 --page-token "eyJvZmZzZXQiOiA1MH0="

undefined

Output Options

输出选项

bash

undefined

bash

undefined

Output format (table or json)

输出格式（表格或json）

mlflow traces search --experiment-id 1 --output json

Include span details in output

在输出中包含Span详情

mlflow traces search --experiment-id 1 --include-spans

Order results

结果排序

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

undefined

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

undefined

Retrieving Single Trace

检索单个Trace

When you need to retrieve details about a specific trace, use the

mlflow traces get

command.

bash

mlflow traces get --trace-id <trace_id>

当你需要获取特定Trace的详细信息时，使用

mlflow traces get

命令。

bash

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>
```
,
```
expectation.<name>
```
: assessments

Pattern operators:

LIKE

ILIKE

(case-insensitive),

RLIKE

(regex)

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

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

For

mlflow.search_traces()

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

关于

mlflow.search_traces()

，请查看：https://mlflow.org/docs/latest/genai/tracing/search-traces.md