MLflow Databricks SQL を使用して MLflow トレースをクエリする
プレビュー
MLflow トレースを Unity Catalog に保存する機能はベータ版です。
トレース データを OpenTelemetry 形式で Unity Catalog に保存すると、MLflow Python SDK を使用するか、Unity Catalog テーブルとビューを使用して Databricks SQL を通じてトレースをクエリできるようになります。
前提条件
- トレースをUnity Catalogテーブルに保存し、トレースを生成します。 「 MLflow トレースを Unity Catalog に保存する 」を参照してください。
MLflow Python SDKを使用してトレースをクエリする
MLflow Python SDK を使用して、トレース オブジェクトを検索および読み込みます。
MLFLOW_TRACING_SQL_WAREHOUSE_ID環境変数を使用して、検索クエリを実行するためのDatabricks SQL ウェアハウスを指定します。mlflow.search_tracesのlocations引数を使用して、トレースを含む 1 つ以上のMLflow拡張機能またはUnity Catalogスキーマを指定します。- Unity Catalogスキーマの名前、またはUnity CatalogスキーマにリンクされたMLflow拡張機能の ID のいずれかを指定できます。 「セットアップ: UC テーブルの作成とエクスペリメントのリンク」を参照してください。
import os
import mlflow
mlflow.set_tracking_uri("databricks")
# Specify the name of a catalog and schema containing traces
catalog_name = "<UC_CATALOG>"
schema_name = "<UC_SCHEMA>"
# Specify the ID of a Databricks SQL warehouse for executing search queries
os.environ["MLFLOW_TRACING_SQL_WAREHOUSE_ID"] = "<SQL_WAREHOUSE_ID>"
traces = mlflow.search_traces(
locations=[f"{catalog_name}.{schema_name}"],
filter_string="trace.status = 'OK'",
order_by=["timestamp_ms DESC"],
include_spans=False,
)
print(traces)
見つかったトレースを読み込むには:
import os
import mlflow
mlflow.set_tracking_uri("databricks")
# Specify the name of a catalog and schema containing traces
catalog_name = "<UC_CATALOG>"
schema_name = "<UC_SCHEMA>"
# Specify the trace UUID (example: "13ffa97d571048d69d21da12240d5863")
trace_uuid = "<TRACE_UUID>"
# Specify the ID of a Databricks SQL warehouse for executing search queries
os.environ["MLFLOW_TRACING_SQL_WAREHOUSE_ID"] = "<SQL_WAREHOUSE_ID>"
trace = mlflow.get_trace(
trace_id=f"trace:/{catalog_name}.{schema_name}/{trace_uuid}"
)
print(trace)
Databricks SQL を使用してトレースをクエリする
基礎となるデータは OpenTelemetry 準拠のテーブル形式で保存されますが、MLflow サービスはそれとともに Databricks SQL ビューを自動的に作成します。これらのビューは、OpenTelemetry データを MLflow 形式に変換します。大量のデータがある場合、これらのビューに対するクエリはパフォーマンスが維持されないため、段階的にマテリアライズする必要があります。
最近のデータで最高のパフォーマンスを得るには、トレースのクエリに API を使用し、ガイダンスについては「パフォーマンスに関する考慮事項」を参照してください。
mlflow_experiment_trace_unified
このビューでは、各トレース ID 別にグループ化されたすべてのトレース データの統合ビューが提供されます。各行には、生のスパン データとトレース情報メタデータが含まれています。メタデータには、MLflow タグ、メタデータ、評価が含まれます。
スキーマ
trace_id: STRING
client_request_id: STRING
request_time: TIMESTAMP
state: STRING
execution_duration_ms: DECIMAL(30,9)
request: STRING
response: STRING
trace_metadata: MAP<STRING, STRING>
tags: MAP<STRING, STRING>
spans: LIST<STRUCT>
trace_id: STRING
span_id: STRING
trace_state: STRING
parent_span_id: STRING
flags: INT
name: STRING
kind: STRING
start_time_unix_nano: BIGINT
end_time_unix_nano: BIGINT
attributes: MAP<STRING, STRING>
dropped_attributes_count: INT
events: LIST<STRUCT>
time_unix_nano: BIGINT
name: STRING
attributes: MAP<STRING, STRING>
dropped_attributes_count: INT
dropped_events_count: INT
links: LIST<STRUCT>
trace_id: STRING
span_id: STRING
trace_state: STRING
attributes: MAP<STRING, STRING>
dropped_attributes_count: INT
flags: INT
dropped_links_count: INT
status: STRUCT
message: STRING
code: STRING
resource: STRUCT
attributes: MAP<STRING, STRING>
dropped_attributes_count: INT
resource_schema_url: STRING
instrumentation_scope: STRUCT
name: STRING
version: STRING
attributes: MAP<STRING, STRING>
dropped_attributes_count: INT
span_schema_url: STRING
assessments: LIST<STRUCT>
assessment_id: STRING
trace_id: STRING
assessment_name: STRING
source: STRUCT
source_id: STRING
source_type: STRING
create_time: TIMESTAMP
last_update_time: TIMESTAMP
expectation: STRUCT
value: STRING
serialized_value: STRUCT
serialization_format: STRING
value: STRING
stack_trace: STRING
feedback: STRUCT
value: STRING
error: STRUCT
error_code: STRING
error_message: STRING
stack_trace: STRING
rationale: STRING
metadata: MAP<STRING, STRING>
span_id: STRING
overrides: STRING
valid: STRING
mlflow_experiment_trace_metadata
このビューには、トレース ID 別にグループ化された MLflow タグ、メタデータ、および評価のみが含まれ、MLflow データを取得する場合の統合ビューよりもパフォーマンスが優れています。
スキーマ
trace_id: STRING
client_request_id: STRING
tags: MAP<STRING, STRING>
trace_metadata: MAP<STRING, STRING>
assessments: LIST<STRUCT>
assessment_id: STRING
trace_id: STRING
assessment_name: STRING
source: STRUCT
source_id: STRING
source_type: STRING
create_time: TIMESTAMP
last_update_time: TIMESTAMP
expectation: STRUCT
value: STRING
serialized_value: STRUCT
serialization_format: STRING
value: STRING
stack_trace: STRING
feedback: STRUCT
value: STRING
error: STRUCT
error_code: STRING
error_message: STRING
stack_trace: STRING
rationale: STRING
metadata: MAP<STRING, STRING>
span_id: STRING
overrides: STRING
valid: STRING
MLflow ログレコードデータ形式
メタデータ、タグ、評価、実行へのリンクなどの MLflow トレース エンティティのデータは、OpenTelemetry ログ テーブルに保存されます。これらは対応するevent_nameを持つログ レコードとして保存され、そのフィールドは属性列に保存されます。ログ テーブルは追加専用であるため、取得時に各イベントの重複を排除し、最新バージョンを最新の状態にする必要があります。すべての属性は、元の型から文字列値としてシリアル化されます。
MLflowメタデータ
トレースごとにこれらのイベントが 1 つだけ存在します。
event_name: "genai.trace.metadata"
trace_id: STRING
time_unix_nano: BIGINT
attributes: STRUCT
client_request_id: STRING
trace_metadata: STRING (JSON-serialized metadata map)
MLflowタグ
各タグの更新は個別のログ レコードとしてシリアル化されます。key属性を使用して、各トレース内で重複を排除できます。
event_name: "genai.trace.tag"
trace_id: STRING
time_unix_nano: BIGINT
attributes: STRUCT
key: STRING
value: STRING
deleted: STRING (boolean "true"/"false")
MLflow評価
MLflow は、各評価の更新を個別のログ レコードとしてシリアル化します。assessment_id属性を使用して、各トレース内で重複を排除できます。
event_name: "genai.assessments.snapshot"
trace_id: STRING
span_id: STRING
time_unix_nano: BIGINT
attributes: STRUCT
assessment_id: STRING
assessment_name: STRING
source.source_id: STRING
source.source_type: STRING
create_time: STRING (serialized decimal number)
last_update_time: STRING (serialized decimal number)
expectation.value: STRING
expectation.serialized_value.serialization_format: STRING
expectation.serialized_value.value: STRING
feedback.value: STRING
feedback.error.error_code: STRING
feedback.error.error_message: STRING
feedback.error.stack_trace: STRING
rationale: STRING
metadata.<key>: STRING (one attribute per metadata key)
overrides: STRING
valid: STRING (boolean "true"/"false")
MLflow実行リンク
トレースと MLflow 実行間のリンクを表します。run_id属性を使用してtrace_idごとに重複排除できます。
event_name: "genai.run.link"
trace_id: STRING
time_unix_nano: BIGINT
attributes: STRUCT
run_id: STRING
deleted: STRING (boolean "true"/"false", true if the run link was removed)
パフォーマンスに関する考慮事項
-
トレース データのサイズが 2 TB を超えると、MLflow 固有の Databricks SQL ビューに対するクエリのパフォーマンスが低下し、増分的にマテリアライズされる可能性があります。
-
検索クエリが遅いかタイムアウトする場合は、 Z-Orderingを使用して、基礎となる OpenTelemetry テーブルを最適化することを検討してください。
Z-Orderingを有効にするには、テーブルに対して次のクエリを実行するジョブをスケジュールします。 ジョブは少なくとも 1 時間ごとに実行する必要があります。リアルタイム アクセスが必要な大きなテーブルの場合は、継続的に実行することを検討してください。Z-Orderingは増分的であるため、最初の実行はその後の実行よりも時間がかかる可能性があります。
SQLOPTIMIZE catalog.schema.mlflow_experiment_trace_otel_logs ZORDER BY (time_unix_nano, trace_id);
OPTIMIZE catalog.schema.mlflow_experiment_trace_otel_spans ZORDER BY (start_time_unix_nano, trace_id);
クエリパフォーマンスを分析する
遅いクエリを診断するには、 SQLクエリ履歴でクエリ プロファイルを検査できます。
- Databricksワークスペースの SQLウェアハウス ページに移動します。
- SQLウェアハウスを選択し、 [クエリ履歴] タブをクリックします。
- ソースとして MLflow が指定されたクエリを検索します。
- クエリをクリックすると、そのクエリ プロファイルが表示されます。
クエリ プロファイルで、次の点を検査します。
- スケジュール時間が長い: スケジュール時間が長い場合、ウェアハウスの使用頻度が高いためにクエリが待機状態になっています。MLflow UI のドロップダウン メニューを使用して別のSQLウェアハウスに切り替えるか、クライアントで別のウェアハウスを構成することを検討してください。
- 全体的なクエリ パフォーマンス: 一貫してクエリが遅い場合は、クエリ内の
trace.timestamp_msの上限と下限を厳しくしたり、他のフィルタ述語を削除したりするなど、より多くのSQLを備えた大規模な SQL ウェアハウスの使用を検討してください。