Databricks の外部にデプロイされたエージェントのトレース

MLflow Tracing は、実行の詳細をキャプチャして Databricks ワークスペースに送信することで、Databricks 外部にデプロイされた本番運用 AI エージェントに包括的な可観測性を提供し、MLflow UI でそれらを表示できます。

このページでは、トレースが有効な状態でDatabricks外部にエージェントをデプロイする方法について説明します。エージェントが Databricks にデプロイされている場合は、Databricks にデプロイされたエージェントをトレースするを参照してください。

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

外部でホストされているエージェントからのトレースは Databricks ワークスペースに送信され、MLflow エクスペリメントにログ記録されます。これが MLflow UI でそれらを表示するためのエントリポイントです。異なるのは、エクスペリメントを支えるストレージロケーションです。次の2つの選択肢があります。

• Unity Catalog ストレージ (本番運用に推奨): エクスペリメントを Unity Catalog のトレースロケーションにバインドして、トレースが Unity Catalog の Delta テーブルに格納されるようにします。デプロイする前に、セットアップが必要です。その結果、エクスペリメントごとの制限なしに、大量のトレースの長期間の保持が可能です。トレースはUnity Catalogのカタログ、スキーマ、およびテーブルの権限によって管理されており、Databricks SQL warehouse を介してSQLで直接クエリーできます。
• エクスペリメントベースのストレージ (default): トレースの場所を設定しない場合、トレースはエクスペリメントのアーティファクトとして保存されます。これは開発には便利ですが、エクスペリメントあたりのトレース制限があり、大量の本番運用トレースのクエリーには最適化されていません。

ここでは Unity Catalog ストレージが Databricks の外部で実行されるため、Databricks ノートブックから Unity Catalog をバックエンドとするエクスペリメントを作成し、以下の環境変数で名前または ID を参照してください。完全なセットアップ、前提条件、および権限については、Unity Catalog に OpenTelemetry トレースを保存するを参照してください。これらのトレースを読み取るには SQL Warehouse が必要です。Unity Catalog エクスペリメントで mlflow.search_traces() または mlflow.get_trace() を呼び出す前に MLFLOW_TRACING_SQL_WAREHOUSE_ID を設定してください。「SQLウェアハウスの統合」を参照してください。

前提 条件

必要なパッケージをインストールします。次の表に、オプションを示します。

パッケージ	推奨される使用例	利点
mlflow-tracing Python SDK または TypeScript SDK	本番運用のデプロイメント	無駄のない迅速な展開のための最小限の依存関係 大量のトレースに最適化されたパフォーマンス 本番運用 モニタリングのクライアント側トレースに着目
mlflow[databricks]	開発と実験	完全な MLflow 実験機能セット (UI、LLM-as-a-judge、開発ツールなど) すべての開発ツールとユーティリティが含まれています

パッケージ	推奨される使用例	利点
mlflow-tracing Python SDK または TypeScript SDK	本番運用のデプロイメント	無駄のない迅速な展開のための最小限の依存関係 大量のトレースに最適化されたパフォーマンス 本番運用 モニタリングのクライアント側トレースに着目
mlflow[databricks]	開発と実験	完全な MLflow 実験機能セット (UI、LLM-as-a-judge、開発ツールなど) すべての開発ツールとユーティリティが含まれています

Python

## Install mlflow-tracing for production deployment tracing
%pip install --upgrade "mlflow-tracing==3.1.0"

## Install mlflow for experimentation and development
%pip install --upgrade "mlflow[databricks]==3.1.0"

基本的なトレース設定

Databricks がトレースを収集できるように、Databricks ワークスペースに接続するようにアプリケーション デプロイを構成します。

次の環境変数を設定します。

Bash

# Required: Set the Databricks workspace host and authentication token
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"

# Required: Set MLflow Tracking URI to "databricks" to log to Databricks
export MLFLOW_TRACKING_URI=databricks

# Required: Configure the experiment name for organizing traces (must be a workspace path)
export MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

デプロイの例

環境変数を設定したら、それをアプリケーションに渡します。タブをクリックすると、接続の詳細をさまざまなフレームワークに渡す方法が表示されます。

Docker

Docker デプロイの場合は、コンテナー構成を介して環境変数を渡します。

Dockerfile

# Dockerfile
FROM python:3.11-slim

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application code
COPY . /app
WORKDIR /app

# Set default environment variables (can be overridden at runtime)
ENV DATABRICKS_HOST=""
ENV DATABRICKS_TOKEN=""
ENV MLFLOW_TRACKING_URI=databricks
ENV MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

CMD ["python", "app.py"]

環境変数を使用してコンテナを実行します。

Bash

docker run -d \
  -e DATABRICKS_HOST="https://your-workspace.cloud.databricks.com" \
  -e DATABRICKS_TOKEN="your-databricks-token" \
  -e MLFLOW_TRACKING_URI=databricks \
  -e MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app" \
  -e APP_VERSION="1.0.0" \
  your-app:latest

Kubernetes

Kubernetes デプロイの場合は、ConfigMaps と Secrets を使用して環境変数を渡します。

YAML

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: databricks-config
data:
  DATABRICKS_HOST: 'https://your-workspace.cloud.databricks.com'
  MLFLOW_TRACKING_URI: databricks
  MLFLOW_EXPERIMENT_NAME: '/Shared/production-genai-app'

---
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: databricks-secrets
type: Opaque
stringData:
  DATABRICKS_TOKEN: 'your-databricks-token'

---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: genai-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: your-app:latest
          envFrom:
            - configMapRef:
                name: databricks-config
            - secretRef:
                name: databricks-secrets
          env:
            - name: APP_VERSION
              value: '1.0.0'

トレース収集の検証

アプリをデプロイした後、トレースが適切に収集されていることを確認します。

Python

import mlflow
from mlflow.client import MlflowClient
import os

# Ensure MLflow is configured for Databricks
mlflow.set_tracking_uri("databricks")

# Check connection to MLflow server
client = MlflowClient()
try:
    # List recent experiments to verify connectivity
    experiments = client.search_experiments()
    print(f"Connected to MLflow. Found {len(experiments)} experiments.")

    # Check if traces are being logged
    traces = mlflow.search_traces(
        experiment_names=[os.getenv("MLFLOW_EXPERIMENT_NAME", "/Shared/production-genai-app")],
        max_results=5
    )
    print(f"Found {len(traces)} recent traces.")
except Exception as e:
    print(f"Error connecting to MLflow: {e}")
    print(f"Check your authentication and connectivity")

その他のリソース

• Databricks MLflow UI でトレースを表示する- MLflow UI でトレースを表示します。
• OpenTelemetry トレースを Unity Catalog に保存: ガバナンスされた Delta テーブルに本番運用トレースを保存し、長期的な保持と分析に役立てます。
• 本番運用モニタリング - アプリケーションの品質をモニタリングするために、本番運用トレースでスコアラーをランします。
• トレースにコンテキストを追加 - デバッグと知見の改善のために、ユーザーまたはセッションID、カスタムタグ、ユーザーフィードバックを添付します。