Armazenar rastreamentos OpenTelemetry no Catálogo do Unity

Azure Databricks dá suporte ao armazenamento de rastreamentos do OTel (OpenTelemetry) em tabelas do Unity Catalog. Por padrão, o MLflow armazena rastreamentos organizados por experimentos no serviço do plano de controle MLflow. No entanto, armazenar rastreamentos no Catálogo do Unity usando o formato OTel oferece os seguintes benefícios:

• O controle de acesso é gerenciado por meio de permissões de esquema e tabela no Unity Catalog, em vez de ACLs de nível de experimento. Os usuários com acesso às tabelas do Catálogo do Unity podem exibir todos os rastreamentos armazenados nessas tabelas, independentemente de quais experimentos os rastreamentos pertencem.
• As IDs de rastreamento usam o formato URI em vez do tr-<UUID> formato, melhorando a compatibilidade com sistemas externos.
• Armazene grandes volumes de rastros em tabelas Delta para retenção e análise de longo prazo.
• Consultar dados de rastreamento diretamente usando o SQL por meio de um databricks SQL Warehouse, habilitando análise avançada e relatórios personalizados.
• O formato OTel garante a compatibilidade com outros clientes e ferramentas do OpenTelemetry.

Pré-requisitos

• Um workspace habilitado para Catálogo do Unity.

• Certifique-se de que a pré-visualização "OpenTelemetry no Databricks" esteja ativada, juntamente com "Desmembramento de Variantes para Desempenho de Leitura Otimizado em Dados Semiestruturados". Consulte Gerenciar pré-visualizações do Azure Databricks.

• Permissões para criar catálogos e esquemas no Catálogo do Unity.

• Um Databricks SQL Warehouse com CAN USE permissões. Salve a ID do warehouse para referência posterior.

• Um workspace em uma região com suporte. Consulte Recursos com disponibilidade regional limitada.

• A biblioteca Python MLflow versão 3.11 ou posterior instalada em seu ambiente:

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

Configuração: criar um experimento com um local de rastreamento do Catálogo do Unity

Execute o seguinte código para criar e associar um experimento a um local de rastreamento do Catálogo do 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)

Você também pode 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, portanto, você deve chamar set_experiment posteriormente para garantir que os rastreamentos sejam roteados 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)

Depois de associar um experimento a um local de rastreamento de UC, você não poderá reatribuir o experimento a um local de rastreamento de UC diferente. No entanto, vários experimentos podem compartilhar o mesmo local de rastreamento da UC.

Verificar tabelas

Depois de executar o código de instalação, quatro novas tabelas do Catálogo do Unity aparecem no esquema na interface do usuário do Catalog Explorer:

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

Conceder permissões

Um usuário ou entidade de serviço do Databricks precisa dos seguintes privilégios do Catálogo do Unity para gravar ou ler dados de rastreamento do MLflow das tabelas do Catálogo do Unity.

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

Registros de log nas tabelas do Catálogo Unity

Depois de criar as tabelas, você pode gravar rastreamentos nelas de várias fontes especificando o local de rastreamento. Como você faz isso depende da origem dos traços.

MLflow SDK

O local de rastreamento do Catálogo do Unity pode ser especificado 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)

Ponto de Extremidade do Serviço de Modelo

Para gravar rastreamentos de um modelo de Azure Databricks servindo ponto de extremidade para tabelas do Catálogo do Unity, você deve configurar um PAT (token de acesso pessoal).

1. Conceda a um usuário ou a uma entidade de serviço MODIFY e SELECT acesso às tabelas spans e annotations.
2. Verifique se os rastreamentos são gravados usando as credenciais do usuário ou do principal de serviço. Se você usar um PAT, defina a DATABRICKS_TOKEN variável de ambiente no modelo do Databricks que atende à configuração de variáveis de ambiente do ponto de extremidade. Se você usar OAuth em vez disso, defina as variáveis de ambiente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET.
3. Em um notebook do Databricks, não de dentro do endpoint de serviço, crie um experimento com um UC trace location 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 à configuração das variáveis de ambiente do ponto de extremidade de serviço de modelo do Databricks, usando MLFLOW_EXPERIMENT_ID como o nome da variável de ambiente.

Cliente OTel de terceiros

Um benefício de armazenar rastreamentos no formato OTel é que você pode gravar nas tabelas do Catálogo do Unity usando clientes de terceiros que dão suporte ao OTel. Os rastros gravados dessa forma aparecem em um experimento do MLflow vinculado à tabela, desde que tenham um span raiz. O exemplo a seguir mostra OpenTelemetry OTLP Exportadores.

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 Langfuse rastros para Azure Databricks MLflow.

Exibir rastreamentos na interface do usuário

Exibir rastreamentos armazenados no formato OTel da mesma forma que você exibe outros rastreamentos:

1. Em seu Workspace, vá para Experimentos.

2. Localize o experimento no qual os rastreamentos são registrados. Por exemplo, o experimento definido por mlflow.set_experiment("/Shared/my-genai-app-traces").

3. Clique na guia Rastreamentos para ver uma lista de todos os rastreamentos registrados nesse experimento.

   

4. Se você armazenou seus rastros em uma tabela do Unity Catalog, o Azure Databricks recuperará os rastros usando um SQL warehouse. Selecione um armazenamento de dados SQL no menu suspenso.

Para obter mais informações sobre como usar a interface do usuário para pesquisar rastreamentos, consulte Exibir rastreamentos na interface do usuário do Databricks MLflow.

Habilitar o monitoramento de produção

Para usar o monitoramento de produção com rastreamentos armazenados no Catálogo do Unity, você deve configurar uma ID do SQL Warehouse para o experimento. O trabalho de monitoramento requer essa configuração para executar consultas de pontuação nas tabelas do Unity Catalog.

Defina a 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
)

Como alternativa, você pode definir a variável de ambiente antes de iniciar o MLFLOW_TRACING_SQL_WAREHOUSE_ID monitoramento.

Se você ignorar essa etapa, os trabalhos de monitoramento falharão com um erro indicando que a tag do experimento mlflow.monitoring.sqlWarehouseId está ausente.

Para configurar o monitoramento para rastreamentos do Catálogo do Unity, você precisa das seguintes permissões no nível do workspace:

• CAN USE permissão no SQL Warehouse
• CAN EDIT permissão no experimento do MLflow
• Permissão para o trabalho de monitoramento (concedida automaticamente quando você registra o primeiro avaliador)

O trabalho de monitoramento é executado sob a identidade do usuário que registrou pela primeira vez um marcador no experimento. As permissões desse usuário determinam o que o trabalho de monitoramento pode acessar.

Limitações

• Inicialmente, a ingestão de traces é limitada a 200 rastreamentos por segundo para cada workspace e 100 MB por segundo para cada tabela. Entre em contato com sua equipe de conta do Databricks se precisar de limites mais altos.

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

• Não há suporte para rastreamentos armazenados no Catálogo do Unity com o Knowledge Assistant ou o Supervisor Agent.

• Não é suportada a remoção de traços individuais para traços armazenados no Catálogo do Unity. Para remover rastreamentos, você deve excluir linhas diretamente das tabelas subjacentes do Catálogo do Unity usando SQL. Isso difere dos rastreamentos de experimento, que podem ser excluídos usando a interface do usuário ou a API do MLflow.

• O servidor MCP do MLflow não dá suporte à interação com rastreamentos armazenados no Catálogo do Unity.

• Os rastros ainda não podem ser gravados em um catálogo de armazenamento padrão.

• Os rastreamentos ainda não podem ser gravados no armazenamento protegido por Link Privado.

Próximas etapas

• Consultar rastreamentos OpenTelemetry armazenados no Catálogo do Unity
• Pesquisar rastreamentos por atributos de span OTel: pesquisar rastreamentos OTel de terceiros armazenados no Catálogo do Unity por atributos de span.
• Migrar rastreamentos para o formato de tabela mais recente do Catálogo do Unity: migre rastreamentos do formato vinculado ao esquema mais antigo para o formato de prefixo de tabela.