Armazene os rastreios OpenTelemetry no Catálogo Unity

O Azure Databricks suporta o armazenamento de traços OpenTelemetry (OTel) em tabelas do Unity Catalog. Por defeito, o MLflow armazena registos organizados por experiências no serviço de plano de controlo do MLflow. No entanto, armazenar traços no Unity Catalog usando o formato OTel oferece os seguintes benefícios:

• O controlo de acesso é gerido através de permissões de esquemas e tabelas do Unity Catalog, em vez de ACLs a nível experimental. Os utilizadores com acesso às tabelas do Catálogo Unity podem visualizar todos os traços armazenados nessas tabelas, independentemente do experimento a que pertençam.
• Os IDs de traço utilizam o formato URI em vez do tr-<UUID> formato, melhorando a compatibilidade com sistemas externos.
• Armazene grandes volumes de traços em tabelas Delta para retenção e análise a longo prazo.
• Consulta os dados de rastreio diretamente usando SQL através de um Databricks SQL warehouse, permitindo análises avançadas e relatórios personalizados.
• O formato OTel assegura compatibilidade com outros clientes e ferramentas OpenTelemetry.

Pré-requisitos

• Um espaço de trabalho com Unity Catalog.

• Certifique-se de que a pré-visualização "OpenTelemetry on Databricks" está ativada, juntamente com "Variant Shredding for Optimized Read Performance on Semi-Structured Data." Ver Gerir Azure Databricks pré-visualizações.

• Permissões para criar catálogos e esquemas no Unity Catalog.

• Um armazém SQL Databricks com CAN USE permissões. Guarde o ID do armazém para referência posterior.

• Um espaço de trabalho numa região suportada. Veja Funcionalidades com disponibilidade regional limitada.

• Biblioteca MLflow Python versão 3.11 ou posterior instalada no seu ambiente.

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

Configuração: Criar um experimento com uma localização de rastreio no Unity Catalog

Execute o seguinte código para criar e vincular um experimento a uma localização de traço do 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)

Também podes usar mlflow.create_experiment com o mesmo trace_location parâmetro. Ao contrário de set_experiment, create_experiment não define o experimento ativo, por isso deve ligar set_experiment depois para garantir que os traços são encaminhados para o local correto:

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)

Uma vez que ligas um experimento a um local de traço UC, não podes reatribuir o experimento a outro local de traço UC. No entanto, múltiplos experimentos podem partilhar a mesma localização de traço UC.

Verificar tabelas

Após executar o código de configuração, quatro novas tabelas do Catálogo Unity aparecem no esquema da interface do Explorador de Catálogo:

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

Conceder permissões

Um utilizador ou entidade de serviço do Databricks necessita dos seguintes privilégios do Unity Catalog para escrever ou ler registos de MLflow a partir das tabelas do Unity Catalog.

1. USE_CATALOG no catálogo.
2. USE_SCHEMA no esquema.
3. MODIFY e SELECT em cada uma das <table_prefix>_<type> tabelas.

Traços de registo para as tabelas do Catálogo Unity

Depois de criar as tabelas, pode escrever traços nelas a partir de várias fontes, especificando a localização do traço. A forma como fazes isto depende da origem dos vestígios.

MLflow SDK

A localização do rastreio do Unity Catalog pode ser especificada usando a 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 de serviço do modelo

Para escrever traços a partir de um modelo Azure Databricks que serve endpoint para tabelas do Unity Catalog, deve configurar um token de acesso pessoal (PAT).

1. Conceda a um utilizador ou principal de serviço MODIFY e SELECT acesso às tabelas spans e annotations.
2. Certifique-se de que as pistas são escritas usando as credenciais do utilizador ou do principal do serviço. Se usares um PAT, define a DATABRICKS_TOKEN variável de ambiente no modelo Databricks que serve a configuração das variáveis de ambiente do endpoint. Se usares OAuth em vez disso, define as variáveis de ambiente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET.
3. A partir de um caderno Databricks, e não dentro do endpoint de serviço, crie um experimento com uma localização de rastreio UC usando a 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. Adicione o ID do experimento ao modelo Databricks que serve a configuração das variáveis de ambiente do endpoint com MLFLOW_EXPERIMENT_ID como nome da variável de ambiente.

Cliente OTel de terceiros

Uma vantagem de armazenar traços no formato OTel é que pode escrever nas tabelas do Unity Catalog usando clientes de terceiros que suportam OTel. Trilhas escritas desta forma aparecem numa experiência MLflow ligada à tabela desde que tenham um alcance de raiz. O exemplo seguinte mostra exportadores OTLP da 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"
    },
)

Veja Exportar traços Langfuse para Azure Databricks MLflow.

Visualizar trilhos na interface

Veja os rastreios armazenados no formato OTel da mesma forma que vê outros rastreios:

1. No teu Espaço de Trabalho, vai a Experiências.

2. Encontra o experimento onde os teus rastros são registados. Por exemplo, o experimento definido por mlflow.set_experiment("/Shared/my-genai-app-traces").

3. Clique no separador Traces para ver uma lista de todos os traços registados nesse experimento.

   

4. Se armazenou os seus traços numa tabela do Unity Catalog, o Azure Databricks recupera os traços usando um armazém SQL. Selecione um SQL warehouse no menu suspenso.

Para mais informações sobre como usar a interface de utilizador para procurar traços, veja Visualizar traços na interface MLflow do Databricks.

Ativar a monitorização da produção

Para usar monitorização de produção com rastros armazenados no Unity Catalog, deve configurar um ID de armazém SQL para o experimento. O trabalho de monitorização requer que esta configuração execute consultas de pontuação contra tabelas do Catálogo Unity.

Defina o ID do 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
)

Alternativamente, podes definir a MLFLOW_TRACING_SQL_WAREHOUSE_ID variável ambiente antes de começares a monitorizar.

Se saltar este passo, os trabalhos de monitorização falham com um erro que indica que a mlflow.monitoring.sqlWarehouseId etiqueta do experimento está em falta.

Para configurar a monitorização dos traços do Unity Catalog, precisa das seguintes permissões ao nível do espaço de trabalho:

• CAN USE permissão no armazém SQL
• CAN EDIT permissão no experimento MLflow
• Permissão para o trabalho de monitorização (concedida automaticamente quando registas o primeiro pontuador)

O trabalho de monitorização é executado sob a identidade do utilizador que foi o primeiro a registar um pontuador na experiência. As permissões deste utilizador determinam o que o trabalho de monitorização pode aceder.

Limitações

• A ingestão de traços é inicialmente limitada a 200 traços por segundo por espaço de trabalho e 100 MB por segundo por tabela. Contacte a equipa da sua conta Databricks se precisar de limites mais elevados.

• Um experimento só pode ser associado a um local de rastreamento do Unity Catalog no momento da criação do experimento.

• Os traços armazenados no Unity Catalog não são suportados pelo Knowledge Assistant ou pelo Supervisor Agent.

• A eliminação de registos individuais não é possível para registos armazenados no Unity Catalog. Para remover vestígios, deve eliminar linhas diretamente das tabelas subjacentes do Unity Catalog usando SQL. Isto difere dos vestígios experimentais, que podem ser eliminados usando a interface ou API do MLflow.

• O servidor MCP do MLflow não suporta interação com traços armazenados no Unity Catalog.

• Os traços ainda não podem ser escritos num catálogo de armazenamento predefinido .

• Os logs ainda não podem ser gravados no armazenamento protegido pelo Private Link.

Próximos passos

• Consultar os traços OpenTelemetry armazenados no Unity Catalog
• Procure traços por atributos de span OTel: Procure traços OTel de terceiros armazenados no Unity Catalog por atributos de span.
• Migrar registos para o formato de tabela mais recente do Unity Catalog: Migrar registos do formato antigo vinculado ao esquema para o formato de prefixo de tabela.