> ## Documentation Index > Fetch the complete documentation index at: https://docs.mka1.com/llms.txt > Use this file to discover all available pages before exploring further. # Auditoria de uso > Acompanhe o uso por usuário, correlacione requisições na borda da API e estruture eventos de auditoria por unidade para detecção de uso indevido. Use este guia quando precisar mostrar qual conta e usuário final fez uma requisição, produzir relatórios de uso por usuário e investigar ações impróprias. A API MKA1 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, veja a [Referência da API](/pt/api-reference/introduction) e abra o grupo **Usage**. ## O que está disponível hoje A borda da API em tempo real e a pilha de observabilidade expõem os seguintes elementos: * As respostas em tempo real incluem `X-Request-ID`. * A configuração Kong ativa usa o plugin `correlation-id` com `header_name: X-Request-ID`, `echo_downstream: true` e `generator: uuid#counter`. * Os logs SigNoz em tempo real incluem `userId`, `externalUserId` e `userContext`. * Os ativos existentes do SigNoz incluem os dashboards `MKLLM Gateway`, `Guardrail Dashboard` e `Sandbox Commands`, além das visualizações de logs `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 visualização em lista do SigNoz visualização individual de log ## Envie um ID de usuário final estável em cada requisição delegada Para integrações server-side multiusuário, envie tanto o `Authorization` quanto o `X-On-Behalf-Of`. É isso que vincula o uso, recursos e logs ao usuário final correto. ```bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' \ --data '{ "model": "meetkai:functionary-pt", "input": "Reply with ok." }' ``` Capture os cabeçalhos de resposta dessa requisição e armazene o `X-Request-ID` junto com a entrada de log da sua aplicação. Isso fornece 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 suportam filtros `user_ids` e dimensões `group_by`. Use-os para relatórios em nível de conta e, em seguida, utilize os logs do SigNoz para investigar um usuário final ou requisição específica. ```ts theme={null} 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 usuário final do `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 dos seus serviços emitirem eventos de ação consistentes. O contrato de auditoria compartilhado em `infra-resources` define os campos obrigatórios: * `request_id` * `actor_id` * `unit_id` * `route_name` * `action` * `resource_type` * `resource_id` * `outcome` * `policy_action` ```json theme={null} { "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 guardrail for acionada, registre isso no mesmo evento: ```json theme={null} { "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 real já visível no SigNoz em 30 de março de 2026 mostra limitação em tempo de execução de atividade de ferramenta no `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 detecção de ações impróprias porque mostra a quantidade de ações tentadas e permitidas no mesmo evento. ## Fluxo prático de investigação Ao investigar uma requisição suspeita, siga esta ordem: 1. Comece pelo relatório de uso em nível de conta nos endpoints de uso da Referência da API. 2. Restrinja ao usuário final por `X-On-Behalf-Of` e `externalUserId`. 3. Use o `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 atividades de política ou ferramenta relacionadas. Isso fornece um caminho consistente desde o relatório de uso até uma requisição específica e, então, até o evento de ação exato que foi permitido, alertado, bloqueado ou escalado.