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.

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

const mka1 = new SDK({
  bearerAuth: `Bearer ${process.env.MKA1_API_KEY}`,
});

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

const usage = await mka1.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. Por exemplo, a especificação em produção atualmente expõe endpoints de uso para responses, conversations, completions, embeddings, extract, classify e vector stores.

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 em infra-resources 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 infraestrutura em produção atualmente 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 em mkllm-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.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Auditoria de uso

O que está disponível hoje

Como isso aparece no nosso dashboard

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

Consulte relatórios de uso por usuário

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

Detecte ações impróprias

Fluxo prático de investigação

​O que está disponível hoje

​Como isso aparece no nosso dashboard

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

​Consulte relatórios de uso por usuário

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

​Detecte ações impróprias

​Fluxo prático de investigação

O que está disponível hoje

Como isso aparece no nosso dashboard

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

Consulte relatórios de uso por usuário

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

Detecte ações impróprias

Fluxo prático de investigação