retrieving-mlflow-traces

MLflow トレースの取得

Unity Catalog の検索を時間で絞り込む

Unity Catalog に保存されたトレースを検索するときは、フィルター文字列に trace.timestamp_ms >= <start_time_ms> を含め、上限がわかっている場合は上限も指定してください。実験 ID、run ID、セッションなど、ほかのフィルターで検索する場合も同様です。結果の上限を小さくしても、トレースの全履歴にわたるスキャンは防げません。Python では、時間条件を filter_string で渡してください。mlflow.search_traces() に start_time 引数はありません。

ユーザーが指定した時間範囲、または実行やインシデントによって特定された時間範囲を使用してください。セットアップの確認では、計測対象の実行を開始する直前の時刻を記録してください。過去の調査対象を、黙って直近 1 時間に限定しないでください。該当する期間を特定できない場合は、広範な UC 検索を開始する前に期間を確認してください。以下の例では個別のフィルターを示しています。UC では、該当する時間範囲と組み合わせてください。

セットアップの確認は簡潔に行う

新たに追加した計測を確認するには、instrumenting-with-mlflow-tracing の確認ワークフローに従ってください。読み戻しには 60 秒の実時間制限を設け、呼び出しが内部で再試行中であっても、期限に達したら確認コマンドをキャンセルしてください。既知のトレース ID を使って 1 回取得するか、時間範囲を指定した検索を --max-results 1（Python では max_results=1）で 1 回実行します。具体的ですぐにできる修正を加えた場合に限り、同じ時間制限内で最大 1 回まで再試行してください。トレース 1 件と想定されるスパンが確認できた時点で終了してください。

読み戻しに時間がかかる、または失敗した場合は、確認できた内容、未確認の内容、観測された阻害要因、および必要なユーザー側の対応（不足している API キーの設定、ログイン、権限の取得、ウェアハウスの可用性や容量の問題の解決など）を報告してください。セットアップの確認を完了するためだけに、並列検索を開始したり、直接 SQL、raw REST、別の認証方式、エージェントの繰り返し実行に切り替えたりしないでください。専用の取得またはデバッグの依頼では、より広範な調査が必要になる場合があります。ユーザーが指定した範囲を守ってください。

単一取得と検索の使い分け

手元にある情報に応じて、適切な方法を選択してください。

手元にあるもの	使用方法	コマンド
トレース 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（人によるフィードバック、評価結果）
• スパン：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 の実験内でトレースを検索します。

Run ID で検索

特定の 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>

セッションまたはユーザーで検索（デバッグでよく使用）

MLflow UI で問題をデバッグするときは、セッション ID またはユーザー 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