メインコンテンツまでスキップ
に最終更新

MLflowトレースをUnity Catalogに保存する

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。「Databricks プレビューの管理」を参照してください。

Databricksでは、OpenTelemetry 互換形式 (OTEL) を使用してMLflowトレースをUnity Catalogテーブルに保存することをサポートしています。 デフォルトでは、 MLflowはエクスペリメントごとに整理されたトレースをMLflowコントロールプレーンサービスに保存します。 ただし、OTEL 形式を使用してUnity Catalogにトレースを保存すると、次の利点があります。

  • アクセス制御は、エクスペリメント レベルの ACL ではなく、 Unity Catalogスキーマとテーブル権限を通じて管理されます。 Unity Catalogテーブルにアクセスできるユーザーは、トレースがどの エクスペリメント に属しているかに関係なく、それらのテーブルに保存されているすべてのトレースを表示できます。

  • トレース ID はtr-<UUID>形式ではなく URI 形式を使用するため、外部システムとの互換性が向上します。

  • Delta テーブルに無制限のトレースを保存し、トレース データの長期保持と分析を可能にします。パフォーマンスに関する考慮事項を参照してください。

  • Databricks SQLウェアハウスを通じてSQLを使用してトレース データを直接クエリし、高度なアナリティクスとカスタム レポートを可能にします。

  • OTEL形式は他のOpenTelemetryクライアントおよびツールとの互換性を保証します

前提条件​

  • Unity カタログ対応のワークスペース。

  • 「OpenTelemetry on Databricks」プレビューが有効になっていることを確認します。「Databricks プレビューの管理」を参照してください。

  • Unity Catalog でカタログとスキーマを作成する権限。

  • CAN USE権限を持つDatabricks SQL ウェアハウス。後で参照できるようにウェアハウス ID を保存します。

  • この機能がベータ版である間は、ワークスペースは次のいずれかのリージョンにある必要があります。

    • us-east-1
    • us-east-2
    • us-west-2
    • ca-central-1
    • ap-southeast-1
    • ap-southeast-2
    • ap-northeast-1
    • ap-northeast-2
    • ap-south-1
    • eu-central-1
    • eu-west-1
    • eu-west-2
    • sa-east-1

  • 環境にインストールされているMLflow Pythonライブラリ バージョン 3.11.0 以降:

    Bash
    pip install mlflow[databricks]>=3.11.0 --upgrade --force-reinstall

セットアップ: Unity Catalogトレース場所を使用してエクスペリメントを作成する​

次のコードを実行して、エクスペリメントを作成し、 Unity Catalogトレースの場所にバインドします。

Python
# Example values for the placeholders below:
# MLFLOW_TRACING_SQL_WAREHOUSE_ID: "abc123def456" (found in SQL warehouse URL)
# experiment_name: "/Users/user@company.com/traces"
# catalog_name: "main" or "my_catalog"
# schema_name: "mlflow_traces" or "production_traces"
# table_prefix: "my_otel"

import os
import mlflow
from mlflow.entities.trace_location import UnityCatalog

mlflow.set_tracking_uri("databricks")

# Specify the ID of a SQL warehouse you have access to.
os.environ["MLFLOW_TRACING_SQL_WAREHOUSE_ID"] = "<SQL_WAREHOUSE_ID>"
# Specify the name of the MLflow Experiment to use for viewing traces in the UI.
experiment_name = "<MLFLOW_EXPERIMENT_NAME>"
# Specify the name of the Catalog to use for storing traces.
catalog_name = "<UC_CATALOG_NAME>"
# Specify the name of the Schema to use for storing traces.
schema_name = "<UC_SCHEMA_NAME>"
# Specify the name of the prefix appended to every table storing trace data.
table_prefix = "<UC_TABLE_PREFIX>"

# mlflow.set_experiment is an upsert operation
experiment = mlflow.set_experiment(
    experiment_name=experiment_name,
    trace_location=UnityCatalog(
        catalog_name=catalog_name,
        schema_name=schema_name,
        table_prefix=table_prefix,  # defaults to experiment id if not provided
    ),
)

print(f"Experiment ID: {experiment.experiment_id}")
print(experiment.trace_location.full_otel_spans_table_name)

mlflow.create_experiment同じtrace_locationとともに使用することもできます。 set_experimentとは異なり、 create_experimentアクティブな拡張を設定しないため、トレースが正しい場所にルーティングされるようにするには、後でset_experimentを呼び出す必要があります。

Python
experiment_id = mlflow.create_experiment(
    name=experiment_name,
    trace_location=UnityCatalog(
        catalog_name=catalog_name,
        schema_name=schema_name,
        table_prefix=table_prefix,
    ),
)

# trace_location is optional here since
# the experiment is already bound to the UC trace location above.
mlflow.set_experiment(experiment_id=experiment_id)

エクスペリメントを UC トレースの場所にバインドすると、そのエクスペリメントを別の UC トレースの場所に再割り当てすることはできません。 ただし、複数のエクスペリメントが同じ UC トレースの場所を共有できます。

テーブルを検証する​

セットアップコードを実行すると、カタログエクスプローラーUIのスキーマに4つの新しいUnity Catalogテーブルが表示されます。

  • <table_prefix>_otel_annotations
  • <table_prefix>_otel_logs
  • <table_prefix>_otel_metrics
  • <table_prefix>_otel_spans

権限を付与する​

DatabricksユーザーまたはサービスプリンシパルがUnity CatalogテーブルからMLflowトレースを読み書きするには、次の権限が必要です。

  1. カタログに対する USE_CATALOG 権限。
  2. スキーマに対する USE_SCHEMA 権限。
  3. 各<table_prefix>_<type>テーブルに対する MODIFY および SELECT 権限。
注記

ALL_PRIVILEGES Unity Catalogトレース テーブルにアクセスするには不十分です。 MODIFY 権限 と SELECT 権限を明示的に付与する必要があります。

Unity Catalogテーブルへのトレースのログ​

テーブルを作成した後、トレースの場所を指定することで、さまざまなソースからトレースをテーブルに書き込むことができます。その方法は、トレースのジェネレータによって異なります。

Unity Catalogトレース場所は、 mlflow.set_experiment Python APIを使用するか、 MLFLOW_TRACING_DESTINATIONを設定することで指定できます。

Python
import mlflow

from mlflow.entities.trace_location import UnityCatalog

mlflow.set_tracking_uri("databricks")

# Specify the catalog, schema, and table prefix to use for storing Traces
catalog_name = "<UC_CATALOG_NAME>"
schema_name = "<UC_SCHEMA_NAME>"
table_prefix = "<UC_TABLE_PREFIX>"

# Option 1: Use the `set_experiment` API
# For existing experiments, it is not necessary to specify `trace_location`. MLflow
# retrieves the UC trace location bound to the experiment and routes traces to
# that location.
mlflow.set_experiment(
    experiment_name="...",
    trace_location=UnityCatalog(
        catalog_name=catalog_name,
        schema_name=schema_name,
        table_prefix=table_prefix,
    ),  # optional for existing experiments
)

# Option 2: Use the `MLFLOW_TRACING_DESTINATION` environment variable
import os

os.environ["MLFLOW_TRACING_DESTINATION"] = f"{catalog_name}.{schema_name}.{table_prefix}"

# Create and ingest an example trace using the `@mlflow.trace` decorator
@mlflow.trace
def test(x):
    return x + 1

test(100)

UIでトレースを表示する​

他のトレースを表示するのと同じ方法で、OTEL 形式で保存されたトレースを表示します。

  1. ワークスペースで、 エクスペリメント に移動します。

  2. トレースが記録されているエクスペリメントを見つけます。 たとえば、 mlflow.set_experiment("/Shared/my-genai-app-traces")によって設定されたエクスペリメント。

  3. 「Traces」 タブをクリックすると、そのエクスペリメントに記録されたすべてのトレースのリストが表示されます。

    トレースリストビュー

  4. トレースをUnity Catalogテーブルに保存した場合、 Databricks SQLウェアハウスを使用してトレースを取得します。 ドロップダウン メニューからSQLウェアハウスを選択します。

UI を使用してトレースを検索する方法の詳細については、 「 Databricks MLflow UI でトレースを表示する」を参照してください。

本番運用モニタリングを有効にする​

Unity Catalogに保存されたトレースを使用して本番運用モニタリングを使用するには、エクスペリメントのSQLウェアハウス ID を構成する必要があります。 モニタリング ジョブでは、 Unity Catalogテーブルに対してスコアラー クエリを実行するためにこの構成が必要です。

set_databricks_monitoring_sql_warehouse_id()を使用してSQLウェアハウス ID を設定します。

Python
from mlflow.tracing import set_databricks_monitoring_sql_warehouse_id

# Set the SQL warehouse ID for monitoring
set_databricks_monitoring_sql_warehouse_id(
    sql_warehouse_id="<SQL_WAREHOUSE_ID>",
    experiment_id="<EXPERIMENT_ID>"  # Optional, uses active experiment if not specified
)

あるいは、モニタリングを開始する前に、 MLFLOW_TRACING_SQL_WAREHOUSE_ID環境変数を設定することもできます。

このステップをスキップすると、モニタリング ジョブは失敗し、 mlflow.monitoring.sqlWarehouseIdエクスペリメント タグが見つからないことを示すエラーが表示されます。

Unity Catalogトレースのモニタリングを設定するには、次のワークスペース レベルの権限が必要です。

  • CAN USE SQLウェアハウスに対する権限
  • CAN EDIT MLflowエクスペリメントの許可
  • モニタリングジョブの権限（最初のスコアラーを登録すると自動的に付与されます）

モニタリング ジョブは、エクスペリメントに最初にスコアラーを登録したユーザーの ID で実行されます。 このユーザーの権限によって、モニタリング ジョブがアクセスできる内容が決まります。

制限事項​

  • トレースデータの取り込みは、ワークスペースあたり毎秒200トレース、テーブルあたり毎秒100MBに制限されています。

  • エクスペリメントは、エクスペリメントの作成時にUnity Catalogトレースの場所にのみバインドできます。

  • Unity Catalogに保存されたトレースは、 Knowledge AssistantまたはSupervisor Agentではサポートされていません。

  • 2TB を超えるトレース データがテーブルに保存されると、UI パフォーマンスが低下する可能性があります。パフォーマンスに関する考慮事項を参照してください。

  • Unity Catalogに保存されているトレースの個々のトレースの削除はサポートされていません。 トレースを削除するには、 SQLを使用して、基礎となるUnity Catalogテーブルから行を直接削除する必要があります。 これは、 MLflow UI またはAPIを使用して削除できるエクスペリメント トレースと異なります。

  • MLflow MCP サーバーは、Unity Catalog に保存されているトレースとのやり取りをサポートしていません。

次のステップ​