Stocker les traces OpenTelemetry dans le catalogue Unity

Azure Databricks prend en charge le stockage des traces OpenTelemetry (OTel) dans les tables du catalogue Unity. Par défaut, MLflow stocke les traces organisées par des expériences dans le service de plan de contrôle MLflow. Toutefois, le stockage des traces dans le catalogue Unity à l’aide du format OTel offre les avantages suivants :

• Le contrôle d’accès est géré via le schéma du catalogue Unity et les autorisations de table plutôt que les listes de contrôle d’accès au niveau de l’expérience. Les utilisateurs ayant accès aux tables du catalogue Unity peuvent afficher toutes les traces stockées dans ces tables, quelle que soit l’expérience à laquelle appartiennent les traces.
• Les ID de trace utilisent le format URI au lieu du format tr-<UUID>, ce qui améliore la compatibilité avec les systèmes externes.
• Stockez de grands volumes de traces dans les tables Delta pour la rétention et l’analyse à long terme.
• Interrogez les données de trace directement à l’aide de SQL via un entrepôt Databricks SQL, ce qui permet une analytique avancée et des rapports personnalisés.
• Le format OTel garantit la compatibilité avec d’autres clients et outils OpenTelemetry.

Prerequisites

• Un espace de travail avec catalogue Unity.

• Vérifiez que la préversion « OpenTelemetry on Databricks » est activée, ainsi que le déchiquetage de variante pour la performance de lecture optimisée sur des données semi-structurées. Consultez Gérer les préversions d'Azure Databricks.

• Autorisations pour créer des catalogues et des schémas dans le catalogue Unity.

• Entrepôt SQL Databricks ayant CAN USE des autorisations. Enregistrez l’ID d’entrepôt pour référence ultérieure.

• Espace de travail dans une région prise en charge. Consultez Fonctionnalités avec une disponibilité régionale limitée.

• MLflow Python bibliothèque version 3.11 ou ultérieure installée dans votre environnement :

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

Configuration : Créer une expérience avec un emplacement de trace du catalogue Unity

Exécutez le code suivant pour créer et lier une expérience à un emplacement de trace du catalogue Unity :

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

Vous pouvez également utiliser mlflow.create_experiment avec le même trace_location paramètre. Contrairement set_experimentà , create_experiment ne définit pas l’expérience active, vous devez donc appeler set_experiment par la suite pour vous assurer que les traces sont routées vers l’emplacement approprié :

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)

Une fois que vous liez une expérience à un emplacement de trace UC, vous ne pouvez pas réaffecter l’expérience à un autre emplacement de trace UC. Toutefois, plusieurs expériences peuvent partager le même emplacement de trace UC.

Vérifier les tables

Après avoir exécuté le code d’installation, quatre nouvelles tables de catalogue Unity apparaissent dans le schéma de l’interface utilisateur de l’Explorateur de catalogues :

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

Accorder des autorisations

Un utilisateur ou un principal de service Databricks a besoin des privilèges de catalogue Unity suivants pour écrire ou lire des traces MLflow à partir des tables du catalogue Unity :

1. USE_CATALOG sur le catalogue.
2. USE_SCHEMA sur le schéma.
3. MODIFIEZ et SELECT sur chacune des <table_prefix>_<type> tables.

Journaliser les traces dans les tables du catalogue Unity

Après avoir créé les tables, vous pouvez écrire des traces à partir de différentes sources en spécifiant l’emplacement de trace. La façon dont vous procédez dépend de la source des traces.

Kit de développement logiciel (SDK) MLflow

L’emplacement de trace du catalogue Unity peut être spécifié à l’aide de l’API mlflow.set_experiment 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)

Point de terminaison de mise en service de modèles

Pour écrire des traces à partir d’un modèle Azure Databricks servant le point de terminaison dans les tables du catalogue Unity, vous devez configurer un jeton d’accès personnel (PAT).

1. Accordez à un utilisateur ou à un principal de service MODIFY et SELECT un accès aux tables spans et annotations.
2. Vérifiez que les traces sont écrites à l’aide des informations d’identification de l’utilisateur ou du principal de service. Si vous utilisez un PAT, définissez la DATABRICKS_TOKEN variable d'environnement dans la configuration des variables d’environnement du point de terminaison du modèle Databricks. Si vous utilisez OAuth, définissez les variables d'environnement DATABRICKS_CLIENT_ID et DATABRICKS_CLIENT_SECRET.
3. À partir d’un notebook Databricks, et non à partir du point de terminaison de service, créez une expérience avec un emplacement de trace UC à l’aide de l’API mlflow.set_experiment 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. Ajoutez l’ID d’expérience au modèle Databricks qui sert la configuration des variables d’environnement du point de terminaison en MLFLOW_EXPERIMENT_ID tant que nom de variable d’environnement.

Client OTel tiers

L’un des avantages du stockage des traces au format OTel est que vous pouvez écrire dans les tables du catalogue Unity à l’aide de clients tiers qui prennent en charge OTel. Les traces écrites de cette façon apparaissent dans une expérience MLflow liée à la table tant qu’elles ont une étendue racine. L’exemple suivant montre les exportateurs OpenTelemetry OTLP.

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"
    },
)

Consultez Exporter les traces Langfuse vers Azure Databricks MLflow.

Afficher les traces dans l’interface utilisateur

Affichez les traces stockées au format OTel de la même façon que vous affichez d’autres traces :

1. Dans votre espace de travail, accédez à Expériences.

2. Recherchez l’expérience dans laquelle vos traces sont journalisées. Par exemple, l’expérience définie par mlflow.set_experiment("/Shared/my-genai-app-traces").

3. Cliquez sur l’onglet Traces pour afficher la liste de toutes les traces enregistrées dans cette expérience.

   

4. Si vous avez stocké vos traces dans une table Unity Catalog, Azure Databricks récupère les traces à l’aide d’un entrepôt SQL. Sélectionnez un entrepôt SQL dans le menu déroulant.

Pour plus d’informations sur l’utilisation de l’interface utilisateur pour rechercher des traces, consultez Afficher les traces dans l’interface utilisateur Databricks MLflow.

Activer la surveillance de la production

Pour utiliser la surveillance de production avec des traces stockées dans le catalogue Unity, vous devez configurer un ID d’entrepôt SQL pour l’expérience. Le travail de surveillance nécessite cette configuration pour exécuter des requêtes du moteur de score sur des tables du catalogue Unity.

Définissez l’ID de l’entrepôt SQL à l’aide de set_databricks_monitoring_sql_warehouse_id():

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
)

Vous pouvez également définir la variable d’environnement avant de commencer la MLFLOW_TRACING_SQL_WAREHOUSE_ID surveillance.

Si vous ignorez cette étape, les travaux de surveillance échouent avec une erreur indiquant que la mlflow.monitoring.sqlWarehouseId balise d’expérience est manquante.

Pour configurer la surveillance des traces du catalogue Unity, vous avez besoin des autorisations suivantes au niveau de l’espace de travail :

• CAN USE autorisation sur l’entrepôt SQL
• CAN EDIT autorisation concernant l'expérience MLflow
• Autorisation sur la tâche de surveillance (accordée automatiquement lorsque vous enregistrez le premier scoreur)

Le travail de surveillance s’exécute sous l’identité de l’utilisateur qui a d’abord inscrit un scoreur sur l’expérience. Les autorisations de cet utilisateur déterminent à quoi le travail de surveillance peut accéder.

Limitations

• L’ingestion de trace est initialement limitée à 200 traces par seconde par espace de travail et 100 Mo par seconde par table. Contactez votre équipe de compte Databricks si vous avez besoin de limites plus élevées.

• Une expérience ne peut être liée qu’à un emplacement de trace du catalogue Unity au moment de la création de l’expérience.

• Les traces stockées dans Unity Catalog ne sont pas compatibles avec l’Assistant de connaissances ou l’Agent superviseur.

• La suppression de traces individuelles n’est pas prise en charge pour les traces stockées dans le catalogue Unity. Pour supprimer des traces, vous devez supprimer des lignes directement des tables de catalogue Unity sous-jacentes à l’aide de SQL. Cela diffère des traces d’expérience, qui peuvent être supprimées à l’aide de l’interface utilisateur ou de l’API MLflow.

• Le serveur MCP MLflow ne prend pas en charge l’interaction avec les traces stockées dans le catalogue Unity.

• Les traces ne peuvent pas encore être écrites dans un catalogue de stockage par défaut .

• Les traces ne peuvent pas encore être écrites dans le stockage protégé par Private Link.

Étapes suivantes

• Interroger les traces OpenTelemetry stockées dans le catalogue Unity
• Rechercher des traces par attributs de portée OTel : Recherchez les traces OTel tierces stockées dans le catalogue Unity par attributs de portée.
• Migrez les traces vers le dernier format de tableau de catalogue Unity : migrez les traces du format lié au schéma plus ancien vers le format de préfixe de table.