Stocker les traces OpenTelemetry dans Unity Catalog

Databricks recommande de stocker les traces MLflow dans des tables Unity Catalog pour les charges de travail nouvelles et de production. Les traces sont stockées au format OpenTelemetry (OTel) et liées à une experimentation MLflow, qui reste le point d'entrée de l'interface utilisateur pour les visualiser. Le stockage des traces dans Unity Catalog offre les avantages suivants :

Stockez de grands volumes de traces dans les tables Delta pour une rétention et une analyse à long terme, sans limite de trace par experimentation.
Le contrôle d'accès est géré via les autorisations de schéma et de table Unity Catalog plutôt que les ACL au niveau de l'expérimentation. Les utilisateurs ayant accès aux tables Unity Catalog peuvent consulter toutes les traces stockées dans ces tables, quelle que soit l'experimentation à laquelle les traces appartiennent.
Les traces sont stockées sous forme de tables Delta natives SQL, ce qui leur permet de s'intégrer à l'ensemble du lakehouse : query-les avec du SQL par le biais d'un Databricks SQL warehouse, élaborez des tableaux de bord AI/BI, posez des questions en langage naturel avec Genie Code, pilotez des alertes et des LakeFlow Pipelines, et traitez-les avec Spark et le reste de l'écosystème lakehouse, au lieu de vous limiter à l'exécution d'analytique et de rapports ad hoc.
Le format OTel assure la compatibilité avec d'autres clients et outils OpenTelemetry.

The following table compares Unity Catalog storage with Experimentation storage:

Compétence	Traces stockées dans Unity Catalog	Traces stockées dans une expérimentation
Limite de stockage	Illimité	100 000 traces par expérimentation
Options de query	Interface utilisateur et SDK Python de MLflow, ainsi que SQL, Genie Code, tableaux de bord AI/BI et tout outil basé sur Spark	Interface utilisateur de MLflow et SDK Python
Gouvernance	Autorisations pour le schéma et la table Unity Catalog	Contrôles d’accès au niveau de l’Experimentation
Compatibilité OpenTelemetry	Traces stockées au format OTel, compatibles avec d'autres clients et outils OTel	Non pris en charge

Compétence	Traces stockées dans Unity Catalog	Traces stockées dans une expérimentation
Limite de stockage	Illimité	100 000 traces par expérimentation
Options de query	Interface utilisateur et SDK Python de MLflow, ainsi que SQL, Genie Code, tableaux de bord AI/BI et tout outil basé sur Spark	Interface utilisateur de MLflow et SDK Python
Gouvernance	Autorisations pour le schéma et la table Unity Catalog	Contrôles d’accès au niveau de l’Experimentation
Compatibilité OpenTelemetry	Traces stockées au format OTel, compatibles avec d'autres clients et outils OTel	Non pris en charge

Prérequis

Un Workspace compatible avec Unity Catalog.
Un Databricks SQL warehouse avec CAN USE autorisations. Enregistrez l'ID du warehouse pour référence ultérieure.
Un workspace dans une région prise en charge. Voir les fonctionnalités avec disponibilité régionale limitée.
Version 3.14 ou ultérieure de la bibliothèque MLflow Python installée dans votre environnement :
Bash
```
pip install mlflow[databricks]>=3.14.0 --upgrade --force-reinstall
```
Si vous installez ou mettez à niveau MLflow dans un notebook en cours d'exécution, détachez et rattachez le notebook pour redémarrer le processus Python afin que les packages mis à niveau se chargent. Si vous ignorez cette étape, les packages précédemment chargés restent en mémoire et le code de configuration de la section suivante peut échouer avec une erreur d'importation telle que cannot import name 'Sentinel' from 'typing_extensions'.
Autorisations de créer le catalogue et le schéma utilisés pour stocker les traces dans Unity Catalog.

remarque

ALL_PRIVILEGES n’est pas suffisant pour les tables de trace Unity Catalog. Accorder explicitement MODIFY et SELECT.

Configuration : Créez une expérimentation avec un emplacement de trace Unity Catalog

Le catalogue et le schéma qui stockent les traces doivent exister avant de créer l’expérimentation. L’association d’une expérimentation à un emplacement de trace Unity Catalog ne permet pas de les créer. Si le schéma n’existe pas encore, créez-le d’abord. Vous avez besoin de USE CATALOG sur le catalogue et de CREATE SCHEMA sur celui-ci.

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

Exécutez ensuite le code suivant pour créer une expérimentation et la lier à un emplacement de trace 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)

Vous pouvez également utiliser mlflow.create_experiment avec le même parameter trace_location. Contrairement à set_experiment, create_experiment ne définit pas l'expérimentation active, vous devez donc appeler set_experiment ensuite pour vous assurer que les traces sont acheminées vers le bon emplacement :

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)

attention

Si le schéma n’existe pas lorsque vous appelez create_experiment avec un trace_location, MLflow crée l’expérimentation, mais le Link de l’emplacement de trace échoue et l’appel génère une erreur. L’expérimentation demeure sans aucun emplacement de trace qui lui soit associé. Créez d’abord le schéma (consultez l’étape ci-dessus), puis supprimez l’Experimentation restante et appelez à nouveau create_experiment. set_experiment est une opération de type upsert. Par conséquent, dès lors que le schéma existe, vous pouvez réexécuter l’opération sur le même nom d’Experimentation sans nettoyage.

Une fois que vous liez une experimentation à un emplacement de trace UC, vous ne pouvez pas réaffecter l'experimentation à un emplacement de trace UC différent. Cependant, plusieurs expérimentations peuvent partager le même emplacement de trace UC.

Vérifier les tables.

Après l'exécution du code de configuration, quatre nouvelles tables Unity Catalog apparaissent dans le schéma de l'interface utilisateur de l'explorateur de catalogue :

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

Accorder des autorisations

Un utilisateur Databricks ou un Service Principal a besoin des privilèges Unity Catalog suivants pour écrire ou lire les traces MLflow des tables Unity Catalog :

USE_CATALOG sur le catalogue.
**USE_SCHEMA** sur le schéma.
Modifier et sélectionner sur chacune des <table_prefix>_<type> tables.

remarque

ALL_PRIVILEGES n’est pas suffisant pour accéder aux tables de suivi Unity Catalog. Vous devez explicitement accorder MODIFIER et SÉLECTIONNER .

Lors de la création d’une application Databricks qui écrit des traces, ajoutez ces tables en tant que ressources d’application pour garantir que l’application dispose des privilèges nécessaires. Pour obtenir des instructions de configuration, consultez Stocker les traces MLflow dans Unity Catalog.

Enregistrer les Logs dans les tables Unity Catalog

Après avoir créé les tables, vous pouvez y écrire des traces provenant de diverses sources en spécifiant l'emplacement de la trace. La manière de procéder dépend de la source des traces.

MLflow SDK
Model Serving endpoint
Third-party OTel client

L’emplacement de trace Unity Catalog peut être spécifié à l’aide de l’ mlflow.set_experiment API Python.

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)

Pour écrire des traces d'un Endpoint de service de modèle Databricks dans des tables Unity Catalog, vous devez configurer un jeton d'accès personnel (PAT).

Accordez à un utilisateur ou à un Service Principal l’accès MODIFY et SELECT aux tables spans et annotations tables.
Assurez-vous que les traces sont écrites à l’aide des informations d’identification de l’utilisateur ou du Service Principal. Si vous utilisez un PAT, définissez la variable d'environnement DATABRICKS_TOKEN dans la configuration des variables d'environnement de l'Endpoint de diffusion de modèles Databricks. Si vous utilisez OAuth plutôt, définissez les variables d'environnement DATABRICKS_CLIENT_ID et DATABRICKS_CLIENT_SECRET.
À partir d'un Notebook Databricks, pas depuis le Endpoint de service, créez une Experimentation avec un emplacement de trace Unity Catalog à l'aide de l'API Python 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
)

Ajoutez l'ID de l'expérimentation à la configuration des variables d'environnement du service de modèle Databricks Endpoint avec MLFLOW_EXPERIMENT_ID comme nom de variable d'environnement.

L'un des avantages du stockage des traces au format OTel est que vous pouvez écrire dans les tables Unity Catalog à l'aide de clients tiers prenant en charge OTel. Les traces écrites de cette manière apparaissent dans une experimentation MLflow liée à la table tant qu'elles ont une portée racine. L'exemple suivant présente les exportateurs 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={
        &quot;content-type&quot;: &quot;application/x-protobuf&quot;,
        &quot;X-Databricks-UC-Table-Name&quot;: &quot;&lt;catalog&gt;.&lt;schema&gt;.&lt;table_prefix&gt;_otel_spans&quot;,
        &quot;Authorization&quot;: &quot;Bearer MY_API_TOKEN&quot;
    },
)

Voir Exporter des traces Langfuse vers Databricks.

Afficher les traces dans l'interface utilisateur

Affichez les traces stockées au format OTel de la même manière que vous visualisez les autres traces :

Dans votre Workspace, accédez aux **Expérimentations**.
Trouvez l'expérimentation où vos traces sont Logs. Par exemple, l'Experimentation défini par mlflow.set_experiment("/Shared/my-genai-app-traces").
Cliquez sur l'onglet Traces pour afficher une liste de toutes les traces enregistrées pour cette Experimentation.
Si vous avez stocké vos traces dans une table Unity Catalog, Databricks récupère les traces à l'aide d'un SQL warehouse. Sélectionnez un SQL warehouse 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 MLflow de Databricks.

Stockage d'expérimentation (fallback)

Unity Catalog est le magasin recommandé. Lorsqu’aucun emplacement de trace Unity Catalog n’est configuré, MLflow se replie sur le backend géré de l’expérimentation. Ce backend limite le stockage à 100 000 traces par expérimentation et peut ne pas être compatible avec les dernières fonctionnalités de MLflow. Quel que soit le backend, une trace appartient toujours à une expérimentation MLflow, qui constitue le point d’entrée de l’interface utilisateur pour l’affichage des traces.

Limitations

L'ingestion des traces est initialement limitée à 200 traces par seconde et par Workspace, et à 100 Mo par seconde et par table. Contactez l'équipe de votre compte Databricks si vous avez besoin de limites plus élevées.
Une expérimentation ne peut être liée qu'à un emplacement de trace Unity Catalog au moment de sa création.
Les traces stockées dans Unity Catalog ne sont pas prises en charge avec Knowledge Assistant ou Supervisor Agent.
La suppression de traces individuelles n'est pas prise en charge pour les traces stockées dans Unity Catalog. Pour supprimer des traces, vous devez supprimer les lignes directement des tables Unity Catalog sous-jacentes à l'aide de SQL. Cela diffère des traces d'Experimentation, qui peuvent être supprimées à l'aide de l'interface utilisateur ou de l'API MLflow.
Les traces ne peuvent pas encore être écrites dans un catalogue de default storage.
Les traces ne peuvent pas encore être écrites vers un stockage protégé par Private Link.
L'activation du traçage sur un endpoint de service peut réduire le throughput de service.

Ressources supplémentaires

Observer et trouver les problèmes
Rechercher des traces par attributs de span OTel : recherchez des traces OTel tierces stockées dans Unity Catalog par attributs de span.
Migrer les traces existantes vers Unity Catalog - Migrer les traces de l’ancien format lié au schéma vers le format avec préfixe de table.
Migrer les traces existantes vers Unity Catalog – Migrez les traces existantes vers Unity Catalog à partir d’experiments n’utilisant pas le stockage Unity Catalog.

Étape suivante : Gouverner et masquer les traces dans Unity Catalog

Prérequis​

Configuration : Créez une expérimentation avec un emplacement de trace Unity Catalog​

Vérifier les tables.​

Accorder des autorisations​

Enregistrer les Logs dans les tables Unity Catalog​

Afficher les traces dans l'interface utilisateur​

Stockage d'expérimentation (fallback)​

Limitations​

Ressources supplémentaires​