Saltar al contenido
Telemetry
Fiabilidad de la API

api_request_completed esquema de evento

Un evento de solicitud de terminal con plantillas de ruta en lugar de URL sin formato, categorías de error limitadas y latencia medida en el límite del servicio.

Revisado por el equipo de producto Telemetry en . Grano de eventos, propiedad, tipos de campos, clasificación de privacidad, carga útil de ejemplo y validación. Revisar los estándares y la propiedad

Pruebe este esquema

Pregunta que este contrato responde

¿Dónde afectan los errores y las solicitudes lentas a los clientes?

Campos
10
Requerido
9
Ruta de evidencia del contrato

api_request_completed: del límite propio a la consulta confiable

Trate a api_request_completed como un contrato analítico duradero: el propietario emite un grano documentado, un dispositivo prueba los campos y una consulta revisada responde a la pregunta formulada.

  1. 1

    El resultado se vuelve definitivo

    HTTP middleware at request completion emits only after the final response status and latency are known.

  2. 2

    El contrato está limitado.

    9 required fields preserve the declared grain: One completed API request.

  3. 3

    El accesorio está verificado

    Tipos de verificación, hora UTC, resultados alternativos, idempotencia y todos los campos seudónimos o clasificados por revisión.

  4. 4

    La pregunta esta respondida

    ¿Dónde afectan los errores y las solicitudes lentas a los clientes?

grano

Una solicitud de API completada.

propietario

Middleware HTTP al finalizar la solicitud

Emitir cuando

Después de conocer el estado de respuesta final y la latencia.

Contrato de campo

Campos escritos con límites de privacidad explícitos

Mantenga estables los nombres y tipos de campos existentes después de que las consultas de producción dependan de ellos. El contexto opcional debe permanecer limitado, documentado y justificado por una decisión específica.

CampoTipoRequeridoPrivacidadSignificado
timestamp_utctimestampyesnon-sensitiveHora UTC en el límite del resultado.
event_idstringyesnon-sensitiveIdentificador único estable utilizado para la deduplicación.
releasestringyesnon-sensitiveVersión de la aplicación o servicio que emitió el evento.
account_idstringyespseudonymousIdentificador de cuenta interno estable, nunca un correo electrónico o nombre.
request_idstringyespseudonymousIdentificador de correlación; no exponga material de autenticación.
routestringyesnon-sensitivePlantilla de ruta de baja cardinalidad como /v1/query/:id.
methodstringyesnon-sensitiveMétodo HTTP.
status_codenumberyesnon-sensitiveEstado de la respuesta HTTP final.
latency_msnumberyesnon-sensitiveDuración de un extremo a otro en milisegundos.
error_typestringnonon-sensitiveCategoría de falla acotada; omita los seguimientos de pila y las cargas útiles.

Evento JSON sintético

{
  "timestamp_utc": "2026-07-28T14:15:06Z",
  "event_id": "evt_api_01",
  "account_id": "acct_8f31",
  "release": "2026.07.2",
  "request_id": "req_2f71",
  "route": "/v1/query/:id",
  "method": "POST",
  "status_code": 200,
  "latency_ms": 184
}

Revisión de privacidad

Revisar los identificadores antes de la ingestión

Este ejemplo utiliza identificadores sintéticos. Los valores seudónimos aún pueden ser datos personales y los campos de revisión pueden exponer el contexto empresarial o del proveedor. Aplique sus propios requisitos de consentimiento, retención, acceso, residencia y eliminación.

  • account_id: pseudonymous
  • request_id: pseudonymous

Lista de verificación de validación

Pruebe el contrato antes de crear un panel

  • Send one known api_request_completed fixture after the documented outcome boundary.
  • Verify all 9 required fields arrive with the documented types.
  • Vuelva a intentar el mismo identificador de evento y confirme el comportamiento de deduplicación elegido.
  • Envíe un error controlado o un resultado alternativo cuando el flujo de trabajo lo admita.
  • Ejecute el SQL relacionado en una ventana fija y concilie el resultado con el dispositivo.

Errores comunes

Mantenga una fila igual a un resultado duradero

  • Emitting api_request_completed before http middleware at request completion knows the final outcome.
  • Mezclar varios granos en una tabla, lo que hace que los recuentos y tasas sean ambiguos.
  • Reemplazar categorías controladas con URL sin formato, cargas útiles, mensajes o texto de error.
  • De ello depende el cambio de un tipo de campo después de las consultas y los paneles guardados.
  • Agregar identificadores sin una necesidad documentada de investigación, acceso y retención.

Usa el contrato

Consultar y operacionalizar el evento.

Panel de confiabilidad de APILatencia de API SQLGuía de diseño de esquemas de eventos.

Contratos relacionados

user_signed_up

¿Qué cohortes de registro se activan y retienen?

Revisar esquemaproduct_milestone_completed

¿Qué cuentas alcanzan los momentos duraderos que definen la activación?

Revisar esquemallm_request_completed

¿Cuánto cuesta cada flujo de trabajo de IA exitoso y qué tan bien funciona?

Revisar esquema

Enviar un dispositivo antes del tráfico de producción.

Cree una clave API gratuita, envíe el evento sintético e inspeccione la tabla inferida antes de conectar un flujo de trabajo en vivo.

Pruebe este esquema