Auditoría de uso

Utiliza esta guía cuando necesites mostrar qué cuenta y usuario final realizó una solicitud, generar informes de uso por usuario e investigar acciones indebidas. La API de MKA1 te proporciona endpoints públicos de uso, encabezados de correlación de solicitudes en vivo y campos de observabilidad vinculados a usuarios. Para detalles de los endpoints, consulta la Referencia de API y abre el grupo Usage.

Qué está disponible hoy

El borde de la API en vivo y la pila de observabilidad exponen los siguientes elementos:

Las respuestas en vivo incluyen X-Request-ID.
La configuración activa de Kong utiliza el plugin correlation-id con header_name: X-Request-ID, echo_downstream: true y generator: uuid#counter.
Los logs en vivo de SigNoz incluyen userId, externalUserId y userContext.
Los activos existentes de SigNoz incluyen los dashboards MKLLM Gateway, Guardrail Dashboard y Sandbox Commands, además de las vistas de logs Sandbox Commands 24h, Sandbox Command Errors 24h y MKLLM Errors.

Ejemplos recientes de sistemas en vivo:

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

Cómo se ve esto en nuestro panel

Envía un ID de usuario final estable en cada solicitud delegada

Para integraciones de servidor con múltiples usuarios, envía tanto Authorization como X-On-Behalf-Of. Esto es lo que vincula el uso, los recursos y los logs con el usuario final correcto.

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."
  }'

Captura los encabezados de respuesta de esa solicitud y almacena X-Request-ID junto con la entrada de log de tu propia aplicación. Eso te da una clave de unión estable entre el borde de la API y la observabilidad aguas abajo.

Consulta informes de uso por usuario

Los endpoints públicos de uso soportan filtros user_ids y dimensiones group_by. Úsalos para informes a nivel de cuenta, y luego utiliza los logs de SigNoz para investigar un usuario final o solicitud 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);

Utiliza userIds para tus IDs de usuario final desde X-On-Behalf-Of. Por ejemplo, la especificación activa actualmente expone endpoints de uso para respuestas, conversaciones, completions, embeddings, extract, classify y vector stores.

Registra acciones como un vocabulario fijo de auditoría

La detección de uso indebido por usuario y por unidad depende de que tus servicios emitan eventos de acción consistentes. El contrato de auditoría compartido en infra-resources define los campos requeridos:

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"
}

Si una política o guardarraíl se activa, regístralo en el mismo evento:

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

Detecta acciones indebidas

Agrupa tus logs y dashboards por actor_id, unit_id, action, outcome y policy_action. Esto te permite responder dos preguntas diferentes:

¿Qué usuario final o unidad generó la actividad?
¿Qué acciones fueron denegadas, limitadas o bloqueadas por una política?

El contrato de infraestructura activa actualmente define estos resultados:

success
denied
throttled
validation_error
policy_violation

Los valores correspondientes de policy_action son:

warn
block
escalate

Un ejemplo real ya visible en SigNoz el 30 de marzo de 2026 muestra la limitación en tiempo de ejecución de la actividad de herramientas en mkllm-gateway:

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

Ese patrón es útil para la detección de acciones indebidas porque muestra la cantidad de acciones intentadas y la cantidad de acciones permitidas en el mismo evento.

Flujo práctico de investigación

Cuando investigues una solicitud sospechosa, sigue este orden:

Comienza con el informe de uso a nivel de cuenta en los endpoints de uso de la Referencia de API.
Reduce al usuario final por X-On-Behalf-Of y externalUserId.
Usa X-Request-ID para correlacionar la solicitud exacta en el borde.
Inspecciona los logs de SigNoz para userId, externalUserId, userContext, route_name, action y outcome.
Revisa los dashboards MKLLM Gateway, Guardrail Dashboard y Sandbox Commands para actividad de política o herramientas relacionada.

Esto te da un camino consistente desde el informe de uso hasta una solicitud específica y luego hasta el evento de acción exacto que fue permitido, advertido, bloqueado o escalado.

Documentation Index

​Qué está disponible hoy

​Cómo se ve esto en nuestro panel

​Envía un ID de usuario final estable en cada solicitud delegada

​Consulta informes de uso por usuario

​Registra acciones como un vocabulario fijo de auditoría

​Detecta acciones indebidas

​Flujo práctico de investigación