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クライアントおよびツールとの互換性を保証します。

次の表では、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 ウェアハウス。後で参照できるようにウェアハウス ID を保存します。

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

• 環境にインストールされている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テーブルへのトレースのログ

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

MLflow SDK

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)

Model Serving endpoint

Databricksモデルサービング エンドポイントからUnity Catalogテーブルにトレースを書き込むには、パーソナル アクセス トークン (PAT) を構成する必要があります。

1. ユーザーまたはサービスプリンシパルMODIFYとSELECTに、 spansテーブルとannotationsテーブルへのアクセスを許可します。
2. トレースは、ユーザーまたはサービスプリンシパルの認証情報を使用して書き込まれるようにしてください。PATを使用する場合は、 Databricksモデルサービング エンドポイントの環境変数構成でDATABRICKS_TOKEN環境変数 を設定します。 OAuthを使用する場合は、 DATABRICKS_CLIENT_IDとDATABRICKS_CLIENT_SECRET環境変数を設定してください。
3. サービス提供エンドポイント内からではなく、 Databricksノートブックから、 mlflow.set_experiment Python APIを使用して UC トレースの場所を含むエクスペリメントを作成します。

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
)

1. 環境変数名としてMLFLOW_EXPERIMENT_IDを使用して、エクスペリメント ID をDatabricksモデルサービング エンドポイントの環境変数構成に追加します。

Third-party OTel client

OTel形式でトレースを保存する利点の1つは、OTelをサポートするサードパーティ製クライアントを使用してUnity Catalogテーブルに書き込むことができる点です。 このように記述されたトレースは、ルートスパンが存在する限り、テーブルにリンクされたMLflow拡張機能に表示されます。 以下の例は、OpenTelemetry OTLP エクスポーターを示しています。

Python

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Span exporter configuration
otlp_trace_exporter = OTLPSpanExporter(
    # Databricks hosted OTLP traces collector endpoint
    endpoint="https://myworkspace.databricks.com/api/2.0/otel/v1/traces",
    headers={
        "content-type": "application/x-protobuf",
        "X-Databricks-UC-Table-Name": "<catalog>.<schema>.<table_prefix>_otel_spans",
        "Authorization": "Bearer MY_API_TOKEN"
    },
)

Langfuse のトレースを Databricks にエクスポートするを参照してください。

UIでトレースを表示する

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

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

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

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

   

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

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を使用して削除できるエクスペリメント トレースと異なります。

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

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

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

その他のリソース

• 問題の観測と検出
• OTelスパン属性でトレースを検索する – Unity Catalogに保存されているサードパーティのOTelトレースをスパン属性で検索します。
• 既存のトレースを Unity Catalog に移行する - トレースを古いスキーマリンク形式からテーブルプレフィックス形式に移行します。
• 既存のトレースを Unity Catalog に移行する - Unity Catalog ストレージを使用していないエクスペリメントから既存のトレースを Unity Catalog に移行します。

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