Aller au contenu principal
Dernière mise à jour le

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.
  • query des données de trace directement à l’aide de SQL via un Databricks SQL warehouse, permettant une analytique avancée et des rapports personnalisés.
  • Le format OTel assure la compatibilité avec d'autres clients et outils OpenTelemetry.

Prérequis​

  • Un Workspace compatible avec Unity Catalog.

  • Activez l’aperçu « Variant Shredding pour des performances de lecture optimisées sur les données semi-structurées ». Pour les Workspace avec un profil de sécurité de la conformité activé, vous devez également activer l’aperçu « Lakeflow Connect Zerobus Ingest ». Consultez Gérer les aperçus Databricks.

  • Autorisations de créer des catalogues et des schémas dans 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

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

Exécutez le code suivant pour créer et lier une expérimentation à 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.
mlflow.set_experiment(experiment_id=experiment_id)

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 :

  1. USE_CATALOG sur le catalogue.
  2. **USE_SCHEMA** sur le schéma.
  3. 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 .

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.

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)

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 :

  1. Dans votre Workspace, accédez aux **Expérimentations**.

  2. Trouvez l'expérimentation où vos traces sont Logs. Par exemple, l'Experimentation défini par mlflow.set_experiment("/Shared/my-genai-app-traces").

  3. Cliquez sur l'onglet Traces pour afficher une liste de toutes les traces enregistrées pour cette Experimentation.

    Vue de la liste des traces

  4. 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.

Activer le monitoring de la production​

Le monitoring de production est une couche de scoring complémentaire qui exécute des scorers sur vos traces. Cela fonctionne sur les traces quel que soit leur emplacement de stockage, vous pouvez donc l'utiliser en même temps que le stockage de traces Unity Catalog.

Pour utiliser le monitoring de production avec des traces stockées dans Unity Catalog, vous devez configurer un ID de SQL Warehouse pour l'Experimentation. Le job de monitoring nécessite cette configuration pour exécuter des requêtes d'évaluateur sur les tables Unity Catalog.

Définissez l'ID du SQL Warehouse à l'aide de set_databricks_monitoring_sql_warehouse_id():

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

Alternativement, vous pouvez définir la variable d'environnement MLFLOW_TRACING_SQL_WAREHOUSE_ID avant de démarrer le monitoring.

Si vous ignorez cette étape, les jobs de monitoring échouent avec une erreur indiquant que la balise d'expérimentation mlflow.monitoring.sqlWarehouseId est manquante.

Pour configurer le monitoring des traces Unity Catalog, vous avez besoin des autorisations au niveau du Workspace suivantes :

  • CAN USE autorisation sur le SQL Warehouse
  • CAN EDIT autorisation sur l'expérimentation MLflow
  • Autorisation sur le job de monitoring (accordée automatiquement lorsque vous enregistrez le premier évaluateur)

Le job de monitoring s'exécute sous l'identité de l'utilisateur qui a enregistré pour la première fois un évaluateur sur l'Experimentation. Les permissions de cet utilisateur déterminent ce à quoi le Job de monitoring peut accéder.

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​

Sur cette page