OpenTelemetry-traceringen opslaan in Unity Catalog

Azure Databricks ondersteunt het opslaan van OTelemetry-traceringen (OpenTelemetry) in Unity Catalog-tabellen. Standaard slaat MLflow traceringen op die zijn ingedeeld op experimenten in de MLflow-besturingsvlakservice. Het opslaan van traceringen in Unity Catalog met behulp van OTel-indeling biedt echter de volgende voordelen:

• Toegangsbeheer wordt beheerd via schema- en tabelmachtigingen voor Unity Catalog in plaats van ACL's op experimentniveau. Gebruikers met toegang tot de Unity Catalog-tabellen kunnen alle traceringen bekijken die zijn opgeslagen in deze tabellen, ongeacht het experiment waartoe de traceringen behoren.
• Traceer-id's gebruiken de URI-indeling in plaats van de tr-<UUID>-indeling, waarmee de compatibiliteit met externe systemen wordt verbeterd.
• Sla grote hoeveelheden traceringen op in Delta-tabellen voor langetermijnretentie en -analyse.
• Query's uitvoeren op traceringsgegevens rechtstreeks met behulp van SQL via een Databricks SQL-warehouse, waardoor geavanceerde analyses en aangepaste rapportage mogelijk zijn.
• OTel-indeling zorgt voor compatibiliteit met andere OpenTelemetry-clients en hulpprogramma's.

Vereiste voorwaarden

• Een werkruimte waarvoor Unity Catalog is ingeschakeld.

• Zorg ervoor dat de preview van OpenTelemetry on Databricks is ingeschakeld, samen met Variant Shredding for Optimized Read Performance on Semi-Structured Data. Zie Manage Azure Databricks previews.

• Machtigingen voor het maken van catalogi en schema's in Unity Catalog.

• Een Databricks SQL Warehouse met CAN USE machtigingen. Sla de magazijn-id op voor later gebruik.

• Een werkruimte in een ondersteunde regio. Zie Functies met beperkte regionale beschikbaarheid.

• MLflow Python bibliotheekversie 3.11 of hoger geïnstalleerd in uw omgeving:

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

Installatie: Een experiment maken met een traceringslocatie van de Unity-catalogus

Voer de volgende code uit om een experiment te maken en te binden aan een traceringslocatie van Unity Catalog:

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

U kunt ook mlflow.create_experiment gebruiken met dezelfde trace_location parameter. In tegenstelling tot set_experiment, create_experiment wordt het actieve experiment niet ingesteld, dus u moet later aanroepen set_experiment om ervoor te zorgen dat traceringen worden gerouteerd naar de juiste locatie:

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)

Wanneer u een experiment aan een UC-traceringslocatie koppelt, kunt u het experiment niet opnieuw toewijzen aan een andere UC-traceringslocatie. Meerdere experimenten kunnen echter dezelfde UC-traceringslocatie delen.

Tabellen verifiëren

Nadat u de installatiecode hebt uitgevoerd, worden vier nieuwe Unity Catalog-tabellen weergegeven in het schema in de gebruikersinterface van Catalog Explorer:

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

Machtigingen verlenen

Een Databricks-gebruiker of -service-principal heeft de volgende Unity Catalog-bevoegdheden nodig om MLflow-traceringen te schrijven of te lezen uit de Unity Catalog-tabellen:

1. USE_CATALOG op de catalogus.
2. USE_SCHEMA in het schema.
3. WIJZIGEN en SELECT op elk van de <table_prefix>_<type> tabellen.

Registreer logboekvermeldingen voor de Unity Catalog-tabellen

Nadat u de tabellen hebt gemaakt, kunt u er traceringen naar schrijven vanuit verschillende bronnen door de traceringslocatie op te geven. Hoe u dit doet, is afhankelijk van de bron van de traceringen.

MLflow SDK

De traceringslocatie van de Unity-catalogus kan worden opgegeven met behulp van de 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
)

# Create and ingest an example trace using the `@mlflow.trace` decorator
@mlflow.trace
def test(x):
    return x + 1

test(100)

Eindpunt voor modelservice

Als u traceringen wilt schrijven van een Azure Databricks-model dat eindpunt naar Unity Catalog-tabellen bedient, moet u een persoonlijk toegangstoken (PAT) configureren.

1. Een gebruiker of service-principal MODIFY en SELECT toegang verlenen tot de spans en annotations tabellen.
2. Zorg ervoor dat traceringen worden geschreven met behulp van de identiteitsgegevens van de gebruiker of service-principal. Als u een PAT gebruikt, stelt u de DATABRICKS_TOKEN omgevingsvariabele in het Databricks-model in voor de configuratie van omgevingsvariabelen van het eindpunt. Als u in plaats daarvan OAuth gebruikt, stelt u de DATABRICKS_CLIENT_ID en DATABRICKS_CLIENT_SECRET omgevingsvariabelen in.
3. Maak vanuit een Databricks-notebook, niet vanuit het servereindpunt, een experiment met een UC-traceringslocatie met behulp van de 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. Voeg de experiment-id toe aan het Databricks-model voor de configuratie van omgevingsvariabelen van het eindpunt met MLFLOW_EXPERIMENT_ID als naam van de omgevingsvariabele.

OTel-client van derden

Een voordeel van het opslaan van traces in het OTel-formaat is dat u naar de Unity Catalog-tabellen kunt schrijven met clients van derden die ondersteuning bieden voor OTel. Traceringen die op deze manier zijn geschreven, worden weergegeven in een MLflow-experiment dat is gekoppeld aan de tabel zolang ze een root span hebben. In het volgende voorbeeld ziet u OpenTelemetry OTLP exporters.

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

Zie Langfuse-traceringen exporteren naar Azure Databricks MLflow.

Traceringen weergeven in de gebruikersinterface

Traceringen weergeven die zijn opgeslagen in OTel-indeling op dezelfde manier als u andere traceringen bekijkt:

1. Ga in uw werkruimte naar Experimenten.

2. Zoek het experiment waarin uw traceringen worden vastgelegd. Bijvoorbeeld het experiment dat is ingesteld door mlflow.set_experiment("/Shared/my-genai-app-traces").

3. Klik op het tabblad Traceringen om een lijst weer te geven met alle traceringen die zijn geregistreerd bij dat experiment.

   

4. Als u uw traceringen heeft opgeslagen in een Unity Catalog-tabel, haalt Azure Databricks de traceringen op met behulp van een SQL-warehouse. Selecteer een SQL Warehouse in de vervolgkeuzelijst.

Zie Traceringen weergeven in de Gebruikersinterface van Databricks MLflow voor meer informatie over het gebruik van de gebruikersinterface voor traceringen.

Productiebewaking inschakelen

Als u productiebewaking wilt gebruiken met traceringen die zijn opgeslagen in Unity Catalog, moet u een SQL Warehouse-id voor het experiment configureren. Voor de bewakingstaak is deze configuratie vereist om scorerquery's uit te voeren op Unity Catalog-tabellen.

Stel de SQL Warehouse-id in met behulp van 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
)

U kunt ook de MLFLOW_TRACING_SQL_WAREHOUSE_ID omgevingsvariabele instellen voordat u begint met bewaken.

Als u deze stap overslaat, mislukken de bewakingstaken met een fout die aangeeft dat de mlflow.monitoring.sqlWarehouseId experimenttag ontbreekt.

Voor het configureren van bewaking voor Unity Catalog-traceringen hebt u de volgende machtigingen op werkruimteniveau nodig:

• CAN USE machtiging voor het SQL Warehouse
• CAN EDIT machtiging voor het MLflow-experiment
• Machtiging voor de bewakingstaak (automatisch verleend wanneer u de eerste scorer registreert)

De bewakingstaak wordt uitgevoerd onder de identiteit van de gebruiker die voor het eerst een scorer heeft geregistreerd bij het experiment. De machtigingen van deze gebruiker bepalen waartoe de bewakingstaak toegang heeft.

Beperkingen

• Traceringinvoer is in eerste instantie beperkt tot 200 traces per seconde per workspace en 100 MB per seconde per tabel. Neem contact op met uw Databricks-accountteam als u hogere limieten nodig hebt.

• Een experiment kan alleen worden gebonden aan een Unity Catalog-traceringslocatie tijdens het maken van het experiment.

• Traceringen die zijn opgeslagen in Unity Catalog, worden niet ondersteund met Knowledge Assistant of Supervisor Agent.

• Het verwijderen van afzonderlijke traceringen wordt niet ondersteund voor traceringen die zijn opgeslagen in Unity Catalog. Als u traceringen wilt verwijderen, moet u rijen rechtstreeks uit de onderliggende Unity Catalog-tabellen verwijderen met behulp van SQL. Dit verschilt van experimenttraceringen, die kunnen worden verwijderd met behulp van de MLflow-gebruikersinterface of API.

• MLflow MCP-server biedt geen ondersteuning voor interactie met traceringen die zijn opgeslagen in Unity Catalog.

• Traceringen kunnen nog niet worden geschreven naar een standaardopslagcatalogus .

• Traceringen kunnen nog niet worden geschreven naar de opslag die beveiligd wordt door Private Link.

Volgende stappen

• OpenTelemetry-traces opvragen die zijn opgeslagen in Unity Catalog
• Zoeken naar traceringen op OTel span-attributen: Zoek naar sporen van derden in Unity Catalog met behulp van OTel span-attributen.
• Traceringen migreren naar de nieuwste Unity Catalog tabelindeling: Traceringen migreren van de oudere schemas-gebonden indeling naar de tabelvoorvoegselindeling.