Procesamiento por lotes, contrapresión y cierre controlado

El procesamiento por lotes puede reducir la sobrecarga de solicitudes, pero también cambia el impacto de las fallas y la latencia de entrega. Un proceso que pone en cola eventos sin límites puede consumir memoria durante una interrupción. Un proceso que finaliza sin tener en cuenta el trabajo pendiente puede perder silenciosamente sus eventos más recientes.

El registro API de Telemetry acepta un objeto JSON o una matriz de objetos JSON. La capacidad API no requiere que todos los productores mantengan una cola en segundo plano en memoria.

Comience con la entrega directa y esperada

Para flujos de trabajo de bajo volumen, envíe un evento de resultado compacto y espere la solicitud con un tiempo de espera limitado. Esta es la ruta de entrega más sencilla para razonar y probar.

Lote cuando la medición muestra que los gastos generales de solicitud son materiales o cuando un trabajador existente ya posee un buffer de recolección duradero. Prefiera lotes pequeños con un límite de tiempo a una cola grande que espera indefinidamente por un umbral de tamaño.

await telemetry.log("api_request_completed", [
  {
    event_id: "evt_101",
    route_template: "/api/projects/:id",
    status: "success",
    latency_ms: 84,
  },
  {
    event_id: "evt_102",
    route_template: "/api/projects/:id",
    status: "failed",
    latency_ms: 912,
    error_type: "database_timeout",
  },
]);

Mantenga todos los objetos de un lote compatibles con el mismo esquema de tabla. Un elemento no válido o incompatible puede complicar el resultado de toda la solicitud.

Atado cada cola

Si la aplicación almacena eventos en buffer, defina:

1. Recuento máximo de eventos en cola y bytes serializados.
2. Edad máxima antes de enviar un lote parcial.
3. Tamaño máximo de lote.
4. Solicite tiempo de espera y vuelva a intentar el presupuesto.
5. Comportamiento de desbordamiento.
6. Comportamiento de apagado.

El comportamiento de desbordamiento debe ser explícito. Descartar el evento de diagnóstico de baja prioridad más antiguo, probar una ruta de éxito ruidosa, bloquear a un trabajador de telemetría dedicado y persistir en una bandeja de salida duradera tienen diferentes consecuencias operativas. No permita que una cola ilimitada decida agotando la memoria del proceso.

Registre la profundidad de la cola, la antigüedad del evento más antiguo, los lotes enviados, los eventos aceptados, los eventos descartados y las fallas de entrega permanentes a través de una ruta de diagnóstico segura. Evite enviar de forma recursiva el propio evento de error de la cola de telemetría a través de la misma cola de errores.

Separar la contrapresión del trabajo del cliente

Para la mayoría de los análisis de productos, la entrega de telemetría no debería consumir todo el presupuesto de latencia de una solicitud de cliente. Utilice una transferencia breve y limitada o un trabajador propiedad de la aplicación. Si la cola está llena, aplique la política de desbordamiento documentada en lugar de esperar indefinidamente.

Para eventos de facturación o auditoría aprobados, utilice una bandeja de salida duradera y presione al trabajador de la bandeja de salida en lugar de perder el evento comercial. El guía de entrega de eventos e idempotencia explica la identidad estable del evento en todos los intentos.

Manejar el apagado deliberadamente

En una señal de apagado elegante:

1. Deja de aceptar nuevos trabajos.
2. Permitir que el trabajo de aplicaciones en vuelo alcance un límite definido.
3. Envíe o persista el lote de telemetría restante.
4. Hacer cumplir una fecha límite de cierre.
5. Registre el conteo que no se pudo entregar.

No reclame una garantía de descarga del cliente a menos que el SDK específico la exponga y la documente. Cuando un cliente envía cada llamada inmediatamente, esperar todas las llamadas rastreadas es diferente a vaciar una cola interna. Los tiempos de ejecución sin servidor y perimetrales pueden congelar la ejecución después de una respuesta, por lo tanto, utilice el mecanismo de trabajo en segundo plano compatible con el tiempo de ejecución o realice la entrega antes de regresar cuando se requiera el evento.

Verificar el comportamiento de sobrecarga

Pruebe un lote completo, un lote parcial activado por tiempo, 429, 503, tiempo de espera de conexión, desbordamiento de cola y terminación de proceso con eventos pendientes. Confirme que los reintentos conserven los ID de eventos y que ninguna ruta de error imprima credenciales o cargas útiles sin procesar.

Utilice el guía de solución de problemas de ingesta de eventos para verificar las respuestas y el guía de volumen de telemetría para medir si realmente es necesario realizar lotes o tomar muestras.