Cómo evalúa Telemetry las alertas de SQL

Una alerta útil es más que un umbral adjunto a un gráfico. El evaluador debe decidir cuándo vence una consulta, qué SQL ejecutar, qué filas cuentan, cómo reducir esas filas a un valor, si el estado cambió y cuándo notificar.

Esta guía documenta la ruta de evaluación implementada por Telemetry. Es una descripción de comportamiento inspeccionable, no una garantía de tiempo de actividad, latencia o entrega.

Modelo de entrada de alerta: una señal de serie temporal

El flujo de trabajo de creación de alertas de Telemetry comienza intencionalmente desde una línea: un eje de tiempo ordenado, un eje de valores numéricos y sin dimensión de agrupación o división. Explorar requiere un gráfico de líneas sin Dividir por. Los resultados de SQL requieren un gráfico de líneas con un eje x de tiempo explícito, un eje y numérico y Agrupar porestablecido enNinguno.

Esta restricción mantiene comprensible la información del evaluador. Cada fila de resultados es un punto en el tiempo, la métrica seleccionada tiene un significado y una unidad, y el umbral configurado produce un estado de alerta. Un resultado de varias series requeriría una política adicional: si alguna o todas las series controlan el estado, si cada serie posee un historial independiente, cómo se agrupan las notificaciones y qué significa una serie faltante o que aparece recientemente. Telemetry evita inventar esa semántica implícitamente.

El SQL que calcula la señal aún puede resultar complejo. Puede unir tablas, filtrar a un servicio o ruta específica, calcular una proporción o imponer un tamaño de muestra mínimo. El resultado final expuesto a la alerta debe ser simple: un período de tiempo y una señal numérica por fila. Mantenga comparaciones agrupadas en un panel o cree alertas separadas cuando cada grupo tenga su propio umbral, propietario y respuesta.

Secuencia de evaluación

El evaluador utiliza un ciclo de programación encadenado de un minuto. Cada paso carga alertas habilitadas, las evalúa simultáneamente con el manejo de fallas aisladas, registra el resultado del paso y programa el siguiente paso después de que finalice el paso actual. El ciclo de un minuto es una cadencia de encuesta; Cada alerta todavía tiene su propio intervalo configurado.

Por cada alerta habilitada:

1. Verifique si la alerta vence desde su última hora de evaluación y el intervalo configurado.
2. Reclame la alerta utilizando su versión actual para que otro evaluador no pueda reclamar la misma versión al mismo tiempo.
3. Resuelva la consulta: use el SQL guardado exactamente para una alerta respaldada por consulta o regenere el SQL desde la configuración de Explore almacenada.
4. Rechazar SQL respaldado por consultas que contengan declaraciones de escritura.
5. Ejecute la consulta e inspeccione las columnas y filas de resultados.
6. Opcionalmente, elimine la fila más nueva cuando represente un período de tiempo incompleto.
7. Tome el número configurado de puntos recientes y agréguelos en un valor observado.
8. Compare ese valor con el umbral y el operador.
9. Almacene el nuevo estado, el valor observado, el tiempo de evaluación y cualquier error controlado.
10. Agregue el historial e intente la entrega de correo electrónico solo cuando el estado cambie.

Esta secuencia es importante a la hora de solucionar problemas. Una consulta válida aún puede no producir ningún valor utilizable, un valor utilizable puede permanecer por debajo del umbral y un umbral superado puede permanecer en silencio cuando la alerta ya se estaba activando.

Consulta guardada y Explorar fuentes

Una alerta respaldada por consulta ejecuta el SQL guardado con la alerta. El evaluador no la reemplaza silenciosamente con una revisión de consulta más nueva. Revise el SQL adjunto a la alerta cuando un panel y una alerta parezcan no coincidir.

Una alerta respaldada por Explore almacena la configuración de Explore y regenera SQL a través del mismo límite de creación de consultas utilizado por Explore. Por lo tanto, los cambios en el esquema, los filtros, la agrupación o la agregación pueden afectar la resolución de la configuración almacenada.

Las declaraciones orientadas a escritura se rechazan para las alertas respaldadas por consultas. Las alertas están destinadas a observar resultados, no a mutar tablas o estados administrativos. Mantenga la alerta SQL limitada por el tiempo y el tamaño del resultado incluso cuando el SQL sea de solo lectura.

Exclusión de puntos más recientes

Las consultas con intervalos de tiempo normalmente devuelven primero el intervalo actual incompleto. Comparar ese minuto u hora parcial con un segmento histórico completo puede crear señales falsas de recuperación o infracción.

Cuando exclude latest incomplete point está habilitado, el evaluador ordena las filas más nuevas primero y elimina la fila de resultados más reciente antes de seleccionar el número de puntos configurado. Esa configuración es correcta solo cuando cada fila realmente representa un período de tiempo y la fila más nueva está incompleta.

No lo habilite para un agregado de una sola fila como:

SELECT
  100.0 * SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) / COUNT(*) AS failure_rate
FROM background_job_completed
WHERE completed_at >= now() - INTERVAL '15 minutes';

Eliminar la única fila no deja ningún valor para evaluar. Para una serie temporal, devuelva una columna de depósito explícita y una columna de valor numérico:

SELECT
  date_bin(INTERVAL '5 minutes', completed_at, TIMESTAMP '1970-01-01') AS bucket,
  100.0 * SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) / COUNT(*) AS failure_rate
FROM background_job_completed
WHERE completed_at >= now() - INTERVAL '35 minutes'
GROUP BY bucket
ORDER BY bucket DESC;

Selección y agregación de puntos.

Después del manejo de los puntos más recientes, el evaluador toma el número configurado de filas recientes. Extrae el valor numérico seleccionado y reduce esos puntos utilizando la configuración de agregación de alertas.

Utilice un único punto cuando el SQL ya calcule la ventana de decisión completa. Utilice varios puntos cuando la alerta requiera intencionalmente persistencia en varios depósitos. La agregación debe coincidir con la pregunta operativa:

• maximum pregunta si se incumplió algún punto seleccionado.
• minimum pregunta si cada punto seleccionado permaneció por encima de un piso.
• average suaviza la variación corta pero puede ocultar un punto grave.
• sum ajusta los recuentos acumulados en depósitos que no se superponen.
• latest utiliza el punto completo restante más nuevo.

Documente esta elección en el procedimiento de respuesta. La “tasa de fallas superior a 5” es ambigua a menos que el equipo sepa si eso significa el último segmento de cinco minutos, el promedio de tres segmentos o el máximo de esos segmentos.

Transiciones de estado y notificaciones

Telemetry almacena el estado de alerta por separado de una única evaluación. Una evaluación exitosa puede producir ok o firing; un problema de ejecución, extracción o configuración produce un resultado de error.

El historial y las notificaciones están orientados a la transición. Un movimiento de ok a firing crea una transición de activación. Un cambio de firing a ok crea una transición de resolución. Las evaluaciones repetidas en el mismo estado actualizan el registro de evaluación sin enviar el mismo correo electrónico de transición en cada pase de votación.

La entrega de notificación actual para este evaluador es por correo electrónico. La entrega se intenta después de que se almacena la transición de estado. Un error en la entrega no debe borrar el hecho de que la alerta realizó la transición, por lo que el historial de alertas y la entrega de correo electrónico deben investigarse por separado.

Comportamiento de simultaneidad y reclamos

Cada alerta se reclama con una simultaneidad optimista utilizando su versión actual. Si la versión ha cambiado u otro evaluador ya reclamó esa versión, el reclamo no prospera. Esto evita que dos evaluadores procesen conscientemente la misma versión de alerta al mismo tiempo.

El programador evalúa el conjunto de alertas habilitadas con promesas establecidas, por lo que una alerta rechazada no impide que se completen las alertas restantes en esa pasada. El bucle programa el siguiente pase solo después de que el pase actual se haya asentado, evitando la superposición de pases dentro de un proceso.

Estos controles explican el comportamiento del evaluador; no son una afirmación de disponibilidad de servicios distribuidos. La topología de implementación, los reinicios de procesos, el comportamiento del proveedor de correo electrónico y los futuros cambios de implementación aún pertenecen a la revisión operativa.

Lista de verificación de solución de problemas

Cuando una alerta no se comporta como se esperaba:

1. Ejecute exactamente el SQL adjunto y confirme que sea de solo lectura.
2. Compruebe que la columna de valor seleccionada sea numérica y exista en cada fila relevante.
3. Inspeccionar el orden de resultados; La lógica del punto más nuevo depende de saber qué fila es la más nueva.
4. Confirme si la consulta devuelve una fila agregada o varios períodos de tiempo.
5. Revise exclude latest incomplete point, el recuento de puntos y la agregación juntos.
6. Verifique que el operador y el umbral utilicen la misma unidad que el valor seleccionado.
7. Consulte el historial de alertas para conocer la transición de estado más reciente y el error controlado.
8. Separe los errores de consulta/evaluación de los errores de entrega de correo electrónico.
9. Confirme que la alerta esté habilitada y que haya transcurrido suficiente tiempo para el intervalo configurado.
10. Pruebe con un dispositivo de evento sintético a ambos lados del umbral.

Para una investigación específica de la entrega, continúe con Solución de problemas de entrega de alertas. Para el diseño de eventos y consultas, utilice Alertas y Cree su primer panel y alerta.

Límite de interpretación

El evaluador puede ejecutar la decisión configurada de forma coherente, pero no puede decidir si la definición empresarial es correcta. El grano del evento, el denominador, la ventana de tiempo, el umbral, la política de datos faltantes y el propietario de la respuesta siguen siendo parte del contrato de alerta.

Vuelva a revisar una alerta después de cambios de esquema, ediciones de consultas, cambios de versiones, cambios de tráfico y retrospectivas de incidentes. Una alerta técnicamente funcional con un umbral o denominador obsoleto sigue siendo una alerta poco fiable.