トレースへのプログラムによるアクセス
プログラムによってトレースの検索、読み取り、分析を行います。mlflow.search_traces()を使用して、Unity Catalogテーブル、MLflowトラッキングサーバー、または推論テーブルに保存されているトレースをクエリーします。また、Unity Catalog内のトレースについては、SQLを使用してDeltaテーブルを直接クエリーします。トレースを取得したら、そのオブジェクトモデル（メタデータ、スパン、評価、トークン使用量）を読み取って、何が起きたのかを調べます。トレースのサブセットを選択して分析したり、評価データセットを作成したりできます。
mlflow.search_traces() API
def mlflow.search_traces(
experiment_ids: list[str] | None = None,
filter_string: str | None = None,
max_results: int | None = None,
order_by: list[str] | None = None,
extract_fields: list[str] | None = None,
run_id: str | None = None,
return_type: Literal['pandas', 'list'] | None = None,
model_id: str | None = None,
sql_warehouse_id: str | None = None,
include_spans: bool = True,
locations: list[str] | None = None,
) -> pandas.DataFrame | list[Trace]
mlflow.search_traces()使用すると、いくつかのディメンションに沿ってデータをフィルタリングおよび選択できます。
- クエリ文字列でフィルタリングする
- 場所によるフィルター: 体験、実行、モデル、またはUnity Catalogスキーマ
- データの制限: 結果の最大数、範囲を含めるか除外するか
- 戻り値の形式を調整する: データ形式、データの順序
search_traces() Pandas DataFrameまたはTraceオブジェクトのリストを返します。これをさらに分析したり、評価データセットに再構成したりできます。 これらの戻り値の型のスキーマの詳細を参照してください。
詳細については、 mlflow.search_traces() API ドキュメントを参照してください。
Databricksが管理するMLflowとOSS（オープンソースソフトウェア）のMLflowは、検索クエリ構文のほとんどを共有していますが、フィールドレベルでいくつかの違いがあります。詳細については、 「OSS MLflowとの違い」を参照してください。
mlflow.search_traces()問題
カテゴリー |
| 説明 | 例 |
|---|---|---|---|
クエリ文字列でフィルタリング |
| サポートされているフィルタとコンパレータについては、 「検索クエリ構文」を参照してください。 |
|
場所でフィルタリング |
| この引数には、フィルタリング用のエクスペリメント ID またはUnity Catalog |
|
| MLflow 実行 ID |
| |
| MLflow モデル ID |
| |
データを制限する |
| 返されるトレースの最大数（行） |
|
| 結果にスパンを含めるか除外します。スパンはトレースの詳細を含み、結果のサイズがはるかに大きくなる可能性があります。 |
| |
戻り値の形式 |
| 構文とサポートされているキーを参照してください。 |
|
| この関数は、 Pandas DataFrameまたは |
| |
非推奨 |
| 代わりに | |
| 代わりに、返された DataFrame 内のフィールドを選択するか、オブジェクトをトレースします。 | ||
| 代わりに |
検索クエリ構文
filter_string引数は、SQLライクなクエリ言語を使用してトレースをフィルタリングします。文字列値はシングルクォーテーションで囲む必要があります（例： trace.status = 'OK' ）。数値はクォーテーションで囲む必要はありません（例： trace.execution_time_ms > 1000 ）。条件をANDと組み合わせます。OR演算子はサポートされていません。
サポートされているフィルターとコンパレーター
Databricksが管理するMLflowでは、以下のフィールドと比較関数がサポートされています。
(UC only) とマークされたフィルターは、Unity Catalogに保存されているMLflowトレースでのみサポートされます。Unity CatalogにOpenTelemetryトレースを保存する方法については、こちらをご覧ください。
フィールドタイプ | フィールド | 比較器 | 例 |
|---|---|---|---|
トレースステータス |
|
|
|
トレースタイムスタンプ |
|
|
|
トレースID |
|
|
|
文字列フィールド |
|
|
|
リクエストとレスポンスの内容 （UCのみ） |
|
|
|
トークン数 （UCのみ） |
|
|
|
リンクされたプロンプト |
|
|
|
スパン名、タイプ、ステータス、サービス名 (UC のみ) |
|
|
|
OTelスパン属性 （UCのみ） |
|
|
|
タグ |
|
拡張モジュールに保存されているMLflowトレース ( Unity Catalogには保存されていない) については、 |
|
メタデータ |
|
拡張モジュールに保存されているMLflowトレース ( Unity Catalogには保存されていない) については、 |
|
フィードバック （UCのみ） |
|
|
|
期待事項 （UCのみ） |
|
|
|
OSS MLflowとの違い
Databricksが管理するMLflowの検索クエリ構文は、オープンソースのMLflowとほぼ同じですが、以下の点が異なります。
フィールド | Databricksが管理するMLflow | OSS MLflow | 注 |
|---|---|---|---|
| サポート対象（UCのみ） | サポートされていない | これらのフィールドを使用して、シリアル化されたリクエストおよびレスポンスのコンテンツをフィルタリングします。 |
| サポート対象（UCのみ） | サポートされていない | トークンの総数でトレースをフィルタリングします。 |
| サポート対象（UCのみ） | サポートされていない | OpenTelemetryのスパン属性に基づいてトレースをフィルタリングします。 |
| サポートされていない | サポート対象（SQLAlchemyストアのみ） | OSSは、トレースコンテンツ全体を対象とした全文検索のために |
| サポートされていない | サポート対象（リンクされたプロンプトタグにマッピングされています） | Databricksでは、最上位の |
| サポートされていない | サポート対象 | Databricksでは、代わりに |
| サポートされていない | サポート対象 | 特定の問題IDに関連付けられたトレースをフィルタリングします。 |
SQL によるトレーステーブルのクエリー
トレースが Unity Catalog に保存されている場合は、SDK に加えて Databricks SQL を使用してクエリーを実行できます。MLflow サービスは、OpenTelemetry 準拠のテーブルにスパンデータを保存し、そのデータを MLflow 形式に変換する Databricks SQL ビューを自動的に作成します。Unity Catalog のトレースストレージを設定するには、Store OpenTelemetry traces in Unity Catalog を参照してください。
Databricksでは、時間の経過とともにスキーマが変更される可能性がある、基盤となるOpenTelemetryテーブルではなく、ビューのクエリー（またはSDKの使用）を推奨しています。トレースのボリュームが大きい場合、ビューのパフォーマンスが低下する可能性があります。ビュー上にマテリアライズドビューを作成してインクリメンタルに更新するか、最近のデータに対して最高のパフォーマンスを得るためにSDKを使用してください。
{table_prefix}_trace_unified
トレース ID でグループ化されたすべてのトレースデータの統一されたビュー。各行には、未加工のスパンデータに加え、トレースメタデータ（MLflow タグ、メタデータ、評価）が保持されます。最上位レベルの列：
trace_id: STRING
client_request_id: STRING
request_time: TIMESTAMP
state: STRING
execution_duration_ms: DOUBLE
request: STRING
response: STRING
trace_metadata: VARIANT
tags: MAP<STRING, STRING>
spans: LIST<STRUCT> # per-span records: name, kind, timing, attributes, status, events, links
assessments: LIST<STRUCT> # feedback and expectation records with source, value, rationale, metadata
trace_metadata 列および span attributes フィールドは VARIANT です。マップ キー ルックアップではなく、コロン パス構文で読み取って必要な型にキャストします：
SELECT spans[0].attributes:`mlflow.spanInputs`::STRING FROM my_catalog.my_schema.my_prefix_trace_unified
{table_prefix}_trace_metadata
トレース ID ごとにグループ化された MLflow タグ、メタデータ、および評価のみが含まれます。スパン データではなく MLflow アノテーション データが必要な場合、統合ビューよりもパフォーマンスが高くなります。列：trace_id、client_request_id、tags、trace_metadata、assessments（統合ビューと同じ構造）。
アノテーション データ形式
MLflow注釈エンティティ（メタデータ、タグ、評価、ラン Link）も{table_prefix}_otel_annotationsテーブルに格納され、エンティティごとに1行が型付きのannotation_type（METADATA、TAG、FEEDBACK、EXPECTATION、またはRUN_LINK）とともに保存されます。テーブルはソフトデリート付きの追記専用であるため、取得時に重複排除を行います。annotation_idごとに最新の行を取得し（updated_atで降順に並べ替え）、deleted_atが設定されている行を除外します。valueおよびmetadataの各列はVARIANT（JSON）です。評価の場合、ユーザー提供のメタデータは内部のMLflowキー（プレフィックスmlflow.付き）の横に配置されます。ユーザーのメタデータを読み取る際は、内部キーを無視してください。
クエリーパフォーマンスの分析
遅いクエリーを診断するには、SQLウェアハウスのクエリー履歴でクエリープロファイルを調べます。 SQL warehouses ページを開き、warehouseを選択して、 Query history をクリックします。 MLflow をソースとするクエリーでフィルターし、クエリーを開いてそのプロファイルを表示し、次を確認します。
- スケジュール時間 ：スケジュール時間が長い場合、重いwarehouseの負荷によってクエリーがキューに入れられていることを意味します。MLflow UI で別のwarehouseに切り替えるか、クライアントで別のwarehouseを構成してください。
- 全体のクエリーパフォーマンス : 常に低速なクエリーの場合は、より大きな SQLウェアハウスを使用し、
trace.timestamp_msの範囲を狭め、可能であれば他のフィルター述語を削除します。
トレースデータの読み取り
MLflow Trace には 2 つのコンポーネントがあります。
完全なトレース オブジェクト モデルとスキーマについては、トレース データ モデルの参照を参照してください。
基本的なメタデータプロパティ
# Primary identifiers
print(f"Trace ID: {trace.info.trace_id}")
print(f"Client Request ID: {trace.info.client_request_id}")
# Status information
print(f"State: {trace.info.state}") # OK, ERROR, IN_PROGRESS
# Request/response previews (truncated)
print(f"Request preview: {trace.info.request_preview}")
print(f"Response preview: {trace.info.response_preview}")
ストレージの場所とエクスペリメント
location = trace.info.trace_location
print(f"Location type: {location.type}")
# Stored in Unity Catalog (recommended)
if location.uc_table_prefix:
print(f"UC location: {location.uc_table_prefix.full_table_prefix}")
# Stored in an MLflow experiment
if location.mlflow_experiment:
print(f"Experiment ID: {trace.info.experiment_id}")
# Stored in a Databricks inference table
if location.inference_table:
print(f"Table: {location.inference_table.full_table_name}")
バックエンドに関係なく、エクスペリメントはUIのエントリポイントとなります。Unity Catalogに保存されている場合でも、trace.info.experiment_idを使用してMLflow UIでトレースを開きます。
リクエストと応答のプレビュー
request_preview と response_preview のプロパティには、完全なリクエストおよびレスポンスデータの省略された概要が表示されるため、完全なペイロードを読み込まずに何が起きたかを理解できます。
request_preview = trace.info.request_preview
response_preview = trace.info.response_preview
# Full request/response data (see below)
full_request = trace.data.request
full_response = trace.data.response
時間に関するプロパティ
# Timestamps (milliseconds since epoch)
print(f"Start time (ms): {trace.info.request_time}")
print(f"Timestamp (ms): {trace.info.timestamp_ms}") # Alias for request_time
# Duration
print(f"Execution duration (ms): {trace.info.execution_duration}")
# Convert to human-readable format
import datetime
start_time = datetime.datetime.fromtimestamp(trace.info.request_time / 1000)
print(f"Started at: {start_time}")
タグとメタデータ
# Tags (mutable, can be updated after creation)
for key, value in trace.info.tags.items():
print(f" {key}: {value}")
print(f"Environment: {trace.info.tags.get('environment')}")
# Trace metadata (immutable, set at creation)
for key, value in trace.info.trace_metadata.items():
print(f" {key}: {value}")
トークンの使用情報
MLflow Tracing は、LLM プロバイダーの APIs によって返されたトークン数を使用して、LLM 呼び出しのトークン使用量を追跡できます。
# Get aggregated token usage (if available)
token_usage = trace.info.token_usage
if token_usage:
print(f"Input tokens: {token_usage.get('input_tokens')}")
print(f"Output tokens: {token_usage.get('output_tokens')}")
print(f"Total tokens: {token_usage.get('total_tokens')}")
トークン使用量の追跡方法は、LLMプロバイダーによって異なります。
シナリオ | トークンの使用状況を追跡する方法 |
|---|---|
OpenAI クライアントを使用して、MLflow Tracing がトークンの使用状況を自動的に追跡することを確認します。 | |
MLflow Tracing をネイティブサポートしている LLM プロバイダー | ネイティブのトークン追跡がサポートされているかどうかを確認するには、MLflow Tracing Integrations の下にあるプロバイダーの統合ページをご覧ください。 |
ネイティブの MLflow Tracing をサポートしていないプロバイダー |
|
AIプラットフォーム全体で複数のEndpointを監視します。 | 提供エンドポイント全体でシステムテーブルにトークンの使用量を記録するには、AI Gateway 使用状況の追跡を使用します。 |
評価
search_assessments() で評価を検索：
# Get all assessments
all_assessments = trace.search_assessments()
# Search by name
helpfulness = trace.search_assessments(name="helpfulness")
if helpfulness:
assessment = helpfulness[0]
print(f"Helpfulness: {assessment.value}")
print(f"Source: {assessment.source.source_type} - {assessment.source.source_id}")
print(f"Rationale: {assessment.rationale}")
# Search by type
feedback_only = trace.search_assessments(type="feedback")
expectations_only = trace.search_assessments(type="expectation")
# Search by span ID
span_assessments = trace.search_assessments(span_id=retriever_span.span_id)
# Include overridden assessments
all_including_invalid = trace.search_assessments(all=True)
評価の詳細にアクセス：
for assessment in trace.info.assessments:
print(f"Assessment: {assessment.name}")
print(f" Type: {type(assessment).__name__}")
print(f" Value: {assessment.value}")
print(f" Source: {assessment.source.source_type.value}")
if assessment.rationale:
print(f" Rationale: {assessment.rationale}")
if assessment.metadata:
print(f" Metadata: {assessment.metadata}")
if assessment.error:
print(f" Error: {assessment.error}")
スパンの操作
スパンはトレースの構成要素であり、個々の操作または作業単位を表します。トレースから取得された変更不可能な完了済みスパンは、Span クラスによって表されます。
スパンのプロパティへのアクセス
# Access all spans from a trace
spans = trace.data.spans
print(f"Total spans: {len(spans)}")
span = spans[0]
# Basic properties
print(f"Span ID: {span.span_id}")
print(f"Name: {span.name}")
print(f"Type: {span.span_type}")
print(f"Parent ID: {span.parent_id}") # None for root spans
# Timing (nanoseconds)
duration_ms = (span.end_time_ns - span.start_time_ns) / 1_000_000
print(f"Duration: {duration_ms:.2f}ms")
# Status
print(f"Status code: {span.status.status_code}")
# Inputs and outputs
print(f"Inputs: {span.inputs}")
print(f"Outputs: {span.outputs}")
特定のスパンを検索する
search_spans() を使用して、特定の基準に一致するスパンを検索します：
import re
from mlflow.entities import SpanType
# Search by exact name
retriever_spans = trace.search_spans(name="retrieve_documents")
# Search by regex pattern
tool_spans = trace.search_spans(name=re.compile(r".*_tool$"))
# Search by span type
chat_spans = trace.search_spans(span_type=SpanType.CHAT_MODEL)
llm_spans = trace.search_spans(span_type="CHAT_MODEL") # String also works
# Search by span ID
specific_span = trace.search_spans(span_id=retriever_spans[0].span_id)
# Combine criteria
tool_fact_check = trace.search_spans(
name="fact_check_tool",
span_type=SpanType.TOOL,
)
スパン属性
from mlflow.tracing.constant import SpanAttributeKey
chat_span = trace.search_spans(span_type=SpanType.CHAT_MODEL)[0]
# Get all attributes
for key, value in chat_span.attributes.items():
print(f" {key}: {value}")
# Get a specific attribute
specific_attr = chat_span.get_attribute("custom_attribute")
# Access chat-specific attributes using SpanAttributeKey
messages = chat_span.get_attribute(SpanAttributeKey.CHAT_MESSAGES)
tools = chat_span.get_attribute(SpanAttributeKey.CHAT_TOOLS)
# Access per-span token usage
input_tokens = chat_span.get_attribute("llm.token_usage.input_tokens")
output_tokens = chat_span.get_attribute("llm.token_usage.output_tokens")
リクエストおよびレスポンスのデータ
import json
# Get root span request/response
request_json = trace.data.request
response_json = trace.data.response
# Parse JSON strings
if request_json:
request_data = json.loads(request_json)
if response_json:
response_data = json.loads(response_json)
おすすめの方法
キーワード引数
mlflow.search_traces()では常にキーワード (名前付き) 引数を使用します。位置引数は許可されますが、関数引数は進化しています。
良い実践例: mlflow.search_traces(filter_string="trace.status = 'OK'")
悪い習慣: mlflow.search_traces([], "trace.status = 'OK'")
filter_string落とし穴
mlflow.search_traces()のfilter_string引数を使用して検索する場合は、次の点に注意してください。
- 接頭辞を使用する:
trace.、tag.、またはmetadata. - タグ名または属性名にドットが含まれている場合はバッククォートを使用します:
tag.`mlflow.traceName` - 一重引用符のみを使用してください:
'value'使用しないでください"value" - 時刻には日付ではなく Unix タイムスタンプ (ミリ秒) を使用します:
1749006880539 - ANDのみ使用: ORはサポートされません
サポートされているフィールドと演算子の完全なリストについては、 「検索クエリ構文」を参照してください。
SQLウェアハウス統合
Unity Catalog エクスペリメントに保存されたトレースを読み取るには、Databricks SQL Warehouse が 必要 です。Unity Catalog でバックアップされたエクスペリメントで mlflow.search_traces() または mlflow.get_trace() を呼び出す前に、MLFLOW_TRACING_SQL_WAREHOUSE_ID を設定してください。この環境変数が設定されていない場合、読み取りは SQL warehouse ID is required for accessing traces in UC tables. で失敗します。セットアップについては、Unity Catalog へのトレースの保存を参照してください。
推論テーブルのような大規模な非 Unity Catalog データセットの場合、SQL Warehouse はオプションですが、クエリーのパフォーマンスが向上します。
import os
os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'
# Required for UC-backed experiments. Improves performance for large non-UC datasets.
traces = mlflow.search_traces(
filter_string="trace.status = 'OK'",
locations=['my_catalog.my_schema'],
)
ページネーション
mlflow.search_traces() 結果をメモリ内に返すので、結果セットが小さい場合に適しています。大きな結果セットを処理するには、ページ区切りをサポートしているMlflowClient.search_traces()を使用します。
その他のリソース
- トレース全体での問題の検索 — MLflow にトレース全体の問題を検出させます。
- トレース データ モデルのリファレンス - 完全なトレース オブジェクト モデル: スパン、スパンの種類、ライフサイクル。
- トレースのエンリッチ: タグ、コンテキスト、フィードバック - より高度な検索を行うために、タグ、メタデータ、コンテキストでトレースをエンリッチします。
- 評価データセットの構築 - クエリーされたトレースをテストデータセットに変換します。
次のステップ: フィードバックの収集とデータセットの構築