Auditoria de uso

Use este guia quando precisar mostrar qual conta e usuário final fizeram uma solicitação, produzir relatórios de uso por usuário e investigar ações impróprias. A API MKA1 fornece endpoints públicos de uso, cabeçalhos de correlação de solicitações em tempo real e campos de observabilidade vinculados ao usuário. Para detalhes dos endpoints, consulte a Referência da API e abra o grupo Uso.

O que está disponível hoje

A borda da API em tempo real e a pilha de observabilidade expõem os seguintes elementos:

Cada resposta da API inclui X-Request-ID — inclusive rejeições (401/429) emitidas na borda do gateway.
O gateway disponibiliza um plugin global Kong correlation-id (parte da configuração de implantação da plataforma, aplicada em todas as instalações) com header_name: X-Request-ID, echo_downstream: true e generator: uuid#counter. Um X-Request-ID fornecido pelo cliente é preservado; solicitações sem um recebem um ID gerado.
A trilha de auditoria registra o mesmo ID como correlation_id em cada solicitação auditada — para solicitações rejeitadas na borda, o remetente de auditoria o resolve a partir do cabeçalho de resposta ecoado, portanto o ID que um cliente informa a partir de uma resposta de erro ainda localiza o registro de auditoria.
Para solicitações que chegam ao gateway, as linhas de log carregam o ID como httpRequestId (junto com traceId/spanId) e os rastreamentos de solicitação o carregam como o atributo de span http.request_id — assim, um ID conecta o cabeçalho de resposta, a trilha de auditoria, os logs e os rastreamentos.
Os logs em tempo real do SigNoz incluem userId, externalUserId e userContext.
Os recursos existentes do SigNoz incluem os dashboards MKLLM Gateway, Guardrail Dashboard e Sandbox Commands, além das visualizações de log Sandbox Commands 24h, Sandbox Command Errors 24h e MKLLM Errors.

Exemplos recentes de sistemas em produção:

GET /api/v1/llm/responses retornou X-Request-ID: 0736e48b-3d39-48d8-806c-952c907*****#12
GET /api/v1/agents retornou X-Request-ID: 0736e48b-3d39-48d8-806c-952c90*****#13
Os agregados de 24 horas do SigNoz mostraram valores de externalUserId como docs-pt-br-user com 14 eventos e docs-test-user com 7 eventos
Os agregados de 24 horas do SigNoz mostraram valores de userId como dRdj8VeoyuE7P9txS7ZVQ8ixI2***** com 63 eventos e uy95pqlp4ABgWCn5oLikRGV1TT***** com 23 eventos

Como isso aparece no nosso dashboard

Envie um ID estável de usuário final em cada solicitação delegada

Para integrações multiusuário no lado do servidor, envie tanto Authorization quanto X-On-Behalf-Of. Isso é o que vincula o uso, os recursos e os logs ao usuário final correto.

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "Responda com ok."
  }'

Capture os cabeçalhos de resposta dessa solicitação e armazene X-Request-ID com sua própria entrada de log da aplicação. Isso fornece uma chave de associação estável entre a borda da API e a observabilidade downstream.

Consulte relatórios de uso por usuário

Os endpoints públicos de uso oferecem suporte aos filtros external_user_ids (IDs de usuários finais delegados de X-On-Behalf-Of) e user_ids (IDs de usuários da plataforma), além das dimensões group_by. Use-os para relatórios no nível da conta e, em seguida, use os logs do SigNoz para investigar um usuário final ou uma solicitação específica.

TypeScript SDK

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

const endTime = Math.floor(Date.now() / 1000);
const startTime = endTime - 24 * 60 * 60;

const usage = await sdk.llm.usage.responses({
  startTime,
  endTime,
  externalUserIds: ["docs-test-user", "docs-pt-br-user"],
  groupBy: ["model", "background"],
});

console.log(usage);

Use externalUserIds para seus IDs de usuários finais de X-On-Behalf-Of. Os endpoints de uso cobrem completions, responses, conversations, embeddings, rerank, extract, classify, vector stores e files. GET /api/v1/llm/usage/costs soma os gastos de LLM em um intervalo de tempo. Para os gastos de todos os serviços, incluindo Compute e Sandbox, use o relatório de custos da plataforma; consulte Qual relatório usar. Agrupado por model, o uso de Responses e o de Completions informam o modelo que atendeu cada solicitação. Em Responses, é o resolved_model da resposta: o modelo para o qual auto e qualquer failover foram resolvidos. O filtro models corresponde aos mesmos nomes atendidos, então filtrar por auto não encontra nada nas respostas que registraram um modelo atendido. Respostas registradas antes de o modelo atendido ser armazenado mantêm o nome que a solicitação enviou. O relatório de custos de LLM agrupa pelo mesmo modelo atendido. Para ver qual modelo atendeu uma solicitação de Responses, leia o campo resolved_model dela (consulte roteamento automático).

Leia uma janela longa página por página

Todos os endpoints de uso, exceto costs, retornam a janela como buckets de tempo, uma página por vez:

bucket_width é 1m, 1h ou 1d, o padrão. Os buckets seguem os limites UTC, então um bucket 1d vai da meia-noite à meia-noite UTC. Quando start_time ou end_time cai dentro de um bucket, o primeiro bucket começa em start_time e o último termina em end_time, de modo que nenhum bucket conta uso de fora da sua janela. Leia o start_time de cada bucket em vez de presumir horários alinhados.
limit é o número de buckets por página. O padrão é 60 para 1m, 24 para 1h e 7 para 1d. Aceita de 1 a 1440, e um valor maior retorna 400. Uma página 1h contém no máximo 168 buckets e uma página 1d no máximo 31, seja qual for o limit enviado.
Quando a janela tem mais buckets do que cabem em uma página, a resposta traz has_more: true e um cursor next_page. Envie o cursor de volta como page, sem alterar nenhum outro parâmetro, para obter a próxima página. Repita até has_more ser false; a última página traz next_page: null.
O cursor é opaco. Envie-o apenas com os mesmos parâmetros da página que o retornou. Um cursor malformado retorna 400, assim como um de uma consulta com outro start_time ou outro bucket_width, ou um que não retoma dentro da janela. Uma mudança em qualquer outro parâmetro, como end_time ou um filtro, não é detectada.
end_time é opcional. Sem ele, a janela de cada página termina quando essa página é calculada, então as páginas de uma mesma consulta podem terminar em momentos diferentes. Envie um end_time explícito ao paginar.

Por exemplo, 30 dias de buckets 1d ocupam cinco páginas com o limit padrão de 7, ou uma página com limit=31. Nenhum endpoint de uso descarta buckets silenciosamente: uma janela maior que uma página sempre volta com has_more: true. Cada página também informa quando foi calculada e se seus números são definitivos. O uso das últimas 24 horas é provisório e ainda pode aumentar; consulte Quando os números de uso são definitivos.

Registre ações como um vocabulário fixo de auditoria

A detecção de uso indevido por usuário e por unidade depende de seus serviços emitirem eventos de ação consistentes. O contrato compartilhado de auditoria define os campos obrigatórios:

request_id
actor_id
unit_id
route_name
action
resource_type
resource_id
outcome
policy_action

{
  "request_id": "0736e48b-3d39-48d8-806c-952c907aa0be#12",
  "actor_id": "docs-test-user",
  "unit_id": "support-team-a",
  "route_name": "POST /api/v1/llm/responses",
  "action": "generate",
  "resource_type": "response",
  "resource_id": "resp_54d14e822fac430396ea2c04f771d7d3",
  "outcome": "success"
}

Se uma política ou barreira de proteção for acionada, registre isso no mesmo evento:

{
  "action": "tool_call",
  "outcome": "policy_violation",
  "policy_action": "block"
}

Detecte ações impróprias

Agrupe seus logs e dashboards por actor_id, unit_id, action, outcome e policy_action. Isso permite responder a duas perguntas diferentes:

Qual usuário final ou unidade gerou a atividade?
Quais ações foram negadas, limitadas ou bloqueadas por política?

O contrato de auditoria define estes resultados:

success
denied
throttled
validation_error
policy_violation

Os valores correspondentes de policy_action são:

warn
block
escalate

Um exemplo em produção já visível no SigNoz em 30 de março de 2026 mostra a limitação em tempo de execução da atividade de ferramentas no gateway:

mensagem: Limiting parallel tool calls to respect max_tool_calls
requestedToolCalls: 2
allowedToolCalls: 1
maxToolCalls: 5
responseId: resp_bcc0e8bba9524e8d9c14289c0c6*****

Esse padrão é útil para a detecção de ações impróprias porque mostra a contagem de ações tentadas e a contagem de ações permitidas no mesmo evento.

Fluxo prático de investigação

Ao investigar uma solicitação questionável, use esta ordem:

Comece pelo relatório de uso no nível da conta nos endpoints de uso da Referência da API.
Restrinja ao usuário final por X-On-Behalf-Of e externalUserId.
Use X-Request-ID para correlacionar a solicitação exata na borda.
Inspecione os logs do SigNoz para userId, externalUserId, userContext, route_name, action e outcome.
Verifique os dashboards MKLLM Gateway, Guardrail Dashboard e Sandbox Commands para atividades de política ou ferramentas relacionadas.

Isso fornece um caminho consistente desde os relatórios de uso até uma solicitação específica e, então, até o evento de ação exato que foi permitido, alertado, bloqueado ou escalado.

Visão geral

Gestão de modelos

Operações

Controle de acesso

Segurança e conformidade

Benchmarks