Saltar para o conteúdo principal
Use este guia quando precisar mostrar qual conta e qual end user fez uma requisição, gerar relatórios de uso por usuário e investigar ações indevidas. A MKA1 API oferece endpoints públicos de uso, cabeçalhos de correlação de requisição 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 Usage.

​
O que está disponível hoje

A borda da API e a pilha de observabilidade em produção expõem os seguintes elementos:
  • Respostas ao vivo incluem X-Request-ID.
  • A configuração ativa do Kong usa o plugin correlation-id com header_name: X-Request-ID, echo_downstream: true e generator: uuid#counter.
  • Logs ao vivo do SigNoz incluem userId, externalUserId e userContext.
  • Os ativos existentes no SigNoz incluem os dashboards MKLLM Gateway, Guardrail Dashboard e Sandbox Commands, além das log views Sandbox Commands 24h, Sandbox Command Errors 24h e MKLLM Errors.
Exemplos recentes de sistemas ao vivo:
  • 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
  • Agregações de 24 horas no SigNoz mostraram valores de externalUserId como docs-pt-br-user com 14 eventos e docs-test-user com 7 eventos
  • Agregações de 24 horas no SigNoz mostraram valores de userId como dRdj8VeoyuE7P9txS7ZVQ8ixI2***** com 63 eventos e uy95pqlp4ABgWCn5oLikRGV1TT***** com 23 eventos

​
Envie um ID estável de end user em toda requisição delegada

Para integrações server-side com múltiplos usuários, envie Authorization e X-On-Behalf-Of. É isso que vincula uso, recursos e logs ao end user 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": "Reply with ok."
  }'
Capture os cabeçalhos de resposta dessa requisição e armazene X-Request-ID junto com o log da sua aplicação. Isso lhe dá uma chave de junçã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 aceitam filtros user_ids e dimensões group_by. Use-os para relatórios em nível de conta e depois use os logs do SigNoz para investigar um end user ou uma requisiçã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,
  userIds: ["docs-test-user", "docs-pt-br-user"],
  groupBy: ["model", "background"],
});

console.log(usage);
Use userIds para os IDs de end user que você envia em X-On-Behalf-Of. Por exemplo, a especificação ao vivo hoje expõe endpoints de uso para responses, conversations, completions, embeddings, extract, classify e vector stores.

​
Registre ações com 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 policy ou guardrail disparar, registre isso no mesmo evento: 
{
  "action": "tool_call",
  "outcome": "policy_violation",
  "policy_action": "block"
}

​
Detecte ações indevidas

Agrupe seus logs e dashboards por actor_id, unit_id, action, outcome e policy_action. Isso permite responder a duas perguntas diferentes:
  • Qual end user ou unidade gerou a atividade?
  • Quais ações foram negadas, limitadas ou bloqueadas por policy?
O contrato ativo de infraestrutura define hoje estes valores de outcome:
  • success
  • denied
  • throttled
  • validation_error
  • policy_violation
Os valores correspondentes de policy_action são:
  • warn
  • block
  • escalate
Um exemplo ao vivo já visível no SigNoz em 30 de março de 2026 mostra limitação em tempo de execução para atividade de ferramentas em mkllm-gateway:
  • message: Limiting parallel tool calls to respect max_tool_calls
  • requestedToolCalls: 2
  • allowedToolCalls: 1
  • maxToolCalls: 5
  • responseId: resp_bcc0e8bba9524e8d9c14289c0c6*****
Esse padrão é útil para detectar ações indevidas porque mostra a contagem de ações tentadas e a contagem de ações permitidas no mesmo evento.

​
Fluxo prático de investigação

Quando você investigar uma requisição questionável, use esta ordem:
  1. Comece pelo relatório de uso em nível de conta nos endpoints de uso da Referência da API.
  2. Afunile até o end user usando X-On-Behalf-Of e externalUserId.
  3. Use X-Request-ID para correlacionar a requisição exata na borda.
  4. Inspecione os logs do SigNoz para userId, externalUserId, userContext, route_name, action e outcome.
  5. Verifique os dashboards MKLLM Gateway, Guardrail Dashboard e Sandbox Commands para ver a atividade de policy ou de ferramentas ao redor do evento.
Isso lhe dá um caminho consistente do relatório de uso para uma requisição específica e depois para o evento exato que foi permitido, sinalizado, bloqueado ou escalado.