Registos de auditoria e monitorização através da consola
Nesta página
A importância da auditoria num ambiente regulamentado
Quando um auditor SOC 2 pergunta: «Quem consumiu o quê, quando e como saberia em caso de anomalia?», a resposta não pode ser «vamos investigar». Para qualquer organização sujeita a obrigações de conformidade — SOC 2, HIPAA, GDPR — a rastreabilidade das ações é um requisito fundamental, e deve prepará-la antes do incidente, não depois. A consola da xAI (console.x.ai) fornece as ferramentas de monitorização e auditoria que lhe permitem rastrear a utilização da sua chave de API e detetar anomalias; esta lição mostra-lhe como as utilizar e, em seguida, como as complementar no lado da aplicação.
A consola da xAI: o seu painel de segurança
A consola, acessível em console.x.ai, centraliza quatro funções: gestão de chaves de API, monitorização de utilização, faturação com limites de despesas e informações de segurança da conta. Relativamente aos dados, fornece-lhe a utilização por chave (número de pedidos, tokens consumidos), utilização por modelo, histórico de faturação detalhado por período e o estado de cada chave — ativa, bloqueada ou desativada. Crie o hábito de a consultar regularmente: a maioria das chaves comprometidas é detetada primeiro por uma curva de utilização que já não se assemelha às semanas anteriores.
Análise de utilização através da API
A consola é suficiente para uma verificação rápida, mas uma monitorização séria deve ser programática: é esse o papel do endpoint de análise.
POST /v1/billing/teams/{team_id}/usage
{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-03-01 00:00:00",
"endTime": "2026-04-01 00:00:00",
"timezone": "UTC"
},
"timeUnit": "DAY",
"values": [{"name": "tokens", "aggregation": "SUM"}],
"groupBy": ["model"]
}
}
Este pedido solicita a soma dos tokens consumidos, dia após dia, desagregada por modelo, para o mês de março. A flexibilidade advém de opções combináveis: as unidades de tempo variam de MÊS a MINUTO, incluindo SEMANA_CALENDÁRIO, DIA, HORA e QUARTO_DE_HORA; as agregações disponíveis são SOMA, MÉDIA, MÍN, MÁX, percentis P50, P90 e P99, bem como CONTAGEM e CONTAGEM_DISTINTA; e pode agrupar por modelo, período ou chave.
Estes componentes cobrem quatro necessidades concretas. Primeiro, a deteção de anomalias: um pico súbito de consumo numa chave que geralmente gere um volume estável é o sintoma clássico de um comprometimento — esta é a consulta que o seu script de monitorização deve executar todas as noites. Em seguida, a otimização de custos: ao agrupar por modelo, identifica endpoints subutilizados ou modelos dispendiosos chamados desnecessariamente. Relatórios de conformidade: a mesma consulta, ao longo de um trimestre, produz os números que o auditor solicitará. Por fim, o planeamento de capacidade: a tendência de consumo indica-lhe quando deve recarregar os seus créditos antes de ficar sem eles num domingo.
Construção de um sistema de alertas
Um painel que não consulta não protege nada; os alertas, no entanto, chegam até si. Eis o esqueleto de uma verificação diária que compara as últimas 24 horas de consumo com um limiar:
import requests
from datetime import datetime, timedelta
def check_usage_anomaly(team_id, threshold_tokens):
today = datetime.utcnow()
yesterday = today - timedelta(days=1)
response = requests.post(
f"https://management-api.x.ai/v1/billing/teams/{team_id}/usage",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
json={
"analyticsRequest": {
"timeRange": {
"startTime": yesterday.strftime("%Y-%m-%d 00:00:00"),
"endTime": today.strftime("%Y-%m-%d 00:00:00"),
"timezone": "UTC"
},
"timeUnit": "DAY",
"values": [{"name": "tokens", "aggregation": "SUM"}]
}
}
)
total_tokens = sum_tokens(response.json())
if total_tokens > threshold_tokens:
send_alert(f"Utilização anormal: {total_tokens} tokens em 24h")
Complemente esta configuração com uma rede de segurança orçamental: o endpoint POST /v1/billing/teams/{team_id}/postpaid/spending-limits permite-lhe definir um limite de despesas mensal — gastos excessivos descontrolados tornam-se então impossíveis, independentemente da causa. E para saber onde se encontra em qualquer ponto do ciclo de faturação, GET /v1/billing/teams/{team_id}/postpaid/invoice/preview fornece-lhe uma pré-visualização dos encargos acumulados antes da fatura final.
Registos de aplicações no lado do cliente
A consola da xAI vê o que acontece na xAI; não vê o que acontece do seu lado. Os seus próprios registos de aplicação são a outra metade da rastreabilidade: são eles que responderão à pergunta «que utilizador desencadeou esta chamada?». Para cada chamada à API, registe o carimbo de data/hora, o ID do utilizador que iniciou a chamada, o modelo e o endpoint utilizados, o número de tokens de entrada e de saída, o estado da resposta HTTP, a latência e o ID da chave de API na versão mascarada.
A disciplina inversa é igualmente importante, pois um registo verboso torna-se ele próprio uma fuga de dados. Nunca registe o conteúdo de prompts que contenham dados pessoais, nem respostas que contenham informações sensíveis, nem chaves de API em texto simples, nem tokens efémeros. Um ficheiro de registo que contenha os prompts dos seus utilizadores é uma base de dados pessoal disfarçada — com todas as obrigações do GDPR que isso implica, incluindo o direito ao apagamento.
Cinco métricas que tornam a monitorização legível
Para consolidar esta lição, reúna os seus dados de monitorização num único painel em vez de multiplicar os ecrãs. As duas primeiras métricas descrevem a atividade normal: consumo diário por chave e por modelo, e a taxa de erro (4xx, 5xx) por endpoint, que revela tanto um erro de implementação como uma chave com permissões mal configuradas. As duas seguintes descrevem atritos: tentativas de moderação acionadas, que indicam o que os seus utilizadores estão a tentar fazer, e chaves próximas da expiração, para antecipar renovações em vez de as enfrentar inesperadamente.
A quinta métrica é a que faz a diferença: a comparação com as médias históricas. Um número bruto não diz nada — oito milhões de tokens na noite passada, é muito? Um desvio em relação à norma, no entanto, diz tudo, e é sobre esse desvio que os seus alertas devem ser acionados.
Pontos-chave
- A consola da xAI (console.x.ai) centraliza a monitorização, a gestão de chaves e a faturação
- O endpoint de utilização permite uma análise programática com agregação flexível (de SOMA a P99, de MINUTO a MÊS)
- Configure alertas de limiar no consumo: um pico anormal é o primeiro sinal de comprometimento
- Defina limites de despesas através da API de Gestão para limitar qualquer excesso
- Registe metadados no lado da aplicação, nunca conteúdo sensível ou chaves em texto simples