Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Esta página descreve como monitorar o uso dos serviços Unity Gateway usando a tabela do sistema de rastreamento de uso.
A tabela de rastreamento de uso captura detalhes de solicitações e respostas para serviços modelo, serviços de provedores modelo e serviços MCP. Para requisições de modelo, ele registra métricas como uso de token e latência. Para requisições MCP, ele registra metadados de chamadas e serviços. Use a tabela para monitorar usuários, acompanhar custos e analisar o uso e desempenho do serviço.
O rastreamento de uso também abrange solicitações ai_query aos Serviços de Modelo fornecidos pelo Databricks.
Os administradores de conta e workspace podem exibir uma visão geral consolidada do uso de IA na página de IA no Hub de Governança.
Requirements
- Um espaço de trabalho Azure Databricks em uma região suportada pelo Unity Gateway.
- Unity Catalog habilitado para seu workspace. Consulte Habilitar um workspace para o Unity Catalog.
Pricing
O rastreamento de uso é um recurso faturado do Unity Gateway. O Azure Databricks cobra pelo uso registrado na tabela system.ai_gateway.usage. Veja preços do Unity Gateway.
Consultar a tabela de uso
O Unity Gateway registra os dados de uso na system.ai_gateway.usage tabela do sistema. Você pode exibir a tabela na interface do usuário ou consultar a tabela no Databricks SQL ou em um notebook.
Observação
Tanto a função de administrador da conta quanto a de administrador do metastore são necessárias para visualizar ou consultar a system.ai_gateway.usage tabela por padrão. Administradores podem gerenciar o acesso às tabelas do sistema para controlar permissões para usuários, grupos e principais de serviço.
Para exibir a tabela na interface do usuário, clique no link da tabela de acompanhamento de uso na página do serviço de modelo para abrir a tabela no Gerenciador de Catálogos.
Para consultar a tabela do Databricks SQL ou de um notebook:
SELECT * FROM system.ai_gateway.usage;
Dica
O Código do Gênio (modo agente) pode fazer isso por você. Experimente este prompt de exemplo:
Query the system.ai_gateway.usage table to analyze AI Gateway usage showing request count and total tokens, grouped by endpoint name for the last 7 days.
Painel de uso integrado
Observação
Alguns workspaces ainda não exibem a lista suspensa Governar. Nesses espaços de trabalho, use os botões independentes Criar Painel,Visualizar Painel e Atualizar na página do Unity Gateway.
Criar um painel de uso embutido
Administradores de contas podem criar um painel de uso do Unity Gateway embutido para monitorar o uso, acompanhar custos e obter insights sobre o desempenho e o consumo de serviços do modelo. Na página do Unity Gateway, clique em Governar no canto superior direito e depois clique em Criar Painel de Uso. O warehouse que executa as consultas do painel é selecionado automaticamente.
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 estão sujeitos às políticas de retenção da tabela usage. Consulte Quais tabelas de sistema estão disponíveis?.
Quando uma versão mais recente do painel de uso embutido estiver disponível, os administradores de contas podem clicar em Atualizar na linha da versão do painel no menu suspenso Governar na página do Unity 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ê ativa essa opção, o painel se atualiza automaticamente sempre que uma versão mais recente fica disponível e um administrador de conta visita a página do Unity 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 visualizar o painel, clique em Governar no canto superior direito da página do Unity Gateway e depois clique em Controle de Uso. O painel abre em uma nova aba. O painel embutido oferece visibilidade abrangente sobre o uso do serviço do modelo Unity Gateway, desempenho e custo. 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.
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 esta aba para obter uma visão rápida da atividade geral do Unity Gateway 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 guia para monitorar a saúde do serviço do modelo e identificar gargalos de desempenho ou problemas de confiabilidade.
- Guia Uso: mostra detalhamentos de consumo por Serviço de Modelo, 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 Serviço de Modelo, modelo de destino, usuário, marcações de serviço e marcas de solicitação. Essa guia também inclui o custo estimado para modelos externos. Veja Analisar o custo do Unity 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 de agentes de programação: Acompanha a atividade dos agentes de programação integrados, incluindo Claude Code, Codex CLI, Cursor e Gemini CLI. 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 |
invocation_id |
STRING | Um identificador exclusivo para cada chamada de inferência individual. Várias invocações podem compartilhar o mesmo request_id, como verificações de proteção ou chamadas de agente de várias rodadas. Use invocation_id para distingui-los. |
c0a8012e-9f3b-4d21-8a7e-1b2c3d4e5f60 |
schema_version |
INTEGER | A versão do esquema do registro de uso. | 1 |
service_type |
STRING | O tipo de serviço que gerou o registro de uso. Os valores são MODEL_SERVICE, MCP_SERVICE, e MODEL_PROVIDER_SERVICE. |
MODEL_SERVICE |
service_id |
STRING | O ID do Serviço Modelo, Serviço MCP ou Serviço Provedor Modelo. | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
service_name |
STRING | O Catálogo Unity é o nome totalmente qualificado do serviço. | main.default.github_tools |
service_tags |
MAP | Etiquetas de recurso aplicadas ao Catálogo Unity são seguras no momento da criação ou atualização. Eles se aplicam a todas as solicitações ao serviço e são úteis para categorizar o uso por equipe, centro de custos ou projeto. | {"team": "engineering"} |
endpoint_id |
STRING | O ID único do serviço modelo Unity Gateway. | 43addf89-d802-3ca2-bd54-fe4d2a60d58a |
endpoint_name |
STRING | O nome do serviço modelo Unity Gateway. | system.ai.gpt-5-2 |
endpoint_tags |
MAP | Tags configuradas no serviço de modelo no momento da criação ou da atualização. Elas se aplicam a todas as solicitações ao serviço de modelo e são úteis para categorizar serviços por equipe, centro de custo ou projeto. | {"team": "engineering"} |
endpoint_metadata |
STRUCT | Metadados do serviço de modelo, 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. | system.ai.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.
Veja Solicitações de Tag para rastreamento de uso e Marcagem de Solicitações. |
{"project": "chatbot", "team": "ml-platform"} |
invocation_metadata |
STRUCT | Informações sobre a origem da solicitação, o nível de serviço reportado pelo provedor do modelo e se a solicitação utilizou uma assinatura Claude. | {"source": "EXTERNAL_CLIENT", "service_tier": "priority", "relayed": false} |
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 detalhado do uso de tokens e ferramentas, incluindo cache_read_input_tokens, cache_creation_input_tokens, output_reasoning_tokens, cache_creation_5m_input_tokens, cache_creation_1h_input_tokens, file_search_count, e num_web_search_queries. |
{"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", ...}]} |
mcp_metadata |
STRUCT | Detalhes de uma solicitação a um serviço MCP, incluindo a ferramenta invocada, o tipo de servidor e a operação JSON-RPC. Preenchido para MCP_SERVICE linhas. |
{"tool_name": "echo", "server_type": "EXTERNAL", "json_rpc_method": "tools/call"} |
session_metadata |
STRUCT | Contexto de sessão e cliente, incluindo IDs de sessão e subagentes, nome e versão do agente de codificação, interface do cliente, esforço de raciocínio e receita de roteamento inteligente. Use esses campos para agrupar requisições relacionadas e analisar o uso por agente ou sessão. | {"coding_agent": "claude-code", "agent_version": "2.1.282", "reasoning_effort": "high", ...} |
auth_mode |
STRING | O tipo de credencial Databricks usado para autenticar a solicitação: um token de acesso pessoal (PAT) ou um token OAuth (OAUTH). |
OAUTH |
Esquemas de colunas aninhadas
As tabelas a seguir descrevem campos dentro de colunas aninhadas STRUCT . A disponibilidade de campo depende do serviço, modelo e cliente usado para a solicitação.
Metadados de invocação e dos tokens
| Caminho do campo | Tipo | Descrição |
|---|---|---|
invocation_metadata.source |
STRING | O aplicativo, serviço ou API que iniciou a solicitação. Use este campo para atribuir o uso à sua fonte. Os valores incluem AI_PLAYGROUND, EXTERNAL_CLIENT, AI_QUERY, GUARDRAIL, e MANAGED_AGENT. |
invocation_metadata.service_tier |
STRING | O nível de serviço reportado pelo provedor modelo na resposta de inferência, como default ou priority. Use este campo para comparar o uso entre os níveis de precificação dos provedores. |
invocation_metadata.relayed |
BOOLEANO | Se o pedido foi repassado para a Anthropic usando a assinatura Claude do interlocutor. |
token_details.cache_read_input_tokens |
LONG | O número de tokens lidos do cache de prompts. |
token_details.cache_creation_input_tokens |
LONG | O número de tokens gravados no cache do prompt. |
token_details.output_reasoning_tokens |
LONG | O número de tokens de raciocínio na saída. |
token_details.cache_creation_5m_input_tokens |
LONG | O número de tokens de entrada gravados no cache do prompt com uma vida útil de 5 minutos. |
token_details.cache_creation_1h_input_tokens |
LONG | O número de tokens de entrada gravados no cache do prompt com tempo de retenção de 1 hora. |
token_details.file_search_count |
LONG | O número de chamadas de ferramenta de busca de arquivos feitas como parte da solicitação. |
token_details.num_web_search_queries |
LONG | O número de consultas faturáveis de pesquisa na web realizadas como parte da solicitação. |
Metadados do serviço MCP
Esses campos são preenchidos em mcp_metadata para MCP_SERVICE linhas.
| Caminho do campo | Tipo | Descrição |
|---|---|---|
mcp_metadata.tool_name |
STRING | O nome da ferramenta invocada por uma solicitação MCP tools/call . Use este campo para analisar o uso de ferramentas individuais em um servidor. |
mcp_metadata.server_type |
STRING | A categoria de servidor MCP que lida com a requisição, como EXTERNAL ou SYSTEM. |
mcp_metadata.json_rpc_method |
STRING | A operação JSON-RPC solicitada pelo cliente, como tools/call para invocar uma ferramenta, tools/list para descobrir ferramentas ou initialize para iniciar uma sessão. |
Metadados da sessão
Os session_metadata campos ajudam a correlacionar requisições dentro de uma sessão e distinguir agentes de codificação, interfaces de cliente e configurações de requisição. Cada campo é preenchido quando as informações correspondentes estão disponíveis do cliente ou solicitação.
| Caminho do campo | Tipo | Descrição |
|---|---|---|
session_metadata.client_session_id |
STRING | O ID da sessão fornecido pelo cliente. Use-o para agrupar solicitações feitas durante a mesma conversa ou sessão do agente de codificação. |
session_metadata.client_subagent_id |
STRING | O ID do subagente fornecido pelo cliente. Use-o com client_session_id para distinguir requisições de subagentes em uma sessão principal. |
session_metadata.coding_agent |
STRING | O nome normalizado do agente codificador que enviou a solicitação, como claude-code ou codex. |
session_metadata.agent_version |
STRING | A versão reportada pelo agente de codificação. Use-o com coding_agent para comparar o uso entre versões do agente. |
session_metadata.surface |
STRING | A interface cliente a partir da qual o agente de codificação enviava a solicitação, como uma interface de linha de comando, IDE ou aplicativo de desktop. |
session_metadata.reasoning_effort |
STRING | O esforço de raciocínio especificado na solicitação, como low, medium, ou high. Os valores disponíveis dependem do modelo e da API. |
session_metadata.smart_router_name |
STRING | O nome da receita de roteamento inteligente selecionado pelo cliente. Use-o para agrupar o uso por receita de roteamento. |
Solicitações de marcação para acompanhamento de uso
As tags de solicitação são pares de chave-valor personalizados que quem faz a chamada anexa a cada solicitação. 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. As marcas de solicitação são registradas na system.ai_gateway.usage tabela e podem ser usadas para filtrar, agregar e analisar dados de uso.
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 exemplos mostrando como definir tags de requisição com APIs REST, SDK OpenAI e SDK Anthropic, veja Marcagem de Requisições.
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;
Limitations
- O Unity Gateway não rastreia o uso de tokens para respostas maiores que 1 MiB que não sejam de streaming nem de embedding.