Archiviare tracce OpenTelemetry nel Catalogo Unity

Azure Databricks supporta l'archiviazione di tracce OpenTelemetry (OTel) nelle tabelle del catalogo Unity. Per impostazione predefinita, MLflow archivia le tracce organizzate dagli esperimenti nel servizio del piano di controllo MLflow. Tuttavia, l'archiviazione di tracce nel catalogo Unity con il formato OTel offre i vantaggi seguenti:

• Il controllo di accesso viene gestito tramite le autorizzazioni dello schema e della tabella del catalogo Unity anziché gli ACL a livello di esperimento. Gli utenti con accesso alle tabelle del catalogo Unity possono visualizzare tutte le tracce archiviate in tali tabelle, indipendentemente dall'esperimento a cui appartengono le tracce.
• Gli ID traccia usano il formato URI anziché il tr-<UUID> formato, migliorando la compatibilità con i sistemi esterni.
• Archiviare grandi volumi di tracce nelle tabelle Delta per la conservazione e l'analisi a lungo termine.
• Eseguire query sui dati di traccia direttamente usando SQL tramite un databricks SQL Warehouse, abilitando analisi avanzate e report personalizzati.
• Il formato OTel garantisce la compatibilità con altri client e strumenti OpenTelemetry.

Prerequisiti

• Un'area di lavoro abilitata per il Catalogo di Unity.

• Verificare che l'anteprima di "OpenTelemetry on Databricks" sia abilitata, insieme a "Variant Shredding for Optimized Read Performance on Semi-Structured Data". Vedere Manage Azure Databricks previews.

• Autorizzazioni per creare cataloghi e schemi nel catalogo Unity.

• Databricks SQL Warehouse con CAN USE autorizzazioni. Salvare l'ID magazzino per riferimento successivo.

• Un'area di lavoro in un'area supportata. Consulta Funzionalità con disponibilità regionale limitata.

• MLflow Python library versione 3.11 o successiva installata nell'ambiente:

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

Configurazione: creare un esperimento con un percorso di tracciamento del catalogo Unity

Eseguire il codice seguente per creare e associare un esperimento a un percorso di traccia del catalogo 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)

È anche possibile usare mlflow.create_experiment con lo stesso trace_location parametro. A differenza di set_experiment, create_experiment non imposta l'esperimento attivo, quindi è necessario chiamare set_experiment in seguito per assicurarsi che le tracce vengano instradate alla posizione corretta:

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)

Dopo aver associato un esperimento a una posizione di traccia UC, non è possibile riassegnare l'esperimento a un percorso di traccia UC diverso. Tuttavia, più esperimenti possono condividere la stessa posizione di traccia UC.

Verificare le tabelle

Dopo aver eseguito il codice di installazione, quattro nuove tabelle del catalogo Unity vengono visualizzate nello schema nell'interfaccia utente di Esplora cataloghi:

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

Concedere le autorizzazioni

Un utente o un principale di servizio di Databricks ha bisogno dei seguenti privilegi del Catalogo Unity per scrivere o leggere tracce MLflow dalle tabelle del Catalogo Unity:

1. USE_CATALOG nel catalogo.
2. USE_SCHEMA sullo schema.
3. MODIFY e SELECT in ognuna delle <table_prefix>_<type> tabelle.

Registrare le tracce nelle tabelle del Catalogo Unity

Dopo aver creato le tabelle, è possibile scrivere le tracce dalle diverse origini specificando la destinazione della traccia. La modalità di questa operazione dipende dall'origine delle tracce.

MLflow SDK

È possibile specificare il percorso di traccia del catalogo Unity usando 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)

Endpoint di gestione del modello

Per scrivere tracce da un endpoint di serving del modello Azure Databricks nelle tabelle di Unity Catalog, è necessario configurare un token di accesso personale.

1. Concedere a un utente o a un'entità di servizio MODIFY e SELECT l'accesso alle tabelle spans e annotations.
2. Assicurarsi che le tracce vengano scritte utilizzando le credenziali dell'utente o del principale del servizio. Se si utilizza un PAT, impostare la variabile di ambiente nella configurazione delle variabili di ambiente dell'endpoint del modello di servizio di Databricks. Se invece si usa OAuth, impostare le variabili di ambiente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET.
3. Da un notebook di Databricks, non dall'interno dell'endpoint di servizio, creare un esperimento con un percorso di traccia UC usando 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. Aggiungere l'ID esperimento al modello di Databricks che gestisce la configurazione delle variabili di ambiente dell'endpoint con MLFLOW_EXPERIMENT_ID come nome della variabile di ambiente.

Client OTel di terze parti

Uno dei vantaggi dell'archiviazione delle tracce nel formato OTel consiste nel fatto che è possibile scrivere nelle tabelle del catalogo Unity usando client di terze parti che supportano OTel. Le tracce scritte in questo modo vengono visualizzate in un esperimento MLflow collegato alla tabella purché abbiano un intervallo radice. L'esempio seguente mostra gli esportatori OTLP OpenTelemetry.

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

Consulta le tracce di esportazione di Langfuse su Azure Databricks MLflow.

Visualizzare le tracce nell'interfaccia utente

Visualizzare le tracce archiviate in formato OTel nello stesso modo in cui si visualizzano altre tracce:

1. Nell'area di lavoro passare a Esperimenti.

2. Trova l'esperimento in cui le tue tracce vengono registrate. Ad esempio, l'esperimento impostato da mlflow.set_experiment("/Shared/my-genai-app-traces").

3. Fare clic sulla scheda Tracce per visualizzare un elenco di tutte le tracce registrate nell'esperimento.

   

4. Se hai memorizzato le tue tracce in una tabella del Catalogo Unity, Azure Databricks recupera le tracce usando un magazzino SQL. Selezionare un SQL warehouse dal menu a discesa.

Per altre informazioni sull'uso dell'interfaccia utente per cercare tracce, vedere Visualizzare le tracce nell'interfaccia utente di Databricks MLflow.

Abilitare il monitoraggio della produzione

Per usare il monitoraggio della produzione con le tracce archiviate nel catalogo unity, è necessario configurare un ID di sql warehouse per l'esperimento. Il processo di monitoraggio richiede questa configurazione per eseguire query del scorer sulle tabelle del catalogo Unity.

Impostare l'ID di SQL Warehouse usando 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
)

In alternativa, è possibile impostare la variabile di ambiente prima di avviare il MLFLOW_TRACING_SQL_WAREHOUSE_ID monitoraggio.

Se si ignora questo passaggio, il monitoraggio dei processi ha esito negativo con un errore che indica che il tag dell'esperimento mlflow.monitoring.sqlWarehouseId non è presente.

Per configurare il monitoraggio per le tracce del catalogo Unity, sono necessarie le autorizzazioni a livello di area di lavoro seguenti:

• CAN USE autorizzazione per SQL Warehouse
• CAN EDIT autorizzazione per l'esperimento MLflow
• Autorizzazione per il processo di monitoraggio (concessa automaticamente quando si registra il primo scorer)

Il processo di monitoraggio viene eseguito con l'identità dell'utente che per primo ha registrato un scorer nell'esperimento. Le autorizzazioni di questo utente determinano a cosa può accedere il processo di monitoraggio.

Limitazioni

• L'inserimento di tracce è inizialmente limitato a 200 tracce al secondo per area di lavoro e 100 MB al secondo per tabella. Se sono necessari limiti più elevati, contattare il team account di Databricks.

• Un esperimento può essere associato solo a una posizione di traccia del catalogo Unity in fase di creazione dell'esperimento.

• Le tracce archiviate nel catalogo unity non sono supportate con Knowledge Assistant o Supervisor Agent.

• L'eliminazione di singole tracce non è supportata per le tracce archiviate nel catalogo unity. Per rimuovere le tracce, è necessario eliminare le righe direttamente dalle tabelle del catalogo Unity sottostanti usando SQL. Ciò differisce dalle tracce dell'esperimento, che possono essere eliminate usando l'interfaccia utente o l'API MLflow.

• Il server MCP MLflow non supporta l'interazione con le tracce archiviate nel catalogo unity.

• Le tracce non possono ancora essere scritte in un catalogo di archiviazione predefinito .

• Le tracce non possono ancora essere scritte nella risorsa di archiviazione protetta da collegamento privato.

Passaggi successivi

• Eseguire query su tracce OpenTelemetry archiviate nel Catalogo Unity
• Cercare tracce dai attributi span OTel: cercare tracce OTel di terze parti archiviate in Unity Catalog basandosi sugli attributi span.
• Eseguire la migrazione delle tracce al formato di tabella del catalogo Unity più recente: eseguire la migrazione delle tracce dal formato precedente collegato allo schema al formato di prefisso di tabella.