instrumenting-with-mlflow-tracing

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 の場所から、実験／場所を確認します。

• 返されたスパンを再利用し、成功したら終了します。利用可能な agent-evaluation/scripts/validate_tracing_runtime.py は、別の監査を追加するのではなく、同じ期限内でこの確認の代わりに使用できます。

• 具体的な簡単な修正を行った場合に限り、元の時間枠内で最大 1 回再試行します。

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

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

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

• バックエンドの検証が妨げられている場合も、計測の変更は維持します。トレースが検証されるまで評価を一時停止します。

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

参考情報

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

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

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

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

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

• 捕捉された動作の説明：debug-agent。依頼された動作の修正を実装する場合：トレースの根拠を添えて fix-agent-issue を使用します。これらは任意の後続タスクです。

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

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