MONITORIZACIÓN
Monitorizar un pipeline de cuotas de Pinnacle.
Un pipeline que sondea la API de cuotas de Pinnacle falla en silencio más a menudo que con ruido: los precios dejan de moverse, un cursor se atasca, un worker entra en backoff y nunca vuelve. Cinco métricas detectan esos fallos, y cada umbral se deriva del intervalo de sondeo y del plan en el que estás.
Las cinco métricas
Regístralas por tablero, es decir, por deporte y fase, porque un tablero de tenis en vivo y un tablero de fútbol prepartido fallan de forma independiente. Un contador por sondeo basta para derivar las cinco.
| Métrica | Cómo medirla | Alertar cuando |
|---|---|---|
| Antigüedad del snapshot | Segundos desde el último sondeo que devolvió un envelope válido | Por encima de tres intervalos de sondeo durante una cartelera |
| Avance del cursor | El valor last de cada respuesta, comparado con el anterior | Sin cambios durante 30 minutos mientras hay eventos del tablero en juego |
| Latencia del sondeo | Tiempo desde la solicitud hasta la respuesta parseada, p50 y p95 | p95 por encima de 2 segundos durante 10 minutos |
| Tasa de error | Respuestas por estado por hora: 2xx, 429, 5xx, timeouts | 429 por encima del 1% de las solicitudes, o cualquier 401 o 403 |
| Tasa de solicitudes | Solicitudes por segundo en el pico, y por día con la clave gratuita | Por encima del 70% del techo del plan, o 90 de las 100 gratuitas al día |
La antigüedad del snapshot es la que importa
Cualquier otro fallo acaba apareciendo aquí, y por eso la antigüedad es la métrica que poner en la pared. Calcúlala desde el último sondeo correcto y validado, no desde el último intento: un poller que recibe 5xx cada diez segundos lo intenta constantemente y nunca lo consigue. Expón el mismo número a tus consumidores junto a los precios, para que un dashboard pueda etiquetar un tablero desactualizado en lugar de mostrar precios viejos como actuales. La mesa de partidos pública de pnclHUB hace exactamente esto: retiene los precios cuando la frescura de la fuente no está confirmada en lugar de mostrarlos con una advertencia.
El umbral escala con el intervalo. Sondeando tableros en vivo cada 5 segundos, alerta a los 15; sondeando prepartido cada 30, alerta a los 90. Fuera de una cartelera, un tablero sin eventos puede quedarse en silencio de forma legítima, así que condiciona la alerta a que el tablero tenga eventos cuya hora de inicio ya haya pasado.
Avance del cursor y el delta vacío
El cursor since hace que un sondeo devuelva solo lo que cambió, y un tablero en vivo sano devuelve algo en la mayoría de los ciclos. Un cursor que deja de avanzar mientras hay partidos en juego significa una de tres cosas: el poller está enviando un cursor antiguo, la respuesta se descarta antes de guardar el cursor, o el propio feed se ha atascado. Registra el cursor con cada sondeo y las dos primeras se ven en un minuto. La disciplina de sondeo en integración REST cubre dónde debe vivir el cursor para que un reinicio reanude desde él.
Métricas de presupuesto
Las solicitudes por segundo frente al techo son el número que predice los 429 de mañana. Mantén el estado estable por debajo del 70% de la tasa del plan, 7 por segundo en el plan de 10 por segundo y 21 en el de 30 por segundo, y trata el pico de un día de partidos como la cifra a comparar, ya que los rechazos llegan cuando los tableros están más ocupados. Con la clave gratuita, el recuento diario es el que hay que vigilar: a 90 de las 100 solicitudes diarias, detén las llamadas opcionales para que las programadas terminen el día. La aritmética detrás del pico está en la página de planificación de capacidad.
De dónde salen los números
Una línea de registro estructurada por sondeo lo lleva todo: tablero, estado, latencia, cursor antes y después, número de eventos. Una capa de métricas puede derivar las cinco series de esas líneas, y una búsqueda en los registros responde a las preguntas que un dashboard no puede, como qué tablero produjo el primer 429 del sábado. Nombra las series con claridad, odds_poll_age_seconds, odds_poll_latency_seconds, odds_poll_total con una etiqueta de estado, y un ingeniero nuevo lee el dashboard sin leyenda.
{"board": "soccer/live", "status": 200,
"latency_ms": 412, "since": 141, "last": 158,
"events": 7, "at": "2026-09-29T14:03:10Z"}Añade una comprobación sintética que lea tu propio almacén, no la API: recupera un evento conocido de la caché cada minuto y confirma su antigüedad. Detecta el fallo en el que el poller funciona pero los consumidores no ven su trabajo. Si el poller también usa el stream SSE, cuenta las reconexiones por hora en el mismo dashboard; la guía de configuración de SSE en pnclPULSE describe cómo es un ciclo de reconexión sano.
Preguntas que esto plantea
¿La antigüedad del snapshot es lo mismo que la antigüedad de los datos del proveedor?
No. La antigüedad del snapshot mide tu poller. La frescura del propio feed es otra cuestión, y la documentación describe el prepartido actualizándose más o menos cada 30 segundos mientras los precios en vivo llegan en una fracción de segundo. Sigue ambas cuando puedas.
¿Cuánto historial deberían conservar las métricas?
Dos semanas a resolución completa cubren dos fines de semana, que es donde están los picos. Una retención más larga puede reducirse a máximos por hora.
¿Necesito las cinco con la clave gratuita?
La antigüedad y el recuento diario de solicitudes bastan para un prototipo. Añade el resto cuando el poller pase a un plan de pago y a un techo por segundo.
Las asignaciones y las cifras de actualización siguen la documentación publicada por el proveedor, revisada el 26 de septiembre de 2026. Publicado el .