Armazene os rastros do OpenTelemetry no Unity Catalog

O Databricks recomenda armazenar rastreamentos do MLflow em tabelas do Unity Catalog para novas cargas de trabalho e cargas de trabalho de produção. Os rastreamentos são armazenados no formato OpenTelemetry (OTel) e vinculados a um experimento do MLflow, que permanece o ponto de entrada da UI para visualizá-los. Armazenar rastreamentos no Unity Catalog oferece as seguintes vantagens:

Armazene grandes volumes de rastreamentos em tabelas Delta para retenção e análise de longo prazo, sem limite de rastreamento por experimento.
O controle de acesso é gerenciado por meio do esquema Unity Catalog e das permissões de tabela, em vez de ACLs em nível de experimento. Usuários com acesso às tabelas Unity Catalog podem view todos os rastreamentos armazenados nessas tabelas, independentemente do experimento ao qual os rastreamentos pertencem.
Os rastreamentos são armazenados como tabelas Delta nativas de SQL, integrando-se a todo o lakehouse: query-os com SQL por meio de um Databricks SQL warehouse, crie painéis de AI/BI, faça perguntas em linguagem natural com o Genie Code, impulsione alertas e LakeFlow Pipelines, e processe-os com o Spark e o restante do ecossistema do lakehouse — indo muito além da execução de analítica e relatórios ad-hoc.
O formato OTel garante compatibilidade com outros clientes e ferramentas OpenTelemetry.

A tabela a seguir compara o armazenamento do Unity Catalog com o armazenamento de experimentos:

Capacidade	Rastreamentos armazenados no Unity Catalog	Rastreamentos armazenados em um experimento
Limite de armazenamento	Ilimitadas	100.000 rastreamentos por experimento
Opções de query	Interface do usuário do MLflow e Python SDK, além de SQL, Genie Code, AI/BI dashboards e qualquer ferramenta baseada em Spark	MLflow UI e Python SDK
Governança	Permissões de esquema e tabela do Unity Catalog	Controles de acesso em nível de experimento
Compatibilidade com o OpenTelemetry	Rastreamentos armazenados no formato OTel, compatíveis com outros clientes e ferramentas OTel	Não suportado

Capacidade	Rastreamentos armazenados no Unity Catalog	Rastreamentos armazenados em um experimento
Limite de armazenamento	Ilimitadas	100.000 rastreamentos por experimento
Opções de query	Interface do usuário do MLflow e Python SDK, além de SQL, Genie Code, AI/BI dashboards e qualquer ferramenta baseada em Spark	MLflow UI e Python SDK
Governança	Permissões de esquema e tabela do Unity Catalog	Controles de acesso em nível de experimento
Compatibilidade com o OpenTelemetry	Rastreamentos armazenados no formato OTel, compatíveis com outros clientes e ferramentas OTel	Não suportado

Requisitos

Um workspace compatível com o Catálogo Unity.
Um data warehouseDatabricks SQL com CAN USE permissões. Guarde o ID do armazém para referência futura.
Um workspace em uma região compatível. Veja recurso com disponibilidade regional limitada.
Versão da biblioteca Python do MLflow 3,14 ou posterior instalada em seu ambiente:
Bash
```
pip install mlflow[databricks]>=3.14.0 --upgrade --force-reinstall
```
Se você instalar ou atualizar o MLflow em um notebook em execução, desvincule e reconecte o notebook para reiniciar o processo do Python para que os pacotes atualizados sejam carregados. Se você ignorar isso, os pacotes carregados anteriormente permanecerão na memória e o código de configuração na próxima seção poderá falhar com um erro de importação, como cannot import name 'Sentinel' from 'typing_extensions'.
Permissões para criar o catálogo e o esquema usados para armazenar os rastreamentos no Unity Catalog.

nota

ALL_PRIVILEGES não é suficiente para tabelas de rastreamento do Unity Catalog. Conceda MODIFY e SELECT explicitamente.

Configuração: Crie um experimento com um local de rastreamento Unity Catalog

O catálogo e o esquema que armazena os rastreamentos devem existir antes de você criar o experimento. Vincular um experimento a um local de rastreamento do Unity Catalog não os cria. Se o esquema ainda não existir, crie-o primeiro. Você precisa de USE CATALOG no catálogo e CREATE SCHEMA nele.

SQL
CREATE SCHEMA IF NOT EXISTS <catalog_name>.<schema_name>;

Em seguida, execute o seguinte código para criar e vincular um experimento a um local de rastreamento do Unity Catalog:

Python
# 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 parâmetro trace_location . 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:

Python
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.
experiment = mlflow.set_experiment(experiment_id=experiment_id)

print(f"Experiment ID: {experiment.experiment_id}")
print(experiment.trace_location.full_otel_spans_table_name)

atenção

Se o esquema não existir quando você chamar create_experiment com trace_location, o MLflow criará o experimento, mas o link do local do rastreamento falhará e a chamada gerará um erro. O experimento permanece sem nenhum local de rastreamento vinculado a ele. Crie o esquema primeiro (consulte o passo acima), exclua o experimento restante e chame create_experiment novamente. set_experiment é uma operação de upsert; portanto, assim que o esquema existir, você poderá executá-lo novamente com o mesmo nome de experimento sem precisar de limpeza.

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

Verificar tabelas

Após executar o código de configuração, quatro novas tabelas do Unity Catalog 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 Databricks precisa dos seguintes privilégiosUnity Catalog para gravar ou ler rastreamentos MLflow nas tabelas Unity Catalog :

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

nota

ALL_PRIVILEGES Não é suficiente para acessar as tabelas de rastreamento Unity Catalog . Você deve conceder explicitamente as permissões MODIFY e SELECT .

Ao criar um aplicativo Databricks que grava rastreamentos, adicione essas tabelas como recursos do aplicativo para garantir que ele tenha os privilégios necessários. Para obter instruções de configuração, consulte Armazenar rastreamentos do MLflow no Unity Catalog.

rastreia logs nas tabelas Unity Catalog

Após criar as tabelas, você pode gravar rastreamentos nelas a partir de várias fontes, especificando o local do rastreamento. A forma de fazer isso depende da origem dos rastros.

MLflow SDK
Model Serving endpoint
Third-party OTel client

O local de rastreamento do Unity Catalog pode ser especificado usando a API Python 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)

Para gravar rastreamentos de um endpoint Databricks servindo modelo em tabelas Unity Catalog , você deve configurar um access token pessoal (PAT).

Conceda a um usuário ou entidade de serviço MODIFY e SELECT acesso às tabelas spans e annotations .
Certifique-se de que os rastreamentos sejam gravados usando as credenciais do usuário ou da entidade de serviço. Se você usar um PAT, defina a variável de ambiente DATABRICKS_TOKEN na variável de configuração do ambiente doDatabricks modelo endpoint. Se você usar OAuth em vez disso, defina a variável de ambiente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET .
A partir de um Notebook Databricks , e não do endpoint de serviço, crie um experimento com um local de rastreamento UC usando a API Python 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
)

Adicione o ID do experimento à configuração variável de ambiente do endpoint do modelo de atividade doDatabricks com MLFLOW_EXPERIMENT_ID como o nome da variável de ambiente.

Uma das vantagens de armazenar rastreamentos no formato OTel é a possibilidade de gravar nas tabelas Unity Catalog usando clientes de terceiros que suportam OTel. Os rastreamentos escritos dessa forma aparecem em um experimento MLflow vinculado à tabela, desde que possuam um intervalo raiz. O exemplo a seguir mostra os exportadores OTLP do OpenTelemetry.

Python
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={
        &quot;content-type&quot;: &quot;application/x-protobuf&quot;,
        &quot;X-Databricks-UC-Table-Name&quot;: &quot;&lt;catalog&gt;.&lt;schema&gt;.&lt;table_prefix&gt;_otel_spans&quot;,
        &quot;Authorization&quot;: &quot;Bearer MY_API_TOKEN&quot;
    },
)

See Export Langfuse traces to Databricks.

visualizar rastros na interface do usuário

Visualize os rastreamentos armazenados no formato OTel da mesma forma que você view outros rastreamentos:

Na sua área de trabalho, acesse Experimentos .
Encontre o experimento em que seus registros são logaritmos. Por exemplo, o experimento definido por mlflow.set_experiment("/Shared/my-genai-app-traces").
Clique na tab "Rastreamentos " para ver uma lista de todos os registros de rastreamento desse experimento.
Se você armazenou seus rastreamentos em uma tabela Unity Catalog, Databricks recupera os rastreamentos usando um SQL warehouse. Selecione um SQL warehouse no menu suspenso.

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

Armazenamento de experimentos (fallback)

O Unity Catalog é o repositório recomendado. Quando nenhum local de rastreamento do Unity Catalog é configurado, o MLflow recorre ao back-end gerenciado do experimento. Este back-end limita o armazenamento a 100.000 rastreamentos por experimento e pode não ser compatível com os recursos mais recentes do MLflow. Independentemente do back-end, um rastreamento sempre pertence a um experimento do MLflow, que é o ponto de entrada da interface do usuário para a visualização de rastreamentos.

Limitações

A ingestão de rastreamentos é inicialmente limitada a 200 rastreamentos por segundo por workspace e 100 MB por segundo por tabela. Entre em contato com a equipe da sua account Databricks se precisar de limites maiores.
Um experimento só pode ser vinculado a um local de rastreamento Unity Catalog no momento da criação do experimento.
Os rastros armazenados no Unity Catalog não são compatíveis com o Assistente de Conhecimento ou o Agente Supervisor.
A exclusão de rastreamentos individuais não é compatível com rastreamentos armazenados no Unity Catalog. Para remover os vestígios, você deve excluir linhas diretamente das tabelas subjacentes do Unity Catalog usando SQL. Isso difere dos rastros de experimentos, que podem ser excluídos usando a interface do usuário ou a API do MLflow.
Ainda não é possível gravar os registros em um catálogo de armazenamentodefault .
Ainda não é possível gravar dados em armazenamento protegido por Link Privado.
Habilitar o rastreamento em um endpoint de serviço pode reduzir a Taxa de transferência de serviço.

Recursos adicionais

Observe e encontre problemas
Pesquise rastreamentos por atributos de span OTel - Pesquise rastreamentos OTel de terceiros armazenados no Unity Catalog por atributos de span.
Migrar rastreamentos existentes para o Unity Catalog - Migre rastreamentos do formato mais antigo vinculado a esquemas para o formato de prefixo de tabela.
Migrar rastreamentos existentes para o Unity Catalog - Migre rastreamentos existentes para o Unity Catalog a partir de experimentos que não usam o armazenamento do Unity Catalog.

Próximo passo: Governar e redigir rastreamentos no Unity Catalog

Requisitos​

Configuração: Crie um experimento com um local de rastreamento Unity Catalog​

Verificar tabelas​

Conceder permissões​

rastreia logs nas tabelas Unity Catalog​

visualizar rastros na interface do usuário​

Armazenamento de experimentos (fallback)​

Limitações​

Recursos adicionais​