Monitorar o uso dos endpoints do Gateway de IA do Unity

Importante

Esse recurso está em Beta. Os administradores de conta podem controlar o acesso a esse recurso na página Visualizações do console da conta. Consulte Gerenciar prévias do Azure Databricks.

Esta página descreve como monitorar o uso de endpoints do Gateway de IA do Unity usando a tabela de acompanhamento de uso.

A tabela de acompanhamento de uso captura automaticamente os detalhes de solicitação e resposta para um endpoint, registrando métricas essenciais, como uso de token e latência. Você pode usar os dados nesta tabela para monitorar o uso, acompanhar os custos e obter informações detalhadas sobre o desempenho e o consumo dos endpoints.

O rastreamento de uso também registra solicitações para ai_query endpoints disponibilizados pela Databricks.

Requirements

Consultar a tabela de uso

O Gateway de IA do Unity registra dados de uso na tabela de sistema system.ai_gateway.usage. Você pode exibir a tabela na interface do usuário ou consultar a tabela no Databricks SQL ou em um notebook.

Observação

Somente os administradores da conta têm permissão para exibir ou consultar a system.ai_gateway.usage tabela.

Para exibir a tabela na interface do usuário, clique no link da tabela de acompanhamento de uso na página do endpoint para abrir a tabela no Explorador de Catálogos.

Para consultar a tabela do Databricks SQL ou de um notebook:

SELECT * FROM system.ai_gateway.usage;

Painel de uso integrado

Criar painel de uso interno

Os administradores da conta podem criar um painel integrado de uso do Unity AI Gateway clicando em Criar painel na página do AI Gateway para monitorar o uso, acompanhar os custos e ter insights sobre o desempenho e o consumo do endpoint. Os administradores de conta também podem atualizar o warehouse usado para executar consultas de painel, o que se aplica a todas as consultas subsequentes.

Botão de criar painel

Observação

A criação do painel é restrita aos administradores da conta porque requer permissões SELECT na tabela system.ai_gateway.usage. Os dados do painel de controle estão sujeitos às usage políticas de retenção da tabela. Consulte Quais tabelas de sistema estão disponíveis?.

Quando uma versão mais recente do painel de uso interno estiver disponível, os administradores da conta poderão clicar em Atualizar no menu ações do painel na página do Gateway de IA.

Caixa de diálogo do painel de atualização do ai-gateway

Você pode usar as seguintes opções de configuração do painel para gerenciar o painel:

  • Escopo: selecione se o escopo do painel deve ser aplicado à conta ou ao espaço de trabalho.
  • Permissões: escolha se as consultas são executadas usando as permissões do proprietário do painel ou as permissões de cada visualizador. Veja o que são permissões de dados compartilhadas?.
  • Atualizações automáticas: quando você habilita essa opção, o painel é atualizado automaticamente sempre que uma versão mais recente fica disponível e um administrador de conta visita a página do Gateway de IA.

Opções do painel de atualização do ai-gateway

Quando o painel é atualizado para versão 0.3 ou superior, um agendamento é criado automaticamente para atualizar o painel a cada 6 horas. Se necessário, esse agendamento pode ser desabilitado no painel do Lakeview. Confira Criar agendamento.

Exibir painel de uso

Para exibir o painel, clique em Exibir Painel na página gateway de IA. O painel integrado oferece visibilidade abrangente sobre o uso, o desempenho e o custo do endpoint do Unity AI Gateway. Ele inclui várias páginas acompanhando solicitações, consumo de token, métricas de latência, taxas de erro, detalhamentos de custos, tráfego externo do servidor MCP e atividade do agente de codificação.

Botão Exibir painel de controle

painel de uso do ai-gateway

O painel fornece análise entre espaços de trabalho por padrão. Todas as páginas do painel podem ser filtradas por intervalo de datas e ID do workspace.

  • Guia Visão geral: mostra métricas de uso de alto nível, incluindo volume de solicitação diária, tendências de uso de token ao longo do tempo, principais usuários por consumo de token e contagens totais de usuários exclusivos. Use essa guia para obter um instantâneo rápido da atividade geral do Gateway de IA do Unity e identificar os usuários e modelos mais ativos.
  • Guia Desempenho: controla as principais métricas de desempenho, incluindo percentis de latência (P50, P90, P95, P99), tempo para primeiro byte, taxas de erro e distribuições de código de status HTTP. Use esta aba para monitorar a integridade do ponto de extremidade e identificar gargalos de desempenho ou problemas de confiabilidade.
  • Aba de Uso: mostra detalhamentos de consumo por endpoint, workspace e solicitante. Esta aba mostra padrões de uso de tokens, distribuição de solicitações e taxas de acerto de cache.
  • Guia Observabilidade de Custo: mostra divisões de custo por ponto de extremidade, modelo de destino, usuário, marcas de ponto de extremidade e marcas de solicitação. Essa guia também inclui o custo estimado para modelos externos. Consulte Monitoramento do custo do Unity AI Gateway.
  • Guia Servidor MCP externo: mostra volume de solicitação, taxas de erro, usuários e conexões e tendências de uso diário para o tráfego externo do servidor MCP.
  • Aba Agentes de Codificação: acompanha a atividade de agentes de codificação integrados, incluindo Cursor, Claude Code, CLI do Gemini e CLI do Codex. Essa guia mostra métricas como dias ativos, sessões de codificação, confirmações e linhas de código adicionadas ou removidas para monitorar o uso da ferramenta de desenvolvedor. Consulte o painel do agente de codificação para obter mais detalhes.

Esquema de Tabela de Utilização

A system.ai_gateway.usage tabela tem o seguinte esquema:

Nome da coluna Tipo DESCRIÇÃO Example
account_id STRING O ID da conta. 11d77e21-5e05-4196-af72-423257f74974
workspace_id STRING O identificador do espaço de trabalho. 1653573648247579
request_id STRING Um identificador exclusivo para a solicitação. b4a47a30-0e18-4ae3-9a7f-29bcb07e0f00
schema_version INTEGER A versão do esquema do registro de uso. 1
endpoint_id STRING O ID exclusivo do ponto de extremidade do Gateway de IA do Unity. 43addf89-d802-3ca2-bd54-fe4d2a60d58a
endpoint_name STRING O nome do ponto de extremidade do Unity AI Gateway. databricks-gpt-5-2
endpoint_tags MAP Tags configuradas no endpoint no momento da criação ou da atualização. As tags de endpoint se aplicam a todas as requisições ao endpoint e são úteis para categorizar endpoints por equipe, centro de custo ou projeto. Consulte como marcar solicitações e endpoints para rastreamento de uso. {"team": "engineering"}
endpoint_metadata STRUCT Metadados de ponto de extremidade, incluindo creator, creation_time, last_updated_time, destinations, inference_table e fallbacks. {"creator": "user.name@email.com", "creation_time": "2026-01-06T12:00:00.000Z", ...}
event_time TIMESTAMP O registro de data/hora quando a solicitação foi recebida. 2026-01-20T19:48:08.000+00:00
latency_ms LONG A latência total em milissegundos. 300
time_to_first_byte_ms LONG O tempo até o primeiro byte em milissegundos. 300
destination_type STRING O tipo de destino (por exemplo, modelo externo ou modelo de base). PAY_PER_TOKEN_FOUNDATION_MODEL
destination_name STRING O nome do modelo ou provedor de destino. databricks-gpt-5-2
destination_id STRING A ID exclusiva do destino. 507e7456151b3cc89e05ff48161efb87
destination_model STRING O modelo específico usado para a solicitação. GPT-5.2
requester STRING A ID do usuário ou da entidade de serviço que fez a solicitação. user.name@email.com
requester_type STRING O tipo de solicitante (usuário, entidade de serviço ou grupo de usuários). USER
ip_address STRING O endereço IP do solicitante. 1.2.3.4
url STRING A URL da solicitação. https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions
user_agent STRING O agente de usuário do solicitante. OpenAI/Python 2.13.0
api_type STRING O tipo de chamada à API (por exemplo, chat, conclusões ou inserções). mlflow/v1/chat/completions
request_tags MAP Etiquetas fornecidas pelo usuário enviadas com solicitações individuais usando o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags. Use marcas de solicitação para atribuir o uso a projetos, equipes, ambientes ou usuários finais específicos. Consulte solicitações de marca e pontos de extremidade para acompanhamento de uso e solicitações de marca para acompanhamento de uso. {"project": "chatbot", "team": "ml-platform"}
input_tokens LONG O número de tokens de entrada. 100
output_tokens LONG O número de tokens de saída. 100
total_tokens LONG O número total de tokens (entrada + saída). 200
token_details STRUCT Detalhamento de token, incluindo cache_read_input_tokens, cache_creation_input_tokense output_reasoning_tokens. {"cache_read_input_tokens": 100, ...}
response_content_type STRING O tipo de conteúdo da resposta. application/json
status_code INT O código de status HTTP da resposta. 200
routing_information STRUCT Detalhes de roteamento para tentativas de fallback. Contém uma attempts matriz com priority, action, , destination, destination_idstatus_code, , error_code, latency_ms, e start_timeend_time para cada modelo tentado durante a solicitação. {"attempts": [{"priority": "1", ...}]}

Etiquetar solicitações e endpoints para rastreamento de uso

O Gateway de IA oferece suporte a dois tipos de tags para rastrear e atribuir o uso:

  • Marcas de solicitação: pares chave-valor personalizados que o chamador anexa a solicitações individuais. Use marcas de solicitação para atribuir o uso por projeto, equipe, ambiente, usuário final ou qualquer outra dimensão relevante para sua organização.
  • Tags de endpoint: pares de chave-valor configurados no próprio endpoint. As tags de endpoint se aplicam a todas as solicitações roteadas por meio do endpoint e são úteis para categorizar endpoints por equipe, centro de custo ou aplicativo.

Ambos os tipos de tag são registrados na tabela system.ai_gateway.usage e podem ser usados para filtrar, agrupar e analisar dados de uso.

Etiquetas da solicitação

Para identificar solicitações individuais, inclua o cabeçalho HTTP Databricks-Ai-Gateway-Request-Tags com um objeto JSON que mapeia chaves de string para valores de string. As tags de solicitação são registradas na coluna request_tags na tabela de uso e nas tabelas de inferência.

Para ver exemplos de como definir tags de solicitação com a API REST, o SDK da OpenAI e o SDK da Anthropic, consulte Marcar solicitações para rastreamento de uso.

Por exemplo, você pode agregar o uso por projeto usando marcas de solicitação:

SELECT
  request_tags['project'] AS project,
  COUNT(*) AS request_count,
  SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE request_tags['project'] IS NOT NULL
GROUP BY request_tags['project']
ORDER BY total_tokens DESC;

Tags de endpoint

As tags de endpoint são configuradas ao criar ou atualizar um endpoint do AI Gateway. Eles aparecem na coluna endpoint_tags da tabela de uso em todas as solicitações a esse endpoint.

Por exemplo, você pode agrupar o uso por equipe usando tags de endpoint:

SELECT
  endpoint_tags['team'] AS team,
  endpoint_name,
  COUNT(*) AS request_count,
  SUM(total_tokens) AS total_tokens
FROM system.ai_gateway.usage
WHERE endpoint_tags['team'] IS NOT NULL
GROUP BY endpoint_tags['team'], endpoint_name
ORDER BY total_tokens DESC;

Próximas etapas

  • Last updated on