Cómo funcionan las alarmas de registro Ciclo de vida de las consultas programadas administradas Configuración de las alarmas de registro Consulta de registros Expresiones de agregación Alarmas con varios colaboradores Tratamiento de datos que faltan Estados de evaluación Actualización de alarmas Acciones y notificaciones Prácticas recomendadas y solución de problemas

Alarmas de registro

Una alarma de registro supervisa los resultados de una consulta de Información de registros de CloudWatch que se ejecuta según una programación mediante una Consulta programada. La alarma aplica una expresión de agregación a los resultados de la consulta para generar un valor numérico. Cuando ese valor agregado supera un umbral configurado, la alarma pasa al estado ALARM y ejecuta las acciones configuradas.

A diferencia de las alarmas de métricas, que requieren filtros de métricas como paso intermedio, las alarmas de registro evalúan directamente los datos de registro mediante el mismo lenguaje de consulta de Información de registros que se utiliza para los análisis ad hoc.

Cómo funcionan las alarmas de registro

Los siguientes pasos describen cómo funciona una alarma de registro:

Se crea una alarma de registro con una consulta, una expresión de agregación, una programación y un umbral.
CloudWatch crea automáticamente una consulta programada administrada por AWS que ejecuta la consulta según la programación especificada.
Cada ejecución de la consulta genera resultados agregados, ya sea un único valor o varios valores de colaboradores.
CloudWatch evalúa los resultados agregados con respecto al umbral mediante una evaluación de M de N aplicada a las ejecuciones recientes de la consulta.
Si se supera el umbral, la alarma pasa al estado ALARM y ejecuta las acciones configuradas, como las notificaciones de Amazon SNS.

nota

Las alarmas de registro evalúan las N ejecuciones más recientes de la consulta. La alarma pasa al estado ALARM cuando M de esas N ejecuciones superan el umbral.

Para crear una alarma de registro, consulte Creación de una alarma de registro.

Ciclo de vida de las consultas programadas administradas

Cuando se crea una alarma de registro, CloudWatch crea automáticamente una consulta programada administrada por AWS que ejecuta la consulta según la programación especificada. No es necesario crear la consulta programada por separado.

La consulta programada administrada por AWS tiene las siguientes características:

Se muestra en la consola de Registros de CloudWatch, en Consultas programadas.
No se puede modificar directamente. Para cambiar la consulta o su configuración, actualice la alarma de registro.
CloudWatch elimina la consulta programada administrada por AWS cuando se elimina la alarma.

Configuración de las alarmas de registro

Una alarma de registro se configura con los siguientes parámetros:

QueryString es la consulta de Información de registros de CloudWatch que se ejecutará.
LogGroupIdentifiers son los grupos de registros que se consultarán. Especifique los nombres o los ARN de los grupos de registro.
ScheduledQueryRoleARN es el ARN del rol de IAM que permite que Registros de CloudWatch ejecute la consulta programada en su nombre.
AggregationExpression define cómo se agregan los resultados de la consulta para obtener un valor numérico que se utilizará en la evaluación del umbral.
ScheduleExpression define la frecuencia con la que se ejecuta la consulta, por ejemplo, rate(5 minutes).
StartTimeOffset define, en segundos, el período retrospectivo de cada ejecución de la consulta.
EndTimeOffset define el final del intervalo de tiempo de la consulta como un desplazamiento, en segundos, con respecto a la hora actual.
ComparisonOperator define cómo se comparan los resultados agregados con el umbral. Valores válidos: GreaterThanThreshold, GreaterThanOrEqualToThreshold, LessThanThreshold, LessThanOrEqualToThreshold.
Threshold es el valor numérico con el que se realiza la comparación.
QueryResultsToEvaluate es el número de ejecuciones recientes de la consulta que se evaluarán, es decir, N en la evaluación de M de N.
QueryResultsToAlarm es el número de resultados que deben superar el umbral para activar ALARM, es decir, M en la evaluación de M de N.
TreatMissingData define cómo se tratan los resultados faltantes de la consulta durante la evaluación.

Para consultar la lista completa de parámetros y las instrucciones de creación, consulte Creación de una alarma de registro.

Consulta de registros

La consulta de la alarma de registros es una consulta de Información de registros de CloudWatch que selecciona y filtra los datos de registro que se evaluarán. La consulta se ejecuta en los grupos de registro especificados en LogGroupIdentifiers durante el intervalo de tiempo definido por StartTimeOffset y EndTimeOffset.

La consulta utiliza la sintaxis de consulta de Información de registros de CloudWatch. Para consultar las directrices sobre cómo escribir consultas eficientes para las alarmas de registros, consulte Prácticas recomendadas y solución de problemas.

Expresiones de agregación

La expresión de agregación define cómo CloudWatch resume los resultados de la consulta en un valor numérico para evaluar el umbral. La expresión utiliza la misma sintaxis que el comando stats de Información de registros de CloudWatch.

La sintaxis de una expresión de agregación es la siguiente:


statistic_func_expression [by field1, field2, ...] [| sort asc|desc]

Solo se puede especificar una expresión de agregación. En la siguiente tabla se enumeran las funciones de agregación compatibles.

Funciones de agregación compatibles
Función	Descripción	Ejemplo
`count(*)`	Recuento de todas las líneas de registro coincidentes.	`count(*)`
`avg(field)`	Valor promedio del campo especificado.	`avg(duration)`
`sum(field)`	Suma del campo especificado.	`sum(bytesSent)`
`min(field)`	Valor mínimo del campo especificado.	`min(latency)`
`max(field)`	Valor máximo del campo especificado.	`max(latency)`

La función bin() no se admite en la cláusula by de la expresión de agregación. Sin embargo, puede utilizar bin() en la propia cadena de consulta.

Alarmas con varios colaboradores

Cuando se incluye una cláusula by en la expresión de agregación, la alarma evalúa de forma independiente cada combinación única de valores de campo, denominada colaborador. La alarma pasa al estado ALARM si algún colaborador supera el umbral.

Por ejemplo, la siguiente expresión agrupa los recuentos de errores por nombre de servicio:


count(*) by serviceName

Cada valor único de serviceName se evalúa de forma independiente con respecto al umbral. Si algún servicio supera el umbral en M de N ejecuciones de la consulta, la alarma pasa al estado ALARM.

Los siguientes límites se aplican a las alarmas con varios colaboradores:

Un máximo de 5 campos en la cláusula by.
Un máximo de 500 resultados de colaboradores por ejecución de la consulta.
Un máximo de 100 colaboradores pueden tener seguimiento simultáneo en el estado ALARM.

De forma predeterminada, los colaboradores se ordenan alfabéticamente y solo se devuelven los primeros 500 en cada ejecución de la consulta. Para ordenar los colaboradores por su valor agregado, especifique | sort asc o | sort desc en la expresión de agregación, por ejemplo, avg(latency) by serviceName | sort desc. La clasificación por valor garantiza que los colaboradores más significativos se evalúen primero cuando el total supere los 500.

En las alarmas con varios colaboradores, las acciones de Amazon SNS y Lambda se ejecutan a nivel de colaborador, una vez por cada colaborador que supere el umbral. Las acciones de OpsItem de Systems Manager se ejecutan a nivel de alarma.

nota

Las alarmas de registro no admiten las acciones del Administrador de incidentes de Systems Manager ni las acciones de investigación.

Si un colaborador deja de aparecer en los resultados de la consulta, por ejemplo, porque se termina un recurso efímero, pasa al estado OK independientemente de la configuración del tratamiento de los datos faltantes.

Tratamiento de datos que faltan

Se producen datos faltantes cuando la ejecución de una consulta programada no genera un valor que se pueda evaluar con respecto al umbral. Esto sucede en los siguientes casos:

No hay registros: el grupo de registro no contiene eventos de registro dentro del intervalo de tiempo de la consulta.

La consulta no devuelve resultados aplicables: hay registros, pero la expresión de agregación no puede generar un valor. Esto ocurre cuando:

No hay resultados de consulta coincidentes según el filtro de la consulta.
El campo al que se hace referencia en la expresión de agregación no estaba presente en los resultados de la consulta. Por ejemplo, count(error-codes), donde error-codes no existe en los eventos de registro devueltos.

Tenga en cuenta que count(*) aplicado a un conjunto de resultados vacío devuelve 0, que es un punto de datos válido y no se trata como faltante.

Puede configurar la forma en que la alarma trata los datos faltantes mediante el parámetro TreatMissingData. En la siguiente tabla se describen las opciones disponibles.

Opciones de tratamiento de los datos faltantes
Valor	Comportamiento
`missing`	Tratar el punto de datos como faltante. Esta es la opción predeterminada.
`notBreaching`	Tratar el punto de datos faltante como si no superara el umbral.
`breaching`	Tratar el punto de datos faltante como si superara el umbral.
`ignore`	Ignorar el punto de datos faltante y evaluar únicamente los datos disponibles.

Estados de evaluación

Además de los estados estándar OK, ALARM y INSUFFICIENT_DATA, las alarmas de registro pueden informar de los siguientes estados de evaluación en el campo EvaluationState. Estos estados proporcionan contexto adicional sobre el motivo por el que la alarma se encuentra en su estado actual.

Estados de evaluación de las alarmas de registro
Estado	Descripción
`EVALUATION_FAILURE`	Un problema transitorio del servicio de CloudWatch impidió la evaluación. Esto puede ocurrir cuando el servicio tiene problemas para evaluar los resultados de la consulta debido a errores del servicio o cuando fallan algunos de los resultados de la consulta, pero no todos. La alarma pasa al estado `INSUFFICIENT_DATA`. Se recomienda realizar una supervisión manual hasta que se resuelva el problema.
`EVALUATION_ERROR`	Un error de configuración del cliente impidió la evaluación. Esto puede ocurrir debido a permisos insuficientes, una consulta no válida o cuando fallan todos los resultados de la consulta. La alarma pasa inmediatamente al estado `INSUFFICIENT_DATA`. Consulte el campo `StateReason` para obtener más información.
`PARTIAL_DATA`	La consulta devolvió el máximo de 500 grupos de colaboradores, pero había más coincidencias. La alarma evalúa los colaboradores disponibles, pero es posible que los resultados estén incompletos.

Actualización de alarmas

Cuando se actualizan la consulta, la expresión de agregación, la programación o los grupos de registro de una alarma de registro, la alarma pasa al estado INSUFFICIENT_DATA hasta que se recopilan suficientes puntos de datos nuevos. Los cambios en el umbral o en los valores de M de N no desencadenan este restablecimiento.

Acciones y notificaciones

Las alarmas de registro admiten las siguientes acciones:

Notificaciones de Amazon SNS
Invocaciones de funciones de Lambda
Creación de un OpsItem en Systems Manager

Para consultar la matriz completa de compatibilidad con las acciones, consulte Acciones de la alarma.

Cuando cambia el estado de una alarma de registro, la notificación de la acción incluye la siguiente información:

Información estándar sobre los cambios en la configuración de la alarma, como el nombre, la descripción y los detalles de configuración.
Información sobre el cambio de estado, como el nuevo estado, el motivo del estado y la marca de tiempo.
Las notificaciones por correo electrónico de Amazon SNS también incluyen un enlace directo a la consola de Información de registros de CloudWatch, donde se muestran los resultados completos de la consulta.

El siguiente ejemplo muestra una notificación por correo electrónico de Amazon SNS para una alarma de registro de un solo valor, sin una cláusula BY:


{
    "AlarmName": "HighErrorCount",
    "NewStateValue": "ALARM",
    "NewStateReason": "Threshold Crossed: 3 out of the last 5 query results [142.0 (10/06/26 12:15:00), 135.0 (10/06/26 12:10:00), 120.0 (10/06/26 12:05:00)] were greater than the threshold (100.0) (minimum 3 datapoints for OK -> ALARM transition).",
    "NewStateReasonData": {
        "version": "1.0",
        "queryDate": "2026-06-10T12:15:30.000+0000",
        "threshold": 100.0,
        "queryResultsToEvaluate": 5,
        "queryResultsToAlarm": 3,
        "results": [
            {
                "queryResultId": "scheduled-query-execution-id-3",
                "status": "COMPLETE",
                "timestamp": "2026-06-10T12:15:00.000+0000",
                "value": 142.0
            }
            // Additional results...
        ]
    },
    "StateChangeTime": "2026-06-10T12:15:30.000+0000",
    "OldStateValue": "OK"
    // Additional fields...
}

El siguiente ejemplo muestra una notificación por correo electrónico de Amazon SNS para una alarma de registro con varios colaboradores, con una cláusula BY. Cada colaborador que supera el umbral genera una notificación independiente:


{
    "AlarmName": "EndpointLatency",
    "NewStateValue": "ALARM",
    "NewStateReason": "5 out of 10 contributors evaluated to ALARM",
    "StateChangeTime": "2026-06-10T12:20:15.000+0000",
    "OldStateValue": "OK",
    "AlarmContributorId": "a1b2c3d4e5f6g7h8",
    "AlarmContributorAttributes": {
        "endpoint": "/api/orders"
    }
    // Additional fields...
}

Inclusión de líneas de registro en las notificaciones

De manera opcional, puede incluir en las notificaciones de alarma las líneas de registro sin procesar de los resultados de la consulta. Para ello, establezca el parámetro ActionLogLineCount en un valor comprendido entre 1 y 50. Estas líneas corresponden a los eventos de registro subyacentes sobre los que se evalúa la expresión de agregación, no a los valores agregados. El valor predeterminado es 0, lo que significa que no se incluye ninguna línea de registro.

nota

Las líneas de registro solo se incluyen en las notificaciones por correo electrónico de Amazon SNS. Las cargas útiles de las acciones de Lambda no incluyen líneas de registro.

importante

La inclusión de líneas de registro en las notificaciones podría exponer información confidencial de los registros en los mensajes de Amazon SNS. Revise el contenido de los registros antes de habilitar esta característica.

Para incluir líneas de registro, el rol de líneas de registro debe tener el permiso logs:GetQueryResults. El número de líneas de registro incluidas en una notificación está limitado por la cantidad solicitada, el total de resultados disponibles y el límite de tamaño de la carga útil de Amazon SNS.

Prácticas recomendadas y solución de problemas

Prácticas recomendadas

Optimización de consultas

Pruebe manualmente las consultas en Información de registros de CloudWatch antes de utilizarlas en una alarma de registro, a fin de comprobar su rendimiento y verificar que produzcan los resultados esperados.
Utilice comandos de filtrado al principio de la consulta para reducir el volumen de datos procesados.
Limite el intervalo de tiempo de las consultas mediante el ajuste de la hora de inicio con StartTimeOffset, a fin de evitar que se agote el tiempo de espera en grupos de registro con grandes volúmenes de datos.
Utilice índices de campos para optimizar el rendimiento de las consultas.

Planificación de la programación

Elija una frecuencia de programación que permita que las consultas finalicen antes de la siguiente ejecución. En el caso de los grupos de registro con un gran volumen de datos, utilice intervalos más largos, por ejemplo, 10 minutos en lugar de 5.
Tenga en cuenta los retrasos en la ingesta de registros al establecer el desplazamiento de la hora de inicio (StartTimeOffset). Un breve intervalo entre el desplazamiento de la hora de finalización (EndTimeOffset) y la hora actual ayuda a evitar que se evalúen datos incompletos.
Distribuya las programaciones de las alarmas de registro en la cuenta para evitar alcanzar los límites de simultaneidad de las consultas programadas. El número de ejecuciones simultáneas de consultas en la cuenta no puede superar 100. Tenga en cuenta esta cuota al crear varias alarmas de registro con programaciones que se superpongan.

Ajuste de los umbrales

Comience con valores más altos para Resultados de la consulta que se evaluarán (N) a fin de reducir el ruido de las alarmas provocado por picos transitorios.
Para eventos poco frecuentes, como errores que rara vez se producen, establezca Tratamiento de los datos faltantes en notBreaching para que la alarma permanezca en el estado OK cuando no coincida ningún registro.
Para señales continuas, como los registros de tráfico, considere establecer Tratamiento de los datos faltantes en breaching para detectar cuándo dejan de recibirse los datos de registro esperados.

Diseño con varios colaboradores

Elija campos significativos para la cláusula BY que representen recursos o dimensiones distintos que desee supervisar de forma independiente.
Tenga en cuenta que solo se devuelven los primeros 500 colaboradores en cada ejecución de la consulta. Si espera obtener más resultados, restrinja la consulta o utilice menos campos en la cláusula BY.
Utilice el sufijo | sort desc o | sort asc en la expresión de agregación para priorizar los valores más altos o más bajos, según el operador de comparación, cuando se alcance el límite de 500 colaboradores.

Solución de problemas

La alarma permanece en INSUFFICIENT_DATA

Causa posible	Resolución
Al rol de ejecución de la consulta programada le faltan permisos	Compruebe que el rol tenga los permisos `logs:StartQuery`, `logs:StopQuery`, `logs:GetQueryResults` y `logs:DescribeLogGroups`, con el ámbito limitado a los grupos de registro correctos.
El grupo de registro no existe o se eliminó	Compruebe que los ARN de los grupos de registro especificados en la configuración de la alarma sean correctos y que se pueda acceder a ellos.
Alarma creada o actualizada recientemente	Después de crear la alarma o actualizar su configuración, esta permanece en INSUFFICIENT_DATA hasta que finalicen suficientes ejecuciones de la consulta para satisfacer el período de evaluación de M de N.
La consulta programada no se ejecuta	Compruebe la consulta programada administrada por AWS en la consola de Registros de CloudWatch para verificar que se ejecute según la programación.
El campo de agregación no está presente en los resultados de la consulta	El campo al que se hace referencia en la expresión de agregación debe estar presente en los resultados de la consulta. Por ejemplo, si la agregación es `avg(latency)`, asegúrese de que la consulta genere un campo `latency`. Si el campo no está presente, el resultado se trata como dato faltante.
Retraso en la ingesta de registros	Una consulta programada solo puede evaluar los eventos de registro que ya se hayan ingerido en el momento de su ejecución. `StartTimeOffset` y `EndTimeOffset` definen el intervalo de la consulta con respecto a la hora de ejecución T: [T − StartTimeOffset, T − EndTimeOffset]. Sin embargo, no tienen en cuenta el retraso en la ingesta. Si todavía se están ingiriendo eventos correspondientes al intervalo consultado, la consulta se ejecuta antes de que estén disponibles y los omite. Utilice `EndTimeOffset` para desplazar el intervalo hacia atrás lo suficiente como para que la ingesta haya finalizado en todo el intervalo. Ejemplo: suponga que los registros tardan hasta 2 minutos en estar disponibles para las consultas después de que se produzcan los eventos. `StartTimeOffset=60, EndTimeOffset=0`: intervalo [T − 60 s, T]. El intervalo finaliza en el momento de la ejecución, por lo que los eventos recientes aún no se han ingerido y se omiten. `StartTimeOffset=180, EndTimeOffset=120`: intervalo [T − 180 s, T − 120 s]. El intervalo finaliza 2 minutos antes del momento de la ejecución. Para entonces, todos los eventos ya se han ingerido y se pueden evaluar.

La alarma muestra EVALUATION_ERROR

Esto indica un problema de configuración del cliente. Consulte el campo StateReason para obtener más información. Causas comunes:

La sintaxis de la consulta no es válida o presenta errores de formato.
El rol de ejecución de la consulta programada no dispone de permisos suficientes.
Todas las ejecuciones de la consulta fallaron, por ejemplo, porque se revocaron los permisos del grupo de registro.

La alarma muestra EVALUATION_FAILURE

Esto indica un problema transitorio del servicio de CloudWatch. La alarma se recupera automáticamente cuando se resuelve el problema. Si el problema persiste durante más de unos minutos, consulte el panel de estado del servicio de CloudWatch.

La alarma muestra PARTIAL_DATA

La consulta devolvió el máximo de 500 grupos de colaboradores, pero había más coincidencias. La alarma evalúa los colaboradores disponibles, pero es posible que los resultados estén incompletos. Considere restringir la consulta o reducir el número de campos de la cláusula BY.

Las líneas de registro no aparecen en las notificaciones

Compruebe que ActionLogLineCount esté establecido en un valor entre 1 y 50.
Compruebe que el rol de las líneas de registro tenga el permiso logs:GetQueryResults, con el ámbito limitado a los grupos de registro correctos.
Las líneas de registro solo se incluyen en las notificaciones por correo electrónico de Amazon SNS. Los demás tipos de acciones no incluyen líneas de registro.
Las consultas que utilizan unmask() no pueden incluir líneas de registro en las notificaciones y se rechazan durante la creación.

Para consultar otras prácticas recomendadas sobre la optimización de consultas, la supervisión y la autorización, consulte Prácticas recomendadas para las consultas programadas en la Guía del usuario de Registros de Amazon CloudWatch.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Alarmas PromQL

Alarmas compuestas