Skip to main content
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

vista de lista de SigNoz vista individual de log

​
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.
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 external_user_ids (IDs de usuario final delegados desde X-On-Behalf-Of) y user_ids (IDs de usuario de la plataforma), además de 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.
TypeScript SDK
Utiliza externalUserIds 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. Agrupado por model, el uso de Responses informa el nombre que envió cada solicitud, como auto, y el uso de Completions informa el modelo que atendió cada solicitud. El filtro models coincide con esos mismos nombres. Para saber qué modelo atendió una solicitud de Responses, lee el campo resolved_model de la respuesta (consulta enrutamiento automático).

​
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 define los campos requeridos:
  • request_id
  • actor_id
  • unit_id
  • route_name
  • action
  • resource_type
  • resource_id
  • outcome
  • policy_action
Si una política o guardarraíl se activa, regístralo en el mismo evento:

​
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 auditoría 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 el 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:
  1. Comienza con el informe de uso a nivel de cuenta en los endpoints de uso de la Referencia de API.
  2. Reduce al usuario final por X-On-Behalf-Of y externalUserId.
  3. Usa X-Request-ID para correlacionar la solicitud exacta en el borde.
  4. Inspecciona los logs de SigNoz para userId, externalUserId, userContext, route_name, action y outcome.
  5. 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.