Qué registrar de un sondeador de cuotas

Un sondeador que registra cada sondeo exitoso llena su log con la única línea que no te dice nada. El log útil es una lista de transiciones: errores, bloqueos, reanudaciones y reinicios, más un pequeño resumen por hora. Las métricas te dicen que algo va mal; este log te dice el qué.

Las métricas no son logs

La guía de monitorización sigue cinco métricas por tablero: edad del snapshot, progreso del cursor, latencia, tasa de error y tasa de solicitudes. Esos números responden si el pipeline está sano ahora mismo. No responden qué pasó a las 03:14 cuando el cursor se atascó, y esa segunda pregunta es la que harás de verdad durante un incidente. El log existe para la segunda pregunta.

Lo que merece una línea

Registra los eventos que cambian estado, con contexto suficiente para actuar después:

• Cada 429, con su valor de Retry-After y la llamada que lo disparó, como recomienda la guía de límites de tasa para alerta temprana.
• Cada 401 y 403, inmediatamente y en alto volumen, porque esos son errores de parada, no de reintento.
• Cada 200 que falla la validación, con la forma de sobre que realmente recibiste.
• Guardados y reanudaciones de cursor, incluido el valor desde el que reanudaste tras un reinicio.
• Lecturas completas del tablero, que deben ser tan raras que cada una lleve un motivo declarado.
• Arranques y paradas de proceso, para que una ventana de caída sea demostrable después.

Cada línea necesita el tablero, la marca de tiempo y el motivo. Una línea sin el nombre del tablero es una aguja en un pajar de trece tableros.

Lo que hay que mantener fuera

No registres cada sondeo exitoso en nivel info, y nunca metas payloads completos de respuesta en el flujo de eventos. La guía de almacenamiento ya responde a la cuestión de los payloads: guarda respuestas crudas comprimidas unos días si quieres rederivar filas tras un bug de parser, y consulta la tabla normalizada. Una línea por selección cambiada pertenece a la tabla de cambios, no al syslog.

El resumen por hora lo paga todo

Una línea de resumen por tablero por hora, sondeos hechos, eventos cambiados, errores por estado, alimenta tanto las métricas como las autopsias. Del resumen puedes recomputar cualquiera de las cinco métricas para cualquier hora que guardaste, lo que significa que el log detallado de eventos puede quedarse corto y el panel puede quedarse honesto.

Registra los cambios, cuenta la rutina, mantén los payloads fuera. El siguiente incidente entonces empieza con respuestas, no con un grep por un millón de líneas idénticas.