Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Comprender los conceptos de las consultas programadas

Antes de crear consultas programadas, comprenda estos conceptos clave que afectan a la forma en que se ejecutan las consultas y al lugar en el que se entregan los resultados.

Separación de funciones de IAM

Las consultas programadas requieren dos funciones de IAM independientes: una para ejecutar las consultas y otra para entregar los resultados a destinos como los buckets de Amazon S3, los buses de EventBridge eventos de Amazon o las tablas de búsqueda. Entender por qué existe esta separación le ayuda a configurar los permisos correctamente y a aprovechar las ventajas operativas y de seguridad que proporciona.

La arquitectura de dos funciones divide las responsabilidades entre el acceso a los datos y la entrega de datos. La función de ejecución de consultas accede a los datos de registro y ejecuta las consultas, mientras que la función de entrega en destino escribe los resultados en el destino elegido. Esta separación sigue el principio de privilegios mínimos: cada rol solo tiene los permisos que necesita para su función específica.

Esta separación proporciona beneficios prácticos para sus operaciones. Desde el punto de vista de la seguridad, si necesita cambiar el lugar donde se entregan los resultados, solo debe modificar la función de entrega en destino sin cambiar los permisos de ejecución de las consultas. Para el cumplimiento y la auditoría, puede realizar un seguimiento claro de qué rol accede a los datos de registro confidenciales y qué rol escribe en sistemas externos. Esto facilita la demostración de que su infraestructura de análisis de registros sigue las prácticas recomendadas de seguridad.

Cross-region y el uso entre cuentas

Se crea una consulta programada en una región específica y se ejecuta en esa región. Sin embargo, puede consultar los grupos de registros y ofrecer resultados en todas las regiones y cuentas. Debes configurar una o más AWS cuentas como cuentas de supervisión y vincularlas con varias cuentas de origen. Una cuenta de monitoreo es una AWS cuenta central que puede ver e interactuar con los datos de observabilidad generados a partir de las cuentas de origen. Una cuenta de origen es una AWS cuenta individual que genera datos de observabilidad para los recursos que residen en ella. Las cuentas de origen comparten sus datos de observabilidad con la cuenta de supervisión. Por lo tanto, puede configurar las consultas programadas desde la cuenta de supervisión utilizando los grupos de registro de todas las cuentas vinculadas.

Enfoque alternativo: utilice la centralización de los CloudWatch registros para replicar los datos de registro de varias cuentas y regiones en una cuenta de supervisión central. Esto le permite crear consultas programadas en una sola región para acceder a todos sus registros centralizados, lo que evita las consultas entre regiones y simplifica la administración de los permisos de IAM.

Programe las expresiones y la gestión de las zonas horarias

La programación que defina determina cuándo se ejecuta la consulta y con qué frecuencia. La elección de la expresión de programación correcta afecta a la hora de recibir los resultados y a la cantidad de datos que se consultan. Comprender los tipos de expresiones le ayuda a elegir entre simplicidad y precisión.

Las expresiones de Cron proporcionan un control preciso sobre el tiempo, lo que permite especificar las horas, los días de la semana o los días del mes exactos. Usa expresiones cron cuando necesites que las consultas se ejecuten en un horario laboral específico o se ajusten a los cronogramas operativos. En la consola también puedes programar consultas mediante sencillas opciones de calendario.

Todas las consultas programadas se ejecutan en UTC, independientemente de tu zona horaria local o de dónde se encuentren tus AWS recursos. Esto es especialmente importante a la hora de programar las consultas para el horario laboral o para realizar análisis en función del tiempo. Por ejemplo, si tu empresa opera en el horario del este de EE. UU. y quieres recibir un informe diario a las 9 a. m. ET, debes tener en cuenta la diferencia UTC (a las 14:00 UTC durante el horario de verano, a las 13:00 UTC en caso contrario). Planifica tus expresiones de programación teniendo en cuenta el horario UTC para asegurarte de que las consultas se ejecuten a la hora prevista.

Cómo elegir un idioma de consulta

Las consultas programadas admiten tres lenguajes de consulta diferentes, y tu elección afecta tanto a la forma en que escribes las consultas como a la facilidad con la que tu equipo puede mantenerlas. El idioma correcto depende de tus requisitos de análisis y de las habilidades actuales de tu equipo.

Si se dedica principalmente a filtrar y agregar datos de registro, el lenguaje de consulta de CloudWatch Logs Insights ofrece la sintaxis más sencilla. En el caso de transformaciones de datos complejas en las que es necesario remodelar o enriquecer los datos mediante varios pasos, el enfoque de canalización de PPL facilita el seguimiento de la lógica. Cuando necesite realizar combinaciones o agregaciones complejas similares a las operaciones de bases de datos, SQL proporciona una sintaxis familiar que los equipos con experiencia en bases de datos pueden adoptar rápidamente.

Selección de destinos y casos de uso

El lugar donde envías los resultados de las consultas determina lo que puedes hacer con ellos. Esta elección da forma a todo su flujo de trabajo posterior, ya sea que esté creando análisis a largo plazo, activando respuestas automatizadas o ambas cosas. Comprender los puntos fuertes de cada tipo de destino le ayuda a diseñar la arquitectura adecuada para su caso de uso.

Los destinos de Amazon S3 están optimizados para el almacenamiento y el procesamiento por lotes. Si necesita conservar los resultados de las consultas durante meses o años, analizar las tendencias a lo largo del tiempo o introducir datos en plataformas de análisis, Amazon S3 proporciona un almacenamiento rentable con retención ilimitada. EventBridge los destinos están optimizados para la automatización en tiempo real. Cuando los resultados de las consultas deben desencadenar acciones inmediatas (como enviar alertas, iniciar flujos de trabajo o actualizar sistemas), los resultados se obtienen EventBridge en forma de eventos a los que las aplicaciones pueden responder al instante. De forma predeterminada, todos los eventos de finalización de consultas se envían automáticamente como eventos al bus de eventos predeterminado, lo que permite la integración con los sistemas de procesamiento posteriores, las funciones de Lambda u otras arquitecturas basadas en eventos. Los resultados solo se publican en los destinos cuando la consulta se ejecuta correctamente. Los destinos de las tablas de búsqueda están optimizados para mantener actualizados los datos de referencia. El destino de una tabla de consulta rellena o actualiza automáticamente la tabla de consulta especificada con los resultados de la consulta en cada ejecución programada, de modo que otras consultas pueden hacer referencia a los datos más recientes con el lookup comando.

Formato y estructura de los resultados de las consultas

Las consultas programadas ofrecen los resultados en formato JSON, pero cada tipo de destino recibe una carga útil diferente. En el caso de un destino de tabla de consulta, los resultados de la consulta se convierten en el contenido de la tabla de consulta y cada ejecución reemplaza ese contenido. Para obtener más información, consulte Configurar los destinos de las tablas de búsqueda para las consultas programadas.

Los destinos de Amazon S3 reciben las filas de resultados de la consulta. Cada objeto contiene una matriz JSON con una entrada para cada fila del conjunto de resultados, y cada entrada asigna los nombres de los campos de salida de la consulta a sus valores. El objeto no contiene metadatos ni estadísticas de consulta, y omite el @ptr campo aunque la consulta lo solicite, porque ese campo solo se puede usar en la consola.

EventBridge los destinos reciben los metadatos de la consulta, incluidas las estadísticas de la consulta, pero no las filas de resultados. Para recuperar las filas de una consulta completada, llame GetQueryResults con el valor de queryId from the event.

El siguiente ejemplo muestra el evento en el que CloudWatch Logs publica EventBridge cuando se completa una consulta programada.

{
    "version": "0",
    "id": "be72061b-eca2-e068-a7e1-83e01d6fe807",
    "detail-type": "Scheduled Query Completed",
    "source": "aws.logs",
    "account": "123456789012",
    "time": "2025-11-18T11:31:48Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:logs:us-east-1:123456789012:scheduled-query:477b4380-b098-474e-9c5e-e10a8cc2e6e7"
    ],
    "detail": {
        "queryId": "2038fd57-ab4f-4018-bb2f-61d363f4a004",
        "queryString": "fields @timestamp, @message, @logStream\n| filter @message like /ERROR/\n| sort @timestamp desc\n| limit 10000",
        "logGroupIdentifiers": [
            "/aws/lambda/my-function"
        ],
        "status": "Complete",
        "startTime": 1763465460,
        "statistics": {
            "recordsMatched": 1842,
            "recordsScanned": 48325,
            "estimatedRecordsSkipped": 0,
            "bytesScanned": 12081250,
            "estimatedBytesSkipped": 0,
            "logGroupsScanned": 1,
            "resultCount": 1842
        }
    }
}

Esta consulta no se agrega y arroja menos filas limit de las 10 000, por lo que cada uno de los 1.842 eventos de registro coincidentes pasó a ser una fila de salida recordsMatched y resultCount son iguales. Una consulta que agrega, o una cuyo conjunto de resultados está truncado porlimit, produce un valor inferior a. resultCount recordsMatched Para obtener más información, consulte Descripción de RecordsScan, RecordsMatched y ResultCount.

Los elementos clave incluyen:

En la tabla siguiente se describe cada campo del statistics objeto. Para ver las definiciones de API de estos campos, consulte QueryStatistics.

Descripción de RecordsScan, RecordsMatched y ResultCount

Tres de las estadísticas de consulta cuentan cosas diferentes y compararlas directamente puede resultar engañoso. Cada una mide una etapa diferente del procesamiento de la consulta:

Cada etapa reduce los datos. Un comando como este stats combina muchos eventos de registro en una sola fila de salida, por lo que resultCount puede ser mucho más pequeño querecordsMatched. Un número grande recordsMatched con un número pequeño resultCount no significa que falten filas en el conjunto de resultados.

Ejemplo: agregación

La siguiente consulta cuenta los mensajes de error de cada secuencia de registros de un grupo de registros durante un período de una hora.

filter @message like /ERROR/
| stats count(*) as errorCount by @logStream

Si la consulta lee 1 500 000 eventos de registro, de los cuales 24 318 contienenERROR, y los eventos de registro coincidentes provienen de 12 flujos de registro, la consulta se completa con las siguientes estadísticas.

"statistics": {
    "recordsMatched": 24318,
    "recordsScanned": 1500000,
    "estimatedRecordsSkipped": 0,
    "bytesScanned": 450000000,
    "estimatedBytesSkipped": 0,
    "logGroupsScanned": 1,
    "resultCount": 12
}

statsproduce una fila para cada flujo de registro, resultCount es decir, 12 y 24.318. recordsMatched Los 12 valores de errorCount suman 24.318.

Ejemplo: filtro Post-aggregation

La siguiente consulta conserva solo los flujos de registro que produjeron más de 1000 errores.

filter @message like /ERROR/
| stats count(*) as errorCount by @logStream
| filter errorCount > 1000

El último filter comando se ejecuta después de la agrupación, por lo que elimina las filas del conjunto de resultados en lugar de registrar los eventos del escaneo. Si 3 de las 12 secuencias de registro tienen errorCount más de 1000, entonces resultCount es 3 en lugar de 12. recordsScannedy bytesScanned no cambien, porque la consulta lee los mismos datos de registro de cualquier manera.

Ejemplo: límite

Un limit comando se reduce resultCount sin ningún tipo de agregación. La siguiente consulta devuelve los 100 mensajes de error más recientes.

filter @message like /ERROR/
| sort @timestamp desc
| limit 100

Si la consulta analiza los mismos 1 500 000 eventos de registro y coincide con los mismos 24 318, entonces resultCount es 100, porque limit limita el conjunto de resultados a 100 filas. En la consola, verá esta relación como Mostrar 100 de los 24.318 registros coincidentes.

Cada estadística responde a una pregunta diferente.