Monitore toda a atividade de AI usando a tabela de rastreamento unificada

info

Beta

A tabela de rastreamento unificada está em Beta. O Unity Gateway está disponível de forma geral, mas seus recursos beta são habilitados separadamente. Um administrador da conta deve ativar os recursos beta do Enhanced Unity Gateway na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.

A tabela de rastreamento unificada oferece um único local para monitorar, depurar, proteger e auditar todas as atividades em seus serviços do Unity Gateway.

Um administrador do metastore configura o rastreamento unificado uma vez. Depois disso, todo o tráfego do Unity Gateway é registrado automaticamente sem necessidade de configuração por endpoint.

importante

By default, apenas o administrador do metastore que cria a tabela de rastreamento pode lê-la. Nenhum outro usuário — incluindo proprietários de endpoint e equipes de segurança — pode query a tabela até que o proprietário conceda acesso explicitamente via Unity Catalog. Consulte Permissões e controle de acesso.

Requisitos

• Prévia do Enhanced Unity Gateway habilitada para sua account. Consulte Gerenciar prévias do Databricks.
• Unity Catalog ativado para seu Workspace.
• Zerobus Ingest disponível para o seu workspace. A tabela unificada de rastreamentos grava spans no Unity Catalog por meio do Zerobus Ingest. Para ver as regiões compatíveis, consulte Disponibilidade de ingestão.
• Função de administrador do Metastore para configurar o rastreamento unificado.
• CREATE TABLE, USE CATALOG e USE SCHEMA permissões no catálogo e esquema do Unity Catalog de destino.
• Para query a tabela: privilégio SELECT na tabela de rastreamento. Por default, apenas o administrador do metastore pode query. Para conceder acesso a outras pessoas, consulte Permissões e controle de acesso.

Para usar um catálogo respaldado pelo armazenamento default, um administrador do workspace também deve habilitar Zerobus Ingest Default Storage em Configurações > Pré-lançamentos . Consulte Gerenciar prévias do Databricks.

O que é uma tabela de rastreamento unificada?

A tabela de rastreamento unificada captura todas as solicitações e respostas em todos os serviços do Unity Gateway em uma única tabela do Unity Catalog no formato OpenTelemetry ("OTel"). Ele oferece três vantagens em relação às tabelas de inferência:

• Concluído. Toda a atividade em cada serviço é centralizada em um único local, sem a necessidade de configuração por endpoint.
• Aplicável. Um administrador de metastore cria a tabela uma vez, e o registro é aplicado em todos os serviços sem pontos cegos de serviços que tenham o registro desativado.
• Abrir. Criado com base no padrão OpenTelemetry, para que qualquer ferramenta possa consumir os dados diretamente sem pós-processamento personalizado.

Usos comuns:

• Depuração: filtre por trace_id para reproduzir cada o passo de uma execução de agente com falha. Filtre por service_name e status.code para encontrar todos os erros em um endpoint específico.
• Analítica para uso de IA: Use funções de IA para analisar interações com LLMs (incluindo assistentes de codificação) para capturar padrões entre chamadores e entender o valor que a IA fornece em sua organização.
• Reduza o uso de tokens: Use funções de AI para analisar padrões de erro comuns em chamadas para LLMs ou MCPs e entender como melhorar a eficácia de agentes e assistentes de codificação.
• Segurança e compliance: cada span registra a identidade do solicitante, o nome do endpoint e o payload completo da solicitação, para que você possa inseri-los em suas ferramentas de segurança para detecção e investigação de ameaças.
• Auditabilidade: Analise a atividade da IA para um usuário, endpoint ou intervalo de tempo.

nota

A entrega de rastreamento é de melhor esforço (consulte Limitações), portanto, a tabela de rastreamento unificada complementa, em vez de substituir, os logs de auditoria do Databricks. Continue a usar os logs de auditoria como o sistema de registro para compliance.

Tabela de rastreamento unificada vs. tabelas de inferência

A tabela de rastreamento unificada é a abordagem recomendada para novas implantações. As tabelas de inferência permanecem disponíveis, mas são projetadas apenas para monitoramento de solicitação/resposta de um único endpoint de serviço de modelo. Para mais informações sobre tabelas de inferência, consulte Registrar solicitações e respostas para tabelas de inferência.

	Tabela de rastreamento unificada	Tabelas de inferência
Escopo	Todos os serviços de modelo e serviços MCP do Unity Gateway, em uma única tabela	Por Endpoint de servindo modelo, uma tabela cada
Configuração	Configuração única pelo administrador do metastore; aplica-se a todos os serviços em todos os workspaces anexados ao metastore	Deve ser habilitado por Endpoint
Esquema	Spans do OpenTelemetry	Específico do Databricks (requer pós-processamento)
Fluxos de trabalho autônomos	Todos os saltos caem em uma única tabela; IDs de rastreamento compartilhados para reconstruir um rastreamento completo de vários saltos estarão disponíveis em breve	Fragmentado entre tabelas por endpoint
Compatibilidade do MLflow	Os spans usam um esquema OTel compatível com MLflow que as ferramentas do MLflow podem ler diretamente	Requer extração manual de rastreamento
Proprietário	Administrador do metastore que cria a tabela	Proprietário do endpoint
Controle de acesso	default: apenas administradores de metastore. Conceda acesso a outros com permissões do Unity Catalog e políticas de filtro de linha ABAC	ACLs do Unity Catalog separadas por endpoint

	Tabela de rastreamento unificada	Tabelas de inferência
Escopo	Todos os serviços de modelo e serviços MCP do Unity Gateway, em uma única tabela	Por Endpoint de servindo modelo, uma tabela cada
Configuração	Configuração única pelo administrador do metastore; aplica-se a todos os serviços em todos os workspaces anexados ao metastore	Deve ser habilitado por Endpoint
Esquema	Spans do OpenTelemetry	Específico do Databricks (requer pós-processamento)
Fluxos de trabalho autônomos	Todos os saltos caem em uma única tabela; IDs de rastreamento compartilhados para reconstruir um rastreamento completo de vários saltos estarão disponíveis em breve	Fragmentado entre tabelas por endpoint
Compatibilidade do MLflow	Os spans usam um esquema OTel compatível com MLflow que as ferramentas do MLflow podem ler diretamente	Requer extração manual de rastreamento
Proprietário	Administrador do metastore que cria a tabela	Proprietário do endpoint
Controle de acesso	default: apenas administradores de metastore. Conceda acesso a outros com permissões do Unity Catalog e políticas de filtro de linha ABAC	ACLs do Unity Catalog separadas por endpoint

Habilitar a tabela de rastreamento unificada

Esta é uma operação única realizada por um administrador do metastore. A tabela reside em um caminho do Unity Catalog que você escolher (por exemplo, <catalog>.<schema>.unity_gateway_otel_spans).

dica

Armazene a tabela de rastreamento em um catálogo ou esquema dedicado. O isolamento evita que permissões de outros catálogos ou esquemas exponham dados de rastreamento não intencionalmente. O administrador do metastore que cria a tabela torna-se seu proprietário e controla quem pode acessá-la. Para conceder acesso de query a outros usuários, recomendamos configurar o ABAC conforme documentado em Permissões e controle de acesso.

1. Na barra lateral do Workspace, clique em AI Gateway .
2. Clique em Govern > Traces > Set up tracing .
3. Selecione o catálogo e o esquema onde a tabela de rastreamento será criada.
4. Clique em Salvar para criar a tabela de rastreamento.

Consumir a tabela de rastreamento unificada

importante

default, apenas o administrador do metastore pode query a tabela de rastreamento. Antes de compartilhá-la, configure uma política de filtro de linha ABAC para que cada usuário veja apenas os rastreamentos que deveria. Consulte Permissões e controle de acesso abaixo.

Visualizar rastreamentos na IU

1. Na barra lateral do workspace, clique em AI Gateway > Govern > tab Traces .

A view Traces fornece os seguintes controles:

• Pesquisar: pesquisa de texto completo em todo o conteúdo na tela atual.
• Intervalo de tempo: filtre rastreamentos por janela de tempo (default: últimas 24 horas).
• Filtros: Filtrar por Serviço (nome do endpoint), Principal (solicitante), Tipo de serviço , Estado ou Tempo de execução .
• Colunas: Mostrar ou ocultar colunas.
• Warehouse: selecione o SQL warehouse usado para executar queries na tabela de rastreamento.

Escreva queries com o Genie Code

O Genie Code está disponível em todo o workspace. Abra o Genie Code na barra lateral e peça para ele escrever queries SQL na sua tabela de rastreamento. O Genie Code entende automaticamente os esquemas de tabela do Unity Catalog.

Exemplos de prompts:

• "Mostre-me todos os erros de limite de taxa no endpoint customer-support-bot nas últimas 24 horas"
• "Quais usuários tiveram os maiores tempos de resposta p99 na semana passada?"
• "Encontrar todos os rastros em que o agente fez mais de três chamadas downstream"

O Genie Code gera o SQL, que você pode executar diretamente em um notebook ou no editor SQL.

query com SQL ou um notebook

A tabela é colocada em clusters por time. Inclua esta coluna em sua cláusula WHERE para obter o melhor desempenho.

Substitua <catalog>.<schema>.<table_name> pelo caminho da sua tabela de rastreamento.

SQL

-- All spans for a specific trace
SELECT * FROM <catalog>.<schema>.<table_name>
WHERE trace_id = 'afdd29f3a069482f8b102380ba0fb3c8'
ORDER BY start_time_unix_nano;

-- All errors on a specific endpoint in the last 24 hours
SELECT trace_id, name, status, attributes
FROM <catalog>.<schema>.<table_name>
WHERE service_name = '<catalog>.<schema>.<model>'
  AND status.code = 'STATUS_CODE_ERROR'
  AND time >= current_timestamp() - INTERVAL 1 DAY;

-- Root spans only (one row per request), with requester and HTTP status
SELECT trace_id, name,
  attributes:`enduser.id`::string AS requester
  attributes:`http.response.status_code`::int AS status_code,
  status.code
FROM <catalog>.<schema>.<table_name>
WHERE parent_span_id IS NULL
  AND service_name = '<catalog>.<schema>.<model>';

Enviar rastreamentos do lado do cliente do seu aplicativo

Seus aplicativos podem enviar spans de OpenTelemetry do lado do cliente para o Unity Gateway por meio de seu endpoint de ingestão OTLP, a partir de qualquer SDK do OpenTelemetry. O SDK do Claude também tem suporte integrado para rastrear suas solicitações de API. Os spans do aplicativo chegam na mesma tabela de rastreamento unificada que os spans da solicitação do gateway (<catalog>.<schema>.<table_name>, escolhido na configuração), para que você monitore o que seu aplicativo fez e o que o gateway serviu em um só lugar.

info

Beta

A ingestão de span do lado do cliente está em Beta e é habilitada por workspace. Para habilitá-lo em seu workspace, entre em contato com sua equipe de account Databricks.

Requisitos

• A tabela de rastreamento unificada está configurada para o seu workspace. Consulte Habilitar a tabela de rastreamento unificada.
• A ingestão de span do lado do cliente está habilitada para seu workspace.
• Um token do Databricks, por exemplo, um access token pessoal. Os spans ingeridos são atribuídos ao principal dos tokens. Os atributos de identidade no payload, como enduser.id, são ignorados.
• O principal do token tem acesso ao workspace. As solicitações são rejeitadas caso contrário.

Enviar spans com um OpenTelemetry SDK

Aponte um exportador OTLP para https://<workspace-url>/ai-gateway/otel/v1/traces. O endpoint aceita OTLP sobre HTTP apenas com codificação protobuf binária (http/protobuf). JSON e gRPC não são suportados. Envie o payload não compactado: não habilite a compactação no exportador (por exemplo, deixe OTEL_EXPORTER_OTLP_COMPRESSION não definido).

Os exemplos a seguir enviam spans de qualquer aplicativo:

Python

1. Instale o SDK do OpenTelemetry e os pacotes de exportação OTLP: opentelemetry-sdk e opentelemetry-exporter-otlp-proto-http.

2. Faça o registro de um provedor de rastreador com um exportador de span OTLP apontado para o Endpoint de ingestão:

   Python

   import os
   
   from opentelemetry import trace
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   from opentelemetry.sdk.resources import Resource
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   
   DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')
   
   # service.name becomes the service_name of these spans in the trace table.
   provider = TracerProvider(
       resource=Resource.create({"service.name": "<your-application-name>"})
   )
   exporter = OTLPSpanExporter(
       endpoint="https://<workspace-url>/ai-gateway/otel/v1/traces",
       headers={"Authorization": f"Bearer {DATABRICKS_TOKEN}"},
   )
   provider.add_span_processor(BatchSpanProcessor(exporter))
   trace.set_tracer_provider(provider)

3. Crie spans no código do seu aplicativo:

   Python

   tracer = trace.get_tracer(__name__)
   
   with tracer.start_as_current_span(""):
       # Your application code
       ...

BatchSpanProcessor exporta spans de forma assíncrona. Em scripts de curta duração, chame provider.shutdown() (ou provider.force_flush()) antes que o processo termine para que os spans em buffer sejam enviados.

TypeScript

1. Instale os pacotes do SDK OpenTelemetry e do exportador OTLP: npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources.

2. Faça o registro de um provedor de rastreador com um exportador de span OTLP apontado para o Endpoint de ingestão:

   TypeScript

   import { trace } from '@opentelemetry/api';
   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
   import { resourceFromAttributes } from '@opentelemetry/resources';
   import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
   
   // service.name becomes the service_name of these spans in the trace table.
   const provider = new NodeTracerProvider({
     resource: resourceFromAttributes({ 'service.name': '<your-application-name>' }),
     spanProcessors: [
       new BatchSpanProcessor(
         new OTLPTraceExporter({
           url: 'https://<workspace-url>/ai-gateway/otel/v1/traces',
           headers: { Authorization: `Bearer ${process.env.DATABRICKS_TOKEN}` },
         }),
       ),
     ],
   });
   provider.register();

3. Crie spans no código do seu aplicativo:

   TypeScript

   const tracer = trace.getTracer('<your-application-name>');
   
   tracer.startActiveSpan('', (span) => {
     // Your application code
     span.end();
   });

BatchSpanProcessor exporta spans assincronicamente. Em scripts de curta duração, chame await provider.shutdown() antes que o processo saia para que os spans em buffer sejam enviados.

Para configurar o exportador sem código, use as variáveis de ambiente padrão do exportador OpenTelemetry. Os SDKs do OpenTelemetry que implementam a especificação do exportador OTLP os leem, por exemplo, quando você cria OTLPSpanExporter() em Python sem argumentos. O valor do cabeçalho é codificado por percentagem, portanto, o espaço após Bearer é gravado como %20:

Bash

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<workspace-url>/ai-gateway/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20<token>"
export OTEL_SERVICE_NAME="<your-application-name>"

Considere o seguinte comportamento:

• Defina o atributo de recurso service.name em cada provedor de rastreador. Intervalos sem isso aparecem na tabela de rastreamento sob unknown_external_service.
• Os spans devem ter um ID de rastreamento de 16 bytes, IDs de span e span pai de 8 bytes e um tempo de começar. Os spans que falham na validação são rejeitados e contados no campo partial_success da resposta.

Correlacionar rastreamentos do lado do cliente e do gateway

Quando seu aplicativo propaga o contexto de rastreamento W3C (o cabeçalho traceparent) em suas solicitações ao Unity Gateway, os intervalos de solicitação do gateway join o contexto de rastreamento propagado, para que possam aparecer no mesmo rastreamento que os intervalos do seu aplicativo. Com um SDK OpenTelemetry genérico, propague o contexto usando a instrumentação OpenTelemetry para seu cliente HTTP ou injetando o contexto nos cabeçalhos da solicitação. O W3C TraceContext é o propagador default.

O link de rastreamento do gateway está em Beta e é habilitado por workspace, separadamente da ingestão de span do lado do cliente. Para habilitá-lo para seu workspace, entre em contato com sua equipe de account da Databricks. Quando o link de rastreamento está habilitado, o gateway adota o contexto de rastreamento recebido para serviços de modelo do Unity Catalog e solicitações MCP. O gateway não encaminha o contexto de rastreamento para o provedor de modelo upstream.

Comportamento e limites de resposta

• O endpoint retorna um OTLP ExportTraceServiceResponse. HTTP 200 significa que o lote foi aceito para entrega, não que os spans estão armazenados de forma durável. As gravações são assíncronas.
• Os intervalos rejeitados, por exemplo, intervalos com IDs malformados ou intervalos enviados antes de o rastreamento ser habilitado para o workspace, são relatados no campo partial_success da resposta. Inspecione partial_success em vez de tentar novamente lotes inteiros.
• O Endpoint retornará HTTP 404 se a ingestão de intervalos do lado do cliente não estiver habilitada para o Workspace, HTTP 403 se a entidade de segurança dos tokens não tiver acesso ao Workspace e HTTP 400 se o corpo da solicitação não for um protobuf OTLP válido, por exemplo, um JSON ou corpo compactado.
• O endpoint aceita até 32 MiB por solicitação e 100 solicitações por segundo por organização. Os valores de atributo de string com mais de 3 MiB (3.145.728 bytes) são truncados. Atributos de matriz e mapa não são truncados, e os spans que excedem o limite de tamanho do registro podem ser descartados. Consulte Limitações.

Rastrear solicitações do Claude

O Unity Gateway integra-se com o suporte do OpenTelemetry do Claude para registrar solicitações da API de Mensagens do Claude e sessões de Agentes Gerenciados do Claude como intervalos na tabela de rastreamento unificada. Existem duas fontes de intervalos do Claude: o SDK do Claude emite intervalos do lado do cliente do seu aplicativo, e o Console do Claude exporta intervalos do lado do servidor para solicitações da API de Mensagens e sessões de Agentes Gerenciados. Você pode usar ambas as fontes ou apenas uma delas.

Você pode rastrear o seguinte:

• Solicitações da API de mensagens : cada solicitação com seu modelo, latência e uso de tokens. Se você habilitar a captura de conteúdo, os intervalos também incluem prompts e respostas.
• Sessões de Agentes gerenciar pelo Claude : Cada turno do agente com as solicitações do modelo, uso de ferramentas e uso de tokens, para que você possa acompanhar o que um agente fez o passo a o passo.

Para obter detalhes sobre o que cada fonte registra, consulte a documentação do OpenTelemetry da Anthropic.

Claude SDK

O SDK emite intervalos do lado do cliente para as solicitações de API que seu aplicativo faz. O SDK usa o provedor de rastreador registrado do seu aplicativo, portanto, depois de configurar o provedor de rastreador em Enviar intervalos com um SDK do OpenTelemetry, nenhum exportador específico do SDK é necessário. O token do Databricks nessa configuração autentica apenas o exportador de intervalo. Suas solicitações da Anthropic vão diretamente para a Anthropic e usam sua key de API da Anthropic.

Python

1. Instale ou atualize para o pacote anthropic mais recente, por exemplo pip install --upgrade anthropic.

2. Instale os pacotes OpenTelemetry e registro o provedor de rastreamento conforme descrito em Enviar spans com um SDK do OpenTelemetry.

3. Crie um cliente SDK Claude e envie uma solicitação:

   Python

   import anthropic
   
   # Uses your Anthropic API key from the ANTHROPIC_API_KEY environment variable.
   client = anthropic.Anthropic()
   
   message = client.messages.create(
       model="claude-opus-5-5",
       max_tokens=256,
       messages=[
           {"role": "user", "content": "What is a mixture of experts model?"},
       ],
   )

TypeScript

1. Instale ou atualize para o pacote @anthropic-ai/sdk mais recente, por exemplo npm install @anthropic-ai/sdk@latest.

2. Instale os pacotes OpenTelemetry e registro o provedor de rastreamento conforme descrito em Enviar spans com um SDK do OpenTelemetry.

3. Crie um cliente SDK Claude e envie uma solicitação:

   TypeScript

   import Anthropic from '@anthropic-ai/sdk';
   
   // Uses your Anthropic API key from the ANTHROPIC_API_KEY environment variable.
   const client = new Anthropic();
   
   const message = await client.messages.create({
     model: 'claude-opus-5-5',
     max_tokens: 256,
     messages: [{ role: 'user', content: 'What is a mixture of experts model?' }],
   });

O que o Claude SDK registra

Os spans seguem as convenções semânticas do GenAI do OpenTelemetry: um span por solicitação de API (por exemplo, anthropic.messages.create), com uso de tokens registrado em atributos gen_ai.usage.*. Para respostas de transmissão, o span da solicitação termina quando a transmissão é totalmente lida ou fechada.

O SDK oferece suporte às seguintes opções adicionais. Os exemplos usam o SDK do Python:

• Modo de conteúdo : por default, os intervalos carregam apenas metadados (metadata_only). Para incluir prompts e respostas em intervalos, defina traces.content_mode como content (por exemplo, Anthropic(open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}})). A key tracer_provider só é necessária para enviar os intervalos deste cliente para um provedor diferente daquele registrado globalmente. O conteúdo do prompt e da resposta é armazenado na tabela de rastreamento, portanto, limite o acesso a ele com políticas ABAC ou redação de PII conforme descrito em Permissões e controle de acesso. O conteúdo que excede o limite de conteúdo por intervalo do SDK é truncado, sendo que as mensagens de entrada mais antigas são truncadas primeiro. Imagens e documentos contribuem apenas com seu tipo, não com seus dados.
• ID da conversa : para agrupar solicitações em uma conversa, passe um ID de conversa por solicitação: client.with_options(open_telemetry={**client.open_telemetry, "conversation_id": "<conversation-id>"}). with_options substitui toda a configuração open_telemetry, portanto, faça um merge nas configurações existentes do cliente para manter opções como o modo de conteúdo.
• Desativar rastreamento : passe open_telemetry=False para desativar o rastreamento para um cliente. A variável de ambiente ANTHROPIC_OPEN_TELEMETRY controla o rastreamento para todos os clientes, e ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE define o modo de conteúdo, por exemplo, ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content.

Console do Claude

Para enviar os intervalos do lado do servidor do Console para a tabela de rastreamento unificada, adicione um destino de telemetria do Databricks. Os intervalos do lado do cliente do seu aplicativo, como chamadas de SDK e as ferramentas que seu aplicativo executa, vêm do rastreamento do SDK do Claude.

1. No console da Claude, vá para Destinos de telemetria.

2. Adicione um destino do Databricks e, em seguida, insira a URL do seu workspace e um access token pessoal do Databricks.

Os Requisitos acima, incluindo a atribuição de token-principal, também se aplicam a intervalos do Console.

Contar tokens

Se você enviar intervalos do Claude SDK e do Claude Console para a mesma tabela de rastreamento, cada solicitação produzirá dois intervalos anthropic.messages.create com as mesmas contagens de tokens: um intervalo SPAN_KIND_CLIENT do SDK e um intervalo SPAN_KIND_SERVER da API. Para contar cada solicitação uma única vez, some os atributos gen_ai.usage.* em apenas um tipo de intervalo. A seguinte query usa os intervalos de cliente do SDK. Se você enviar intervalos apenas do Claude Console, use kind = 'SPAN_KIND_SERVER' em vez disso.

SQL

SELECT
  sum(attributes:`gen_ai.usage.input_tokens`::bigint) AS input_tokens,
  sum(attributes:`gen_ai.usage.output_tokens`::bigint) AS output_tokens
FROM <catalog>.<schema>.<table_name>
WHERE name = 'anthropic.messages.create'
  AND kind = 'SPAN_KIND_CLIENT';

Permissões e controle de acesso

Como todo o tráfego do Unity Gateway é direcionado para uma única tabela, você gerencia o acesso em um só lugar em vez de manter permissões separadas por endpoint.

By default, apenas os administradores do metastore podem query a tabela de rastreamento. O administrador do metastore que criou a tabela é seu proprietário. Para dar a outros usuários acesso de query, o proprietário da tabela deve conceder SELECT na tabela, USE SCHEMA no esquema e USE CATALOG no catálogo. Sem um filtro de linha, qualquer usuário com esses privilégios pode ver rastreamentos de todos os serviços no workspace; portanto, o Databricks recomenda aplicar uma política de filtro de linha ABAC antes de conceder acesso.

Escopo de acesso com políticas ABAC

O Databricks recomenda o controle de acesso baseado em atributos (ABAC) para dar a cada usuário ou equipe acesso apenas às linhas que eles devem ver. Uma política de filtro de linha ABAC anexa uma função SQL à tabela de rastreamento (ou ao seu catálogo ou esquema pai) que é executada no momento da query. Quando um usuário executa SELECT *, ele recebe automaticamente apenas suas próprias linhas, sem nenhuma cláusula WHERE manual e sem risco de ler os rastreamentos de outra equipe.

O exemplo a seguir implementa uma política comum: administradores veem todos os rastreamentos; proprietários de endpoint veem apenas seu próprio serviço; todos os outros não veem nada.

Este exemplo segue uma convenção em que cada serviço tem um grupo de account correspondente chamado <service_name>-owners. Esses grupos não são criados automaticamente. Como parte da configuração do acesso, um administrador deve criar cada grupo e adicionar os membros apropriados, e deve repetir isso sempre que um novo endpoint for adicionado. A função de filtro e a política não mudam à medida que os grupos são adicionados.

1. Crie a função de filtro. Recebe um nome de serviço para cada linha e retorna TRUE se o usuário atual tiver permissão para visualizá-lo.

   SQL

   CREATE OR REPLACE FUNCTION <catalog>.<schema>.ai_traces_filter(svc STRING)
   RETURNS BOOLEAN
   RETURN is_account_group_member('admins')
       OR is_account_group_member(svc || '-owners');

2. Adicione uma tag à coluna service_name para que a política possa ser vinculada a ela. As políticas ABAC passam colunas para a função de filtro por tag governada.

   SQL

   ALTER TABLE <catalog>.<schema>.<table_name>
   ALTER COLUMN service_name SET TAGS ('ai_trace_service' = '');

3. Criar a política de filtro de linha na tabela de rastreamento.

   SQL

   CREATE POLICY ai_traces_filter
   ON TABLE <catalog>.<schema>.<table_name>
   COMMENT 'Restrict trace visibility to service owners and admins'
   ROW FILTER <catalog>.<schema>.ai_traces_filter
   TO `account users`
   FOR TABLES
   MATCH COLUMNS has_tag('ai_trace_service') AS svc
   USING COLUMNS (svc);

4. Crie o grupo de account <service_name>-owners para cada serviço (se ele ainda não existir), adicione seus membros e conceda a ele os privilégios necessários para query a tabela: USE CATALOG no catálogo, USE SCHEMA no esquema e SELECT na tabela.

   SQL

   GRANT USE CATALOG ON CATALOG <catalog> TO `customer-support-bot-owners`;
   GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `customer-support-bot-owners`;
   GRANT SELECT ON TABLE <catalog>.<schema>.<table_name> TO `customer-support-bot-owners`;

Com esta política em vigor, os resultados são filtrados automaticamente com base em quem executa a query:

• Um membro de customer-support-bot-owners que executa SELECT * FROM <table> vê apenas as linhas onde service_name = 'customer-support-bot'.
• Um membro do grupo admins vê todas as linhas.
• Qualquer outro usuário não vê nenhuma linha.

Quando um novo Endpoint é adicionado, repita o passo final: crie o grupo <service_name>-owners correspondente e conceda a ele SELECT. A política e a função de filtro não mudam.

Consulte Controle de acesso baseado em atributos no Unity Catalog para obter a referência completa de ABAC e Padrões comuns para filtragem de linhas e mascaramento de colunas para mais padrões de filtro de linha.

Acesso ao escopo com ocultação de PII

Outra abordagem para abrir o acesso é materializar uma versão da tabela com PII editada. A tabela editada pode conter uma concessão SELECT mais ampla que abrange mais usuários. A compensação é que os rastreamentos são materializados duas vezes: uma em sua forma não editada na tabela original, que mantém requisitos de acesso rigorosos, e outra em sua forma editada em uma tabela separada que está aberta a mais consumidores.

For a reference solution that redacts PII from OpenTelemetry traces in Unity Catalog, see Govern and redact traces in Unity Catalog.

Esquema

Cada linha na tabela de rastreamento unificada é um span do OpenTelemetry. Para a lista completa de colunas, chaves de atributo e campos de evento de avaliação de política, consulte Referência do esquema da tabela de rastreamento unificada.

Limitações

• O tamanho máximo de atributo que é registrado é de 3 MiB (3.145.728 bytes). Atributos que excedem isso são truncados. O span está marcado com databricks.trace.payload_truncated e seu dropped_attributes_count é incrementado.
• A entrega de logs de rastreamento é feita com base no "melhor esforço". A maioria dos rastreamentos chegará em poucos segundos; no entanto, para novas tabelas, os rastreamentos podem levar até uma hora para chegar.
• Os logs de rastreamento não são garantidos para erros 401, 403, 429 ou 500.
• A tabela de rastreamento pode parar de receber logs ou ser corrompida se você alterar o esquema da tabela, renomear a tabela ou excluir a tabela.
• O Databricks não gerencia o ciclo de vida da tabela de rastreamento; sem uma política de retenção, ela cresce indefinidamente. Para excluir linhas automaticamente após um período definido, habilite auto time-to-live (Auto-TTL) na tabela, que executa DELETE e VACUUM em segundo plano. Para gerenciar a retenção por conta própria, programe um DELETE periódico para remover linhas expiradas, seguido por VACUUM para recuperar seu armazenamento. Executar VACUUM isoladamente apenas remove arquivos que já não possuem referência; ele não exclui nenhuma linha. Defina uma política de retenção antes de ativar o rastreamento em produção.
• Por default, somente administradores do metastore podem fazer query na tabela de rastreamento. Um administrador do metastore deve configurar políticas de filtro de linha ABAC e conceder SELECT, USE SCHEMA e USE CATALOG antes que os criadores de endpoint ou equipes de segurança possam acessar seus próprios rastreamentos.