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 の下限が必要です。上限が分かっている場合は追加してください。
• エクスペリメント／実行／セッションの検索にも時間範囲が必要です。結果数を少なくしても、テーブルスキャンの範囲は限定されません。
• ユーザーが指定した過去の時間範囲、またはインシデント／実行のタイムスタンプを使用し、直近 1 時間に暗黙的に置き換えないでください。期間が不明な場合は、広範な 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.name = 'lookup'、span.type = 'RETRIEVER'
評価	feedback.rating = 'positive'、expectation.<name> = <value>
テキスト	trace.text LIKE '%error%'

フィールド名に特殊文字が含まれる場合は、バッククォートで囲みます。シェルコマンドでは、上記のように式全体をシングルクォートで囲むか、コマンド置換を防ぐため、ダブルクォート内のバッククォートをエスケープしてください。フィルター値は個別にエスケープし、信頼できない値をシェル構文として展開しないでください。LIKE、ILIKE、RLIKE は、許可されている場合にパターンマッチングをサポートします。正確なフィールド／演算子のサポートについては、検索ドキュメントを参照してください。

詳細が必要な場合は --include-spans を使用してください。それ以外の場合は、検索後に選択した ID を取得します。--extract-fields を使うと、実際のスキーマを確認したうえで検索結果を絞り込めますが、ネストされたスパンの入力／出力が省略されることがあります。診断には完全なトレースを使用してください。返された継続トークンは、フィルターと順序を固定したまま --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 を 1 つ取得するか、実行時間に上限を設けて max_results=1 の検索を 1 回だけ行ってください。想定されるスパンと実際の入力／出力を確認してください。元の時間枠内に、具体的で簡単な修正を行った後の再試行は最大 1 回までです。認証／プロバイダーキー／権限／ウェアハウスに関する阻害要因があれば停止し、失敗した操作と必要な前提条件を報告してください。並列検索、エージェントの反復実行、直接 SQL、未加工の REST、別の認証方式へのフォールバックは禁止です。このセットアップ上の制限は、専用の検索／調査リクエストの範囲に取って代わるものではありません。

参考資料

• 追加の検索構文／API オプションについては、公式の検索ガイドを参照し、インストール済みのヘルプ／シグネチャと照合してください。ページが移動した場合に限り llms.txt を使用してください。利用できない場合は、インストール済みのヘルプを使用し、正確性が未解決のままなら停止してください。
• 分析がリクエストされた場合は mlflow-trace-analysis を使用してください。検索のみの場合は、リクエストされた根拠を提示した時点で終了してください。