Almacenar trazas de OpenTelemetry en el Catálogo de Unity

Azure Databricks admite el almacenamiento de trazas de OpenTelemetry (OTel) en tablas de Unity Catalog. De forma predeterminada, MLflow almacena seguimientos organizados por experimentos en el servicio del plano de control de MLflow. Sin embargo, almacenar rastros en el catálogo de Unity mediante el formato OTel proporciona las siguientes ventajas:

• El control de acceso se administra a través del esquema del catálogo de Unity y los permisos de tabla en lugar de las ACL de nivel de experimento. Los usuarios con acceso a las tablas del catálogo de Unity pueden ver todos los seguimientos almacenados en esas tablas, independientemente del experimento al que pertenecen los seguimientos.
• Los identificadores de seguimiento usan el formato URI en lugar del tr-<UUID> formato, lo que mejora la compatibilidad con sistemas externos.
• Almacene grandes volúmenes de trazas en tablas Delta para retención a largo plazo y análisis.
• Consulte los datos de seguimiento directamente mediante SQL a través de una instancia de Databricks SQL Warehouse, lo que permite el análisis avanzado y los informes personalizados.
• El formato OTel garantiza la compatibilidad con otros clientes y herramientas de OpenTelemetry.

Prerrequisitos

• Un área de trabajo habilitada para el Catálogo de Unity.

• Asegúrese de que la versión preliminar "OpenTelemetry on Databricks" está habilitada, junto con "Desglose de Variantes para Desempeño de Lectura Optimizado en Datos Semiestructurados". Consulte Administrar versiones preliminares de Azure Databricks.

• Permisos para crear catálogos y esquemas en el catálogo de Unity.

• Una instancia de Databricks SQL Warehouse con CAN USE permisos. Guarde el identificador de almacenamiento para una referencia posterior.

• Un espacio de trabajo en una región compatible. Consulte Características con disponibilidad regional limitada.

• Biblioteca de Python de MLflow versión 3.11 o posterior instalada en su entorno:

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

Configuración: Creación de un experimento con una ubicación de seguimiento del catálogo de Unity

Ejecute el código siguiente para crear y enlazar un experimento a una ubicación de seguimiento del catálogo de 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)

También puede usar mlflow.create_experiment con el mismo trace_location parámetro. A diferencia de set_experiment, create_experiment no establece el experimento activo, así que debe llamar a set_experiment después para asegurarse de que las trazas se enrutan a la ubicación correcta.

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)

Una vez enlazado un experimento a una ubicación de seguimiento de UC, no se puede reasignar el experimento a otra ubicación de seguimiento de UC. Sin embargo, varios experimentos pueden compartir la misma ubicación de seguimiento de UC.

Comprobación de tablas

Después de ejecutar el código de instalación, aparecen cuatro nuevas tablas de Catálogo de Unity en el esquema de la interfaz de usuario del Explorador de catálogos:

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

Concesión de permisos

Un usuario o entidad de servicio de Databricks necesita los siguientes privilegios del Catálogo Unity para escribir o leer registros de MLflow desde las tablas del Catálogo Unity.

1. USE_CATALOG en el catálogo.
2. USE_SCHEMA en el esquema.
3. MODIFY y SELECT en cada una de las <table_prefix>_<type> tablas.

Trazas de registros en las tablas del Unity Catalog

Después de crear las tablas, puede escribir trazas en ellas desde varios orígenes especificando la ubicación de las trazas. La forma de hacerlo depende del origen de los rastros.

MLflow SDK

La ubicación de seguimiento del catálogo de Unity se puede especificar mediante la API de 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)

Modelo de puntos de conexión de servicio

Para escribir registros desde un modelo de servicio de Azure Databricks a las tablas de Unity Catalog, debe configurar un token de acceso personal (PAT).

1. Conceda a un usuario o entidad de servicio MODIFY y SELECT acceso a las tablas spans y annotations.
2. Asegúrese de que los seguimientos sean escritos utilizando las credenciales del usuario o del principal de servicio. Si usa un PAT, establezca la DATABRICKS_TOKEN variable de entorno en la configuración de variables de entorno del modelo de Databricks que atiende a las variables de entorno del punto de conexión. Si usa OAuth en su lugar, establezca las DATABRICKS_CLIENT_ID variables de entorno y DATABRICKS_CLIENT_SECRET .
3. Desde un cuaderno de Databricks, no desde el punto de conexión de servicio, cree un experimento con una ubicación de seguimiento de UC mediante la API de 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. Agregue el identificador del experimento al modelo de Databricks que atiende la configuración de variables de entorno del punto de conexión con MLFLOW_EXPERIMENT_ID como nombre de la variable de entorno.

Cliente de OTel de terceros

Una ventaja de almacenar trazas en formato OTel es que puede escribir en las tablas del Catálogo de Unity mediante clientes de terceros que admiten OTel. Las trazas escritas de esta manera aparecen en un experimento de MLflow vinculado a la tabla, siempre que tengan un span de raíz. En el ejemplo siguiente se muestran los exportadores de OTLP de 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"
    },
)

Consulte exportar seguimientos de Langfuse a Azure Databricks MLflow.

Ver trazas en la interfaz de usuario

Vea los seguimientos almacenados en formato OTel de la misma manera que ve otros seguimientos:

1. En el área de trabajo, vaya a Experimentos.

2. Busque el experimento donde se registran tus trazas. Por ejemplo, el experimento diseñado por mlflow.set_experiment("/Shared/my-genai-app-traces").

3. Haga clic en la pestaña Seguimientos para ver una lista de todos los seguimientos registrados en ese experimento.

   

4. Si guardaste tus trazas en una tabla de Unity Catalog, Azure Databricks recupera trazas mediante un almacén de datos SQL. Seleccione una instancia de SQL Warehouse en el menú desplegable.

Para obtener más información sobre el uso de la interfaz de usuario para buscar seguimientos: consulte Ver seguimientos en la interfaz de usuario de Databricks MLflow.

Habilitación de la supervisión de producción

Para usar la supervisión de producción con seguimientos almacenados en el catálogo de Unity, debe configurar un identificador de SQL Warehouse para el experimento. El trabajo de supervisión requiere esta configuración para ejecutar consultas de valoración en tablas del catálogo de Unity.

Establezca el identificador de SQL Warehouse mediante 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
)

Como alternativa, puede establecer la variable de entorno antes de iniciar la MLFLOW_TRACING_SQL_WAREHOUSE_ID supervisión.

Si omite este paso, los trabajos de supervisión producirán un error que indica que falta la etiqueta del experimento mlflow.monitoring.sqlWarehouseId.

Para configurar la monitorización de trazas en el Unity Catalog, necesita los siguientes permisos a nivel de espacio de trabajo:

• CAN USE permiso en SQL Warehouse
• CAN EDIT permisos del experimento de MLflow
• Permiso para el trabajo de monitoreo (concedido automáticamente al registrar el primer puntuador)

El trabajo de supervisión se ejecuta bajo la identidad del usuario que registró por primera vez un puntuador en el experimento. Los permisos de este usuario determinan a qué puede acceder el trabajo de supervisión.

Limitaciones

• La ingestión de trazas se limita inicialmente a 200 trazas por segundo por espacio de trabajo y 100 MB por segundo por tabla. Si necesita límites más altos, póngase en contacto con el equipo de la cuenta de Databricks.

• Un experimento solo se puede enlazar a una ubicación de seguimiento del catálogo de Unity en el momento de la creación del experimento.

• Los seguimientos almacenados en el Unity Catalog no se admiten con Knowledge Assistant ni Supervisor Agent.

• No se permite eliminar rastros individuales para los rastros almacenados en el catálogo de Unity. Para quitar trazas, debe eliminar filas directamente de las tablas subyacentes del catálogo de Unity mediante SQL. Esto difiere de los seguimientos del experimento, que se pueden eliminar mediante la interfaz de usuario o la API de MLflow.

• El servidor MCP de MLflow no admite la interacción con seguimientos almacenados en el catálogo de Unity.

• Todavía no se pueden escribir rastros en el catálogo de almacenamiento predeterminado.

• Todavía no se pueden escribir seguimientos en el almacenamiento protegido por Private Link.

Pasos siguientes

• Consultar las trazas de OpenTelemetry almacenadas en el catálogo de Unity
• Buscar rastros por atributos de span de OTel: busque rastros de OTel de terceros almacenados en el Catálogo de Unity por atributos de span.
• Migrar trazas al formato de tabla del catálogo de Unity más reciente: Migrar trazas del formato vinculado al esquema anterior al formato de prefijo de tabla.