SALUD DEL FEED
Observa el propio pulso del feed.
Cuando un tablero se queda quieto, la primera pregunta es de quién es la culpa: de tu poller o de la fuente. La API de cuotas de Pinnacle lo responde directamente en dos endpoints de estado: un /health autenticado con detalle por feed, y un /ping público que devuelve un simple ok. Sondearlos en un bucle lento hace que una degradación aparezca en tu panel antes que en tu producto.
Lo que /health reporta
Un GET con tu clave de API devuelve el estado operacional de ambos feeds. Los campos de nivel superior describen solo el feed en vivo: status es healthy o degraded con un degraded_reason opcional, live_write_age_ms son los milisegundos desde la última escritura en vivo, source dice si los datos en vivo llegan por ws, rest o none, y version es el mismo cursor que los endpoints de tablero devuelven como last.
{
"status": "healthy",
"degraded_reason": null,
"live_write_age_ms": 546,
"source": "ws",
"events_in_store": 145,
"version": 50352678,
"prematch": {
"enabled": true,
"status": "healthy",
"write_age_ms": 71,
"version": 50352723
}
}
El objeto anidado prematch es un segundo servicio, no un detalle. Lleva su propio status, que también puede ser unreachable, y su propio write_age_ms y version. Un lado puede estar degradado mientras el otro está bien, y el estado de nivel superior nunca cambia por un problema de prepartido, así que un monitor que lee solo el campo superior está ciego a la mitad del feed.
Conéctalo a tu monitor
Sondea /health una vez por minuto por entorno; cada llamada es una solicitud en tu plan, así que es un pulso barato, no un segundo poller. Alerta en dos condiciones: status saliendo de healthy en cualquiera de los feeds, y live_write_age_ms o prematch.write_age_ms cruzando tu presupuesto de frescura. Ambas edades normalmente están muy por debajo de un segundo, así que una lectura en las decenas de miles ya es una historia.
Dos sutilezas mantienen las alertas honestas. Trata unreachable de prepartido como desconocido, no como caído: significa que el propio health check no pudo alcanzar el servicio de prepartido mientras los datos pueden estar bien. Y compara version con el cursor que tu poller guardó por última vez, porque cursores iguales prueban que tu pipeline lee el mismo feed que la página de estado describe. Para balanceadores de carga y sondas de uptime que no pueden enviar un encabezado de autenticación, /ping es público y devuelve ok en texto plano.
Cuando el feed se degrada
Una lectura degradada es razón para aguantar, no para martillar. Sigue sirviendo el último snapshot bueno con su edad visible, amplía tu intervalo de sondeo para no sumar carga mientras el feed se recupera, y deja que los números de frescura de la siguiente llamada a /health decidan cuándo ajustar de nuevo. Llama a una persona solo cuando la degradación supere la tolerancia que tu producto anunció.
Este endpoint vigila la fuente; tu propio pipeline aún necesita sus cinco métricas del lado del consumidor en la guía de monitoreo de pipeline, y un período degradado puede aparecer como respuestas de error normales, que el runbook de errores cubre. La página de estado en la guía de SSE de pnclPULSE es la referencia de cómo se ve un stream sano con el tiempo.
Preguntas que esto plantea
¿/health está autenticado?
Sí, acepta la misma clave de API de cualquier otro endpoint, en el encabezado o en el parámetro key. /ping es el público, pensado para sondas que no pueden enviar credenciales.
¿Con qué frecuencia debo sondear /health?
Una vez por minuto por entorno basta. Cada llamada cuenta como una solicitud en tu plan, así que cinco paneles sondeando cada cinco segundos suman cuota real sin señal extra.
¿Prepartido unreachable significa prepartido caído?
No. Significa que el health check no pudo alcanzar el servicio de prepartido; los datos en sí pueden estar bien. Trata la lectura como desconocida y confirma con la frescura de tu propio sondeo de prepartido.
¿Puedo confiar solo en el estado de nivel superior?
No. Describe solo el feed en vivo. Una caída de prepartido nunca lo mueve, así que observa prematch.status y prematch.write_age_ms como series separadas.
Los campos de estado y el comportamiento de los endpoints siguen la documentación publicada del proveedor, verificada el 29 de octubre de 2026. Publicado el .