mlflow-trace-instrumentation

MLflow トレースを計測する

調査や評価には、動作確認済みのトレースを再利用します。

前提条件

• エントリポイント、言語／フレームワーク、SDK のバージョン、トラッキング URI、実験、デプロイの識別情報を確認します。
• 保存先とプロバイダーは維持します。アプリケーションで明示された保存先は継承した環境変数の値より優先されます。アシスタントのテレメトリーでは、別の実験を使用する場合があります。
• 実行環境に応じて、Python または TypeScript を読みます。

ステップ 1：保存先を確認する（Databricks のみ）

OSS または SageMaker の場合は、設定済みのバックエンドをそのまま使用し、ステップ 2 に進みます。

• 編集する前に UC のセットアップを読み、認証とワークスペースを検証します。
• 明示された保存先を再利用します。明示されていない場合は、プロビジョニングの前にスキーマの選択を決めます。
• アクセス可能なウェアハウスを自動的に検出します。デフォルトでは UC を使用します。レガシーストレージを使用するには、明示的なリクエストが必要です。

ステップ 2：フレームワークのトレースを有効にする

• 実行前に、該当するインテグレーションを有効にします。LangGraph では mlflow.langgraph.autolog() ではなく、mlflow.langchain.autolog() を使用します。
• 自動トレースされるノード、ツール、モデルを再度ラップしないでください。手動スパンは、捕捉されていない処理やアプリケーション全体を囲む境界に限って使用します。

ステップ 3：アプリケーションの処理を捕捉する

• ルート、LLM、検索、ツール、ルーティング、外部 I/O（ファイル／キュー）のうち、重要なものをトレースします。 ユーティリティ、設定、ログ出力などのノイズは省きます。
• 手動スパンでは、実際の関連する入出力を明示的に捕捉し、エクスポート前に機密情報を伏せます。

ステップ 4：リクエストを 1 回実行する

• 代表的なリクエストを 1 回実行し、開始時刻と終了時刻をエポックミリ秒で記録します。
• トレース ID はプロセス内ですぐに保存します。Python では mlflow.get_last_active_trace_id()、TypeScript ではアクティブなスパンの ID を使用します。
• 読み戻す前に、トレース ID をファイルまたは取得した標準出力に書き込み／フラッシュします。プロセスがキャンセルされても ID を保持します。 ID を復旧するために再実行しないでください。

検証

• ローカルスパンや古いトレースではなく、永続化されたアプリケーショントレースを取得します。

• フラッシュ、SDK の再試行、リクエスト、バックオフを含め、読み戻しプロセスに 60 秒の実時間上限を設定します。 期限に達したら、ユーザーがより詳細なトラブルシューティングを明示的に求めていない限り、処理を終了します。

• ツールの待機時間やスレッド待機のタイムアウトでは、呼び出しはキャンセルされません。キャンセルできない場合は、バックエンドの検証は実施していないと報告します。

• フラッシュは 1 回実行し（mlflow.flush_trace_async_logging() / await mlflow.flushTraces()）、保存した ID を取得します。

• ID がない場合は、設定済みの実験で実行時刻の範囲を指定し、max_results=1 とスパンの取得を有効にして、検索を 1 回実行します。

• UC の検索ではすべて trace.timestamp_ms が必要です。結果数の上限ではスキャン範囲は制限されません。Python の search_traces() には start_time キーワード引数がありません。

Python の読み戻しでは、この手順を保存済みの実行値に合わせて調整し、外部で期限を適用します。

mlflow.flush_trace_async_logging()
if trace_id:
    trace = mlflow.get_trace(trace_id)
else:
    traces = mlflow.search_traces(
        locations=[experiment_id],
        filter_string=(f"trace.timestamp_ms >= {run_start_ms} "
                       f"AND trace.timestamp_ms <= {run_end_ms}"),
        max_results=1, return_type="list", include_spans=True,
    )
    trace = traces[0] if traces else None
assert trace is not None, "No persisted trace read back"
assert run_start_ms <= trace.info.request_time <= run_end_ms
assert trace.data.spans, "No spans captured"

• 想定されるルート／グラフ、モデル、検索、ツールのスパンと、実際の I/O を確認します。スコアラーやアシスタントのテレメトリーではなく、アプリケーションのリクエストを確認します。

• 返されたメタデータ、または実験 ID がない場合はバインドされた UC のロケーションから、実験／ロケーションを確認します。

• 返されたスパンを再利用し、成功したら終了します。

• 元の時間予算内で具体的かつ迅速な修正を行った場合に限り、最大 1 回再試行します。

• プロバイダーキーの不足、認証／権限エラー、ウェアハウスのタイムアウト、RESOURCE_EXHAUSTED／429 が発生した場合は停止します。

• 並列検索、エージェントの繰り返し実行、UC への直接 SQL、未加工の REST、別の認証情報、ウェアハウスへのフォールバックは行いません。

• 操作／エラー、取得した ID、成功した項目、未検証の結果を報告します。シークレットではなく、不足している前提条件を求めます。

• バックエンドの検証が妨げられても、計測の変更は維持します。トレースが検証されるまで評価は保留します。

検証済みのトレース ID／リンクと、確認されたスパンを返します。Databricks では実験だけを示すリンクではなく、検証済みトレース URL のルールを使用します。未検証のリンクを証拠として示さないでください。

参考資料

• デプロイ、非同期エクスポート、サンプリング：本番環境。

• 非同期／スレッドのコンテキスト、編集、捕捉したエラーやリンク：高度なパターン。

• サービス間の親コンテキストの伝播：分散トレーシング。

• トレースに紐付けたユーザー評価：フィードバックの収集。

• 読み取れない非チャットのルートプレビュー：ルートスパンのプレビュー。

• 捕捉した動作の説明：mlflow-trace-analysis。要求された動作修正の実装：トレースの証拠を添えて mlflow-agent-improvement。これらは任意の後続タスクです。

• その他のインテグレーション：自動トレーシングのドキュメント。インストール済みのシグネチャ／型を確認してください。

• トピックが見つからない、または移動している場合：llms.txt。ドキュメントを利用できない場合は、ローカルのレシピとインストール済み API のイントロスペクションを使用し、正確性に不確実さが残る場合は中止してください。