プログラムでトレースを検索する

mlflow.search_traces()を使用して、プログラムでトレースを検索および分析します。この関数は、 MLflowトラッキング サーバー、推論テーブル、またはUnity Catalogテーブルに保存されているトレースをクエリできます。 トレースのサブセットを選択して分析したり、評価データセットを作成したりできます。

mlflow.search_traces() API

Python

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()問題

カテゴリー	parameter: type	説明	例
クエリ文字列でフィルタリング	filter_string: str	サポートされているフィルタとコンパレータについては、 「検索クエリ構文」を参照してください。	trace.status = 'OK' AND tag.environment = 'production'
場所でフィルタリング	locations: list[str]	この引数には、フィルタリング用のエクスペリメント ID またはUnity Catalog catalog.schemaの場所のリストを指定できます。 これを使用して、推論テーブルまたはUnity Catalogテーブルに保存されているトレースを検索します。	['591498498138889', '782498488231546'] または ['my_catalog.my_schema']
	run_id: str	MLflow 実行 ID	35464a26b0144533b09d8acbb4681985
	model_id: str	MLflow モデル ID	acc4c426-5dd7-4a3a-85de-da1b22ce05f1
データを制限する	max_results: int	返されるトレースの最大数（行）	100
	include_spans: bool	結果にスパンを含めるか除外します。スパンはトレースの詳細を含み、結果のサイズがはるかに大きくなる可能性があります。	True
戻り値の形式	order_by: list[str]	構文とサポートされているキーを参照してください。	["timestamp_ms DESC", "status ASC"]
	return_type: Literal['pandas', 'list']	この関数は、 Pandas DataFrameまたはTraceオブジェクトのリストのいずれかを返すことができます。 スキーマの詳細を参照してください。	'pandas'
非推奨	experiment_ids: list[str]	代わりにlocationsを使用してください。
	extract_fields: list[str]	代わりに、返された DataFrame 内のフィールドを選択するか、オブジェクトをトレースします。
	sql_warehouse_id: str	代わりにMLFLOW_TRACING_SQL_WAREHOUSE_ID環境変数を使用してください。

検索クエリ構文

filter_string引数は、SQLライクなクエリ言語を使用してトレースをフィルタリングします。文字列値はシングルクォーテーションで囲む必要があります（例： trace.status = 'OK' ）。数値はクォーテーションで囲む必要はありません（例： trace.execution_time_ms > 1000 ）。条件をANDと組み合わせます。OR演算子はサポートされていません。

サポートされているフィルターとコンパレーター

Databricksが管理するMLflowでは、以下のフィールドと比較関数がサポートされています。

注記

(UC only) とマークされたフィルターは、Unity Catalogに保存されているMLflowトレースでのみサポートされます。Unity CatalogにMLflowトレースを保存する方法については、こちらをご覧ください。

フィールドタイプ	フィールド	比較器	例
トレースステータス	trace.status	=, !=	trace.status = 'OK'
トレースタイムスタンプ	trace.timestamp_ms、 trace.execution_time_ms 、 trace.end_time_ms （UCのみ）	=、!=、>、<、>=、 <=	trace.end_time_ms > 1762408895531
トレースID	trace.run_id	=	trace.run_id = 'run_id'
文字列フィールド	trace.client_request_id （UCのみ） trace.name	=、!=、LIKE、ILIKE、 RLIKE	trace.name LIKE '%Generate%'
リクエストとレスポンスの内容 （UCのみ）	trace.request, trace.response	=、!=、LIKE、ILIKE、 RLIKE	trace.request LIKE '%weather%'
トークン数 （UCのみ）	trace.token_count	=、!=、>、<、>=、 <=	trace.token_count > 1000
リンクされたプロンプト	prompt	= (フォーマット: 'name/version' )	prompt = 'qa-system-prompt/4'
スパン名、タイプ、およびステータス （UCのみ）	span.name、span.type、 span.status	=、!=、LIKE、ILIKE、 RLIKE	span.type RLIKE '^LLM'
OTelスパン属性 （UCのみ）	span.attributes.<key>	=、!=、LIKE、ILIKE、RLIKE、IS NULL、 IS NOT NULL	span.attributes.gen_ai.request.model = 'gpt-4'
タグ	tag.<key>	=、!=、LIKE、ILIKE、RLIKE、IS NULL、 IS NOT NULL 拡張モジュールに保存されているMLflowトレース ( Unity Catalogには保存されていない) については、 =と!=のみがサポートされます。	tag.environment = 'production'
メタデータ	metadata.<key>	=、!=、LIKE、ILIKE、RLIKE、IS NULL、 IS NOT NULL 拡張モジュールに保存されているMLflowトレース ( Unity Catalogには保存されていない) については、 =と!=のみがサポートされます。	metadata.`mlflow.trace.user` = 'user_123'
フィードバック （UCのみ）	feedback.<name>	=、!=、LIKE、ILIKE、 RLIKE	feedback.rating = 'excellent'
期待事項 （UCのみ）	expectation.<name>	=、!=、LIKE、ILIKE、 RLIKE	expectation.result = 'pass'

OSS MLflowとの違い

Databricksが管理するMLflowの検索クエリ構文は、オープンソースのMLflowとほぼ同じですが、以下の点が異なります。

フィールド	Databricksが管理するMLflow	OSS MLflow	注
trace.request, trace.response	サポート対象（UCのみ）	サポートされていない	これらのフィールドを使用して、シリアル化されたリクエストおよびレスポンスのコンテンツをフィルタリングします。
trace.token_count	サポート対象（UCのみ）	サポートされていない	トークンの総数でトレースをフィルタリングします。
span.attributes.<key>	サポート対象（UCのみ）	サポートされていない	OpenTelemetryのスパン属性に基づいてトレースをフィルタリングします。
trace.text	サポートされていない	サポート対象（SQLAlchemyストアのみ）	OSSは、トレースコンテンツ全体を対象とした全文検索のためにtrace.text公開します。Databricksでは、代わりにtrace.requestとtrace.responseを使用してトレースコンテンツをフィルタリングしてください。
trace.prompt	サポートされていない	サポート対象（リンクされたプロンプトタグにマッピングされています）	Databricksでは、最上位のpromptフィールドを使用してください。
trace.request_id	サポートされていない	サポート対象	Databricksでは、代わりにtrace.client_request_idを使用してください。
issue.id	サポートされていない	サポート対象	特定の問題IDに関連付けられたトレースをフィルタリングします。

おすすめの方法

キーワード引数

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ウェアハウス統合

mlflow.search_traces() オプションでDatabricks SQLウェアハウスを使用して、推論テーブルまたはUnity Catalogテーブルの大規模なトレース データセットのパフォーマンスを向上させることができます。 MLFLOW_TRACING_SQL_WAREHOUSE_ID環境変数を使用してSQLウェアハウス ID を指定します。

大規模なトレース データセットのパフォーマンスを向上させるために、Databricks SQL ウェアハウスを使用してトレース クエリを実行します。

Python

import os

os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'

# Use SQL warehouse for better performance
traces = mlflow.search_traces(
    filter_string="trace.status = 'OK'",
    locations=['my_catalog.my_schema'],
)

ページネーション

mlflow.search_traces() 結果をメモリ内に返すので、結果セットが小さい場合に適しています。大きな結果セットを処理するには、ページ区切りをサポートしているMlflowClient.search_traces()を使用します。

次のステップ

• チュートリアル: プログラムによるトレースの検索- 一連の簡単な例を実行する mlflow.search_traces()
• チュートリアル: ユーザーと環境のトレースと分析- トレースにコンテキスト メタデータを追加し、結果を分析する例を実行します。
• 例: トレースの分析- トレース分析のさまざまな例を参照します
• 評価データセットの構築 - クエリされたトレースをテストデータセットに変換します