メインコンテンツまでスキップ

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

Databricks は、新しいワークロードと本番運用ワークロード向けに、MLflow トレースをUnity Catalogテーブルに保存することを推奨しています。トレースはOpenTelemetry (OTel) 形式で保存され、MLflow エクスペリメントにバインドされます。これらは引き続きUIのエントリポイントとして表示されます。Unity Catalogにトレースを保存すると、次の利点があります。

  • 長期的な保持と分析のために、エクスペリメントごとのトレース制限なく、大量のトレースをDeltaテーブルに保存します。
  • アクセス制御は、エクスペリメント レベルの ACL ではなく、 Unity Catalogスキーマとテーブル権限を通じて管理されます。 Unity Catalogテーブルにアクセスできるユーザーは、トレースがどの エクスペリメント に属しているかに関係なく、それらのテーブルに保存されているすべてのトレースを表示できます。
  • トレースは SQL ネイティブの Delta テーブルとして保存されるため、レイクハウス全体に統合されます。Databricks SQL warehouseを使用した SQL によるクエリー、AI/BI ダッシュボードの構築、Genie Code を使用した自然言語での質問、アラートや LakeFlow Pipelines の駆動、Spark や残りのレイクハウスエコシステムによる処理など、アドホックなアナリティクスやレポートの実行にとどまらない幅広い活用が可能です。
  • OTelフォーマットは、他のOpenTelemetryクライアントおよびツールとの互換性を保証します。
注記

OpenTelemetry トレース、 Logs 、メトリクス用の汎用 OTLP Endpoint をお探しですか?「 Zerobus Ingest を使用した OpenTelemetry データの取り込み」を参照してください。MLflow はZerobus Ingestを使用してトレースを Unity Catalog に書き込みますが、このページではトレースをエクスペリメントにバインドする MLflow 固有のワークフローについて説明します。

次の表では、Unity Catalogのストレージとエクスペリメントのストレージを比較しています。

機能

Unity Catalogに保存されているトレース

エクスペリメントに保存されたトレース

ストレージの制限

無制限

エクスペリメントあたり 100,000 トレース

クエリーオプション

MLflow UI と Python SDK、および SQL、Genie Code、AI/BI ダッシュボード、Spark ベースのツール

MLflow UIとPython SDK

ガバナンス

Unity Catalog のスキーマとテーブルの権限

エクスペリメントレベルのアクセス制御

OpenTelemetry の互換性

他の OTel クライアントおよびツールと互換性のある、OTel 形式で保存されたトレース

サポートされていない

機能

Unity Catalogに保存されているトレース

エクスペリメントに保存されたトレース

ストレージの制限

無制限

エクスペリメントあたり 100,000 トレース

クエリーオプション

MLflow UI と Python SDK、および SQL、Genie Code、AI/BI ダッシュボード、Spark ベースのツール

MLflow UIとPython SDK

ガバナンス

Unity Catalog のスキーマとテーブルの権限

エクスペリメントレベルのアクセス制御

OpenTelemetry の互換性

他の OTel クライアントおよびツールと互換性のある、OTel 形式で保存されたトレース

サポートされていない

要件​

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

  • CAN USE 権限を持つ Databricks SQL warehouse。後で参照できるように、warehouse IDを保存します。warehouseを選択せずに UI でトレースを表示するには、MLflow トレースのマネージドwarehouseを参照してください。

  • サポートされているリージョン内のワークスペース。地域限定で利用可能な機能については、こちらをご覧ください。

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

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

    実行中のノートブックで MLflow をインストールまたはアップグレードした場合は、ノートブックをデタッチおよび再アタッチして Python プロセスを再起動し、アップグレードされたパッケージを読み込んでください。これをスキップすると、以前に読み込まれたパッケージがメモリに残ったままになり、次のセクションのセットアップコードが cannot import name 'Sentinel' from 'typing_extensions' などのインポートエラーで失敗する可能性があります。

  • Unity Catalog にトレースを保存するために使用されるカタログおよびスキーマを作成するための権限。

注記

ALL_PRIVILEGES は、Unity Catalog トレーステーブルには不十分です。MODIFY および SELECT を明示的に付与します。

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

エクスペリメントを作成する前に、トレースを格納するカタログとスキーマが存在している必要があります。エクスペリメントを Unity Catalog トレースロケーションにバインドしても、これらは作成されません。スキーマがまだ存在しない場合は、最初に作成してください。カタログに対する USE CATALOG と、そのカタログに対する CREATE SCHEMA が必要です。

SQL
CREATE SCHEMA IF NOT EXISTS <catalog_name>.<schema_name>;

次に、次のコードを実行してエクスペリメントを作成し、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.
experiment = mlflow.set_experiment(experiment_id=experiment_id)

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

create_experiment を trace_location で呼び出したときにスキーマが存在しない場合、MLflow はエクスペリメントを作成しますが、トレースの場所のLinkに失敗し、呼び出しでエラーが発生します。トレースの場所がバインドされていない状態でエクスペリメントが残されます。最初にスキーマを作成し(上記のステップを参照)、残ったエクスペリメントを削除して、再度 create_experiment を呼び出します。set_experiment はアップサートであるため、スキーマが存在すれば、クリーンアップを行わずに同じエクスペリメント名に対して再実行できます。

エクスペリメントを 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トレースを書き込んだり読み取ったりするには、次のUnity Catalog権限が必要です。

  1. カタログに対して USE_CATALOGを実行します 。
  2. スキーマに対して USE_SCHEMAを使用します 。
  3. <table_prefix>_<type>テーブルそれぞれに対して MODIFY と SELECT を実行します 。
注記

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

トレースを書き込むDatabricksアプリを作成する際は、アプリに必要な権限があることを確認するために、これらのテーブルをアプリリソースとして追加してください。セットアップ手順については、「Unity CatalogにMLflowトレースを保存する」を参照してください。

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

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

Unity Catalogトレース場所は、 mlflow.set_experiment Python APIを使用して指定できます。

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>"

# 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
)

# 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 warehouse を使用してトレースを取得します。ドロップダウンメニューからSQLウェアハウスを選択します。

備考

ベータ版

マネージド warehouseを使用すると、SQLウェアハウスを選択しなくても UI がトレースを読み込みます。マネージドwarehouseはベータ版です。

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

エクスペリメント ストレージ (fallback)​

Unity Catalog は推奨されるストアです。Unity Catalog のトレースロケーションが構成されていない場合、MLflow はエクスペリメントのマネージドバックエンドにフォールバックします。このバックエンドは、ストレージの制限をエクスペリメントあたり 100,000 トレースに制限しており、最新の MLflow 機能と互換性がない場合があります。バックエンドに関係なく、トレースは常に MLflow エクスペリメントに属します。これは、トレースを表示するための UI エントリポイントです。

制限事項​

  • トレースデータの取り込みは、初期状態ではワークスペースあたり毎秒200トレース、テーブルあたり毎秒100MBに制限されています。より高い限度額が必要な場合は、Databricksのアカウントチームにお問い合わせください。

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

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

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

  • トレースデータをデフォルトのストレージカタログに書き込むことはまだできません。

  • プライベートサービスコネクトで保護されたストレージには、現時点ではトレースを書き込むことはできません。

  • サービス提供エンドポイントでトレースを有効にすると、サービス提供のスループットが低下する可能性があります。

  • 25 MB を超えるトレースには、MLflow UI または MLflow Python SDK からアクセスできません。これらのトレースにアクセスするには、SQL を使用して基礎となる Unity Catalog テーブルを直接クエリーします。

その他のリソース​

次のステップ: Unity Catalog でトレースをガバナンスおよびリダクションする