Speichern von OpenTelemetry-Ablaufverfolgungen im Unity-Katalog

Azure Databricks unterstützt das Speichern von OpenTelemetry-Ablaufverfolgungen (OTel) in Unity Catalog-Tabellen. Standardmäßig speichert MLflow Ablaufverfolgungen, die nach Experimenten im MLflow-Steuerungsebenendienst organisiert sind. Das Speichern von Ablaufverfolgungen im Unity-Katalog mit dem OTel-Format bietet jedoch die folgenden Vorteile:

• Die Zugriffssteuerung wird über das Unity-Katalogschema und Tabellenberechtigungen verwaltet, anstatt ACLs auf Experimentebene. Benutzer mit Zugriff auf die Unity Catalog-Tabellen können alle in diesen Tabellen gespeicherten Spuren anzeigen, unabhängig davon, zu welchem Experiment die Spuren gehören.
• Trace-IDs verwenden das URI-Format anstelle des tr-<UUID> Formats, um die Kompatibilität mit externen Systemen zu verbessern.
• Speichern Sie große Mengen von Traces in Delta-Tabellen für langfristige Speicherung und Analyse.
• Direktes Abfragen von Ablaufverfolgungsdaten mithilfe von SQL über ein Databricks SQL Warehouse, das erweiterte Analysen und benutzerdefinierte Berichterstellung ermöglicht.
• Das OTel-Format stellt die Kompatibilität mit anderen OpenTelemetry-Clients und -Tools sicher.

Voraussetzungen

• Ein Unity-Katalog-aktivierter Arbeitsbereich.

• Stellen Sie sicher, dass die Vorschau "OpenTelemetry on Databricks" aktiviert ist, zusammen mit "Variant Shredding for Optimized Read Performance on Semi-Structured Data". Siehe Manage Azure Databricks Previews.

• Berechtigungen zum Erstellen von Katalogen und Schemas im Unity-Katalog.

• Ein Databricks SQL Warehouse mit CAN USE Berechtigungen. Speichern Sie die Lager-ID für späteren Verweis.

• Ein Arbeitsbereich in einer unterstützten Region. Weitere Informationen finden Sie unter Features mit eingeschränkter regionaler Verfügbarkeit.

• MLflow Python Bibliothek Version 3.11 oder höher in Ihrer Umgebung installiert:

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

Einrichtung: Erstellen eines Experiments mit einem Unity Catalog-Ablaufverfolgungsort

Führen Sie den folgenden Code aus, um ein Experiment zu erstellen und es an einen Unity Catalog-Überwachungspfad zu binden:

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

Sie können auch mlflow.create_experiment mit demselben trace_location Parameter verwenden. Im Gegensatz zu set_experiment setzt create_experiment das aktive Experiment nicht fest, daher müssen Sie set_experiment danach aufrufen, damit Sie sicherstellen, dass Ablaufverfolgungen an die richtige Position weitergeleitet werden.

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)

Nachdem Sie ein Experiment an einen UC-Ablaufverfolgungsort gebunden haben, können Sie das Experiment nicht erneut einem anderen UC-Ablaufverfolgungsort zuweisen. Mehrere Experimente können jedoch denselben UC-Trace-Standort gemeinsam nutzen.

Überprüfen von Tabellen

Nach dem Ausführen des Setupcodes werden vier neue Unity-Katalogtabellen im Schema in der Benutzeroberfläche des Katalog-Explorers angezeigt:

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

Berechtigungen erteilen

Ein Databricks-Benutzer oder Dienstprinzipal benötigt die folgenden Unity-Katalogberechtigungen , um MLflow-Ablaufverfolgungen aus den Unity Catalog-Tabellen zu schreiben oder zu lesen:

1. USE_CATALOG im Katalog.
2. USE_SCHEMA im Schema.
3. ÄNDERN und SELECT auf jeder der <table_prefix>_<type> Tabellen.

Protokolldaten in die Unity Catalog-Tabellen schreiben

Nach dem Erstellen der Tabellen können Sie Ablaufverfolgungen aus verschiedenen Quellen hinzufügen, indem Sie den Speicherort der Ablaufverfolgung angeben. Die Vorgehensweise hängt von der Quelle der Traces ab.

MLflow SDK

Der Speicherort der Unity-Katalog-Ablaufverfolgung kann mit der mlflow.set_experiment Python-API angegeben werden.

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)

Endpunkt für Modellbereitstellung

Um Ablaufverfolgungen aus einem Azure Databricks-Modell zu schreiben, das Endpunkte in Unity-Katalogtabellen bedient, müssen Sie ein persönliches Zugriffstoken (PERSONAL Access Token, PAT) konfigurieren.

1. Gewähren Sie einem Benutzer oder Dienstprinzipal MODIFY und SELECT Zugriff auf die Tabellen spans und annotations.
2. Stellen Sie sicher, dass Ablaufverfolgungen mithilfe der Anmeldeinformationen des Benutzer- oder Dienstkontos geschrieben werden. Wenn Sie einen PAT verwenden, legen Sie die Umgebungsvariable im DATABRICKS_TOKEN. Wenn Sie stattdessen OAuth verwenden, legen Sie die DATABRICKS_CLIENT_ID Variablen und DATABRICKS_CLIENT_SECRET Umgebungsvariablen fest.
3. Erstellen Sie aus einem Databricks-Notizbuch, nicht im Dienstendpunkt, ein Experiment mit einem UC-Ablaufverfolgungspunkt mithilfe der mlflow.set_experiment Python-API:

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. Fügen Sie die Experiment-ID zur Umgebungsvariablenkonfiguration des Databricks-Modell-Serving-Endpunkts mit MLFLOW_EXPERIMENT_ID als Namen der Umgebungsvariablen hinzu.

OTel-Client von Drittanbietern

Ein Vorteil des Speicherns von Ablaufverfolgungen im OTel-Format besteht darin, dass Sie mithilfe von Clients von Drittanbietern, die OTel unterstützen, in die Unity-Katalogtabellen schreiben können. Auf diese Weise geschriebene Ablaufverfolgungen werden in einem MLflow-Experiment angezeigt, das mit der Tabelle verknüpft ist, solange sie eine Stammspanne aufweisen. Das folgende Beispiel zeigt OpenTelemetry OTLP-Exporteure.

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

Weitere Informationen finden Sie unter Exportieren von Langfuse-Ablaufverfolgungen für Azure Databricks MLflow.

Anzeigen von Traces in der Benutzeroberfläche

Anzeigen von Ablaufverfolgungen, die im OTel-Format gespeichert sind, auf die gleiche Weise wie das Anzeigen anderer Ablaufverfolgungen:

1. Wechseln Sie in Ihrem Arbeitsbereich zu "Experimente".

2. Suchen Sie das Experiment, in dem Ihre Trace-Daten protokolliert werden. Zum Beispiel das vom mlflow.set_experiment("/Shared/my-genai-app-traces") festgelegte Experiment.

3. Klicken Sie auf die Registerkarte "Spuren", um eine Liste aller in diesem Experiment protokollierten Spuren anzuzeigen.

   

4. Wenn Sie Ihre Ablaufverfolgungen in einer Unity-Katalogtabelle gespeichert haben, ruft Azure Databricks Ablaufverfolgungen mithilfe eines SQL-Warehouse ab. Wählen Sie im Dropdownmenü ein SQL-Lagerhaus aus.

Weitere Informationen zur Verwendung der Benutzeroberfläche, um Traces zu suchen, finden Sie unter Traces in der MLflow-Benutzeroberfläche von Databricks anzeigen.

Aktivieren der Produktionsüberwachung

Um die Produktionsüberwachung mit ablaufverfolgungen zu verwenden, die im Unity-Katalog gespeichert sind, müssen Sie eine SQL Warehouse-ID für das Experiment konfigurieren. Der Überwachungsauftrag erfordert diese Konfiguration zum Ausführen von Scorerabfragen für Unity-Katalogtabellen.

Legen Sie die SQL-Lagerhaus-ID mithilfe von 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
)

Alternativ können Sie die Umgebungsvariable vor dem Starten der MLFLOW_TRACING_SQL_WAREHOUSE_ID Überwachung festlegen.

Wenn Sie diesen Schritt überspringen, scheitern Überwachungsaufträge mit einer Fehlermeldung, die angibt, dass die mlflow.monitoring.sqlWarehouseId Experiment-Markierung fehlt.

Um die Überwachung für Unity-Katalogablaufverfolgungen zu konfigurieren, benötigen Sie die folgenden Berechtigungen auf Arbeitsbereichsebene:

• CAN USE Berechtigung für das SQL Warehouse
• CAN EDIT Berechtigung für das MLflow-Experiment
• Berechtigung für den Überwachungsauftrag (automatisch erteilt, wenn Sie den ersten Scorer registrieren)

Der Überwachungsauftrag wird unter der Identität des Benutzers ausgeführt, der zuerst einen Scorer für das Experiment registriert hat. Die Berechtigungen dieses Benutzers bestimmen, auf welchen Überwachungsauftrag zugegriffen werden kann.

Begrenzungen

• Die Verarbeitung von Ablaufverfolgungen ist anfänglich auf 200 Ablaufverfolgungen pro Sekunde und pro Arbeitsbereich sowie 100 MB pro Sekunde und pro Tabelle beschränkt. Wenden Sie sich an Ihr Databricks-Kontoteam, wenn Sie höhere Grenzwerte benötigen.

• Ein Experiment kann nur zum Zeitpunkt seiner Erstellung an einen Unity Catalog-Protokollierungsort gebunden werden.

• Im Unity-Katalog gespeicherte Ablaufverfolgungen werden mit dem Wissens-Assistenten oder Dem Supervisor-Agent nicht unterstützt.

• Das Löschen einzelner Traces wird für im Unity-Katalog gespeicherte Traces nicht unterstützt. Um Spuren zu entfernen, müssen Sie Zeilen direkt aus den darunterliegenden Unity-Katalog-Tabellen mithilfe von SQL löschen. Dies unterscheidet sich von Experimentablaufverfolgungen, die mithilfe der MLflow-BEnutzeroberfläche oder -API gelöscht werden können.

• MLflow MCP-Server unterstützt keine Interaktion mit Traces, die im Unity-Katalog gespeichert sind.

• Protokolldaten können noch nicht in einen Standardspeicherkatalog geschrieben werden.

• Protokolle können noch nicht in den durch Private Link geschützten Speicher geschrieben werden.

Nächste Schritte

• OpenTelemetry-Ablaufverfolgungen abfragen, die im Unity-Katalog gespeichert sind
• Traces nach OTel-Span-Attributen suchen: Suchen Sie im Unity-Katalog nach Traces von Drittanbietern anhand von OTel-Span-Attributen.
• Migrieren Sie Verfolgungsspuren zum neuesten Unity Catalog-Tabellenformat: Migrieren Sie Verfolgungsspuren aus dem älteren schema-gebundenen Format zum Tabellenpräfixformat.