トレースの概念

トレースは、アプリケーションを介したリクエストの完全な実行フローをキャプチャする観測技術です。個別のイベントを記録する従来のログ記録とは異なり、トレースでは、システムがデータをどのように流すかを示す詳細なマップを作成し、その途中で行われたすべての操作を記録します。

GenAIアプリケーションは、LLM、リトリーバー、ツール、エージェントなど、複数のコンポーネントを組み合わせた複雑な多段階ワークフローを実行します。トレース機能を使うことで、実行フロー全体をキャプチャし、ワークフローのデバッグが可能になります。

トレース構造

MLflowトレースは、次の 2 つの主要なオブジェクトで構成されます。

1. Trace.info タイプTraceInfo : トレースの発生元、状態、および実行時間を記述するメタデータ。TraceInfoもタグを保持します。タグは、ユーザー、セッション、開発者が提供するキーと値のペアであり、トレースの検索やフィルタリングに使用できます。

2. Trace.data タイプTraceData : 入力から出力までのアプリケーションのステップごとの実行をキャプチャするインストルメントされたSpanオブジェクトを含む実際のペイロード。

MLflowのトレース機能は、広く採用されている可観測性に関する業界標準であるOpenTelemetryの仕様と互換性があります。トレースは他のOpenTelemetry互換の観測ツールとの相互運用性を維持しつつ、MLflowはOpenTelemetryモデルをGenAI固有の構造と属性で拡張します。

トレース情報

TraceInfo 、全体的なトレースの軽量メタデータを提供します。主なフィールドには以下が含まれます。

フィールド	説明
trace_id	トレースの一意の識別子
trace_location	トレースが保存される場所 ( MLflowエクスペリメントまたはDatabricks推論テーブル)
request_time	トレースの開始時間（ミリ秒）
state	トレースステータス: OK 、 ERROR 、 IN_PROGRESS 、または STATE_UNSPECIFIED
execution_duration	トレースの継続時間（ミリ秒）
request_preview	入力のJSONエンコードされたプレビュー（ルートスパン入力）
response_preview	JSON エンコードされた出力のプレビュー (ルート スパン出力)
tags	トレースのフィルタリングと検索のためのキーと値のペア

トレースデータ

TraceDataオブジェクトは、実行の詳細が保存されるSpanオブジェクトのコンテナーです。各スパンは、次のような特定の操作に関する情報を取得します。

• リクエストとレスポンス
• レイテンシ測定
• LLMメッセージとツールの問題
• 取得した文書とコンテキスト
• メタデータと属性

スパンは親子の接続を通じて階層構造を形成し、アプリケーションの実行フローを表すツリーを作成します。

タグ

タグは、整理とフィルタリングのためにトレースに添付される変更可能なキーと値のペアです。MLflow は、一般的なユースケース向けに標準タグを定義します。

• mlflow.trace.session: 関連するトレースをグループ化するためのセッション識別子
• mlflow.trace.user: ユーザーごとのインタラクションを追跡するためのユーザー識別子
• mlflow.source.name: トレースを生成したエントリポイントまたはスクリプト
• mlflow.source.git.commit: ソースコードの Git コミットハッシュ（該当する場合）
• mlflow.source.type: ソースタイプ ( PROJECT 、 NOTEBOOKなど)

特定のニーズに合わせてカスタム タグを追加することもできます。詳細については、 「トレースにコンテキストを追加する」および「カスタム タグ/メタデータを添付する」を参照してください。

ストレージレイアウト

MLflowは、パフォーマンスとコストの両面でトレースストレージを最適化します。ストレージの場所をカスタマイズするには、拡張機能を作成する際にUnity Catalogボリュームをアタッチします。 アクセスは、 Unity Catalogボリューム権限によって管理されます。

TraceInfo データはインデックス付きの行としてリレーショナルデータベースに直接保存されるため、トレースの検索やフィルタリングを高速に行うことができます。

TraceData （スパンは）リレーショナルデータベースではなくアーティファクトストレージに保存されます。これは、スパンのサイズが大きいためです。これにより、トレース量が増加してもクエリの高速性が維持されます。

アクティブなトレースと終了したトレース

アクティブトレースとは、MLflowが現在書き込んでいるトレースのことです。たとえば、 @mlflow.traceで装飾された関数が実行されている間などです。装飾された関数が終了すると、トレースは終了しますが、新しいデータで注釈を付けることは可能です。

アクティブなトレースまたは最近のトレースを操作するには、次の方法を使用します。

• mlflow.get_active_trace_id() : 現在アクティブなトレースのIDを返します。
• mlflow.get_last_active_trace_id() : 最新の完了したトレースのIDを返します。

次のステップ

• スパンの概念— スパンとは何か、そしてスパンが個々のオペレーションをどのように捉えるのかを学びます。
• はじめに: MLflow Tracing for GenAI ( Databricksノートブック) — ノートブックでトレースを実際に体験してください。