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

info

Beta

A tabela de rastreamento unificada está em Beta. O Unity AI Gateway está disponível de forma geral, mas seus recursos beta são habilitados separadamente. Um administrador da account deve ativar os recursos beta do Enhanced Unity AI Gateway na página Prévias do console da account. 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 AI Gateway.

Um administrador do metastore configura o rastreamento unificado uma única vez. Depois disso, todo o tráfego do Unity AI Gateway é registrado automaticamente, sem a 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 AI Gateway habilitada para sua account. Consulte Gerenciar prévias do Databricks.
• Unity Catalog ativado para seu Workspace.
• 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.

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 AI Gateway em uma única tabela do Unity Catalog no formato OpenTelemetry ("OTel"). Ele oferece três vantagens sobre as 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 AI 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 AI 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 Criar 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>';

Permissões e controle de acesso

Como todo o tráfego do Unity AI Gateway cai em 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.

Para uma solução de referência que redige PII de rastreamentos do OpenTelemetry no Unity Catalog, consulte Redact PII from OpenTelemetry 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.