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.
# Cómo empezar con las consultas programadas
Al crear una consulta programada, configurará varios componentes clave que definen cómo se ejecuta la consulta y dónde se entregan los resultados. Comprender estos componentes le ayudará a configurar un análisis de registro automatizado eficaz.
Cada consulta programada consta de los siguientes componentes clave:
**Configuración de consultas**
La cadena de consulta de CloudWatch Logs Insights, los grupos de registros de destino y el lenguaje de consulta que se utilizarán en el análisis.
**Expresión de programación**
Una expresión cron o un calendario de frecuencias que define cuándo se ejecuta la consulta. Puede especificar la configuración de la zona horaria para garantizar que las consultas se ejecuten a la hora local correcta. La consola muestra una descripción legible de su programación, como «Ejecute la consulta todos los martes a las 15:10 durante un intervalo de tiempo de 5 minutos, con efecto inmediato, en UTC, hasta tiempo indefinido».
**Intervalo de tiempo**
El período retrospectivo de cada ejecución de una consulta, definido por una diferencia entre la hora de inicio y la hora de ejecución. Esto determina la cantidad de datos históricos que analizará cada ejecución de consulta.
**Vista previa del programa de ejecución**
La consola muestra las tres siguientes ejecuciones de consultas programadas con fechas y horas exactas (por ejemplo, 28-10-2025, 15:10, UTC; 2025/11/04 15:10, UTC; 2025/11/11/2011 15:10, UTC), lo que le ayuda a comprobar que la programación está configurada correctamente.
**Destinos**
Dónde se muestran los resultados de la consulta tras una ejecución correcta. Los destinos compatibles incluyen los buckets de Amazon S3 y, de forma predeterminada, los metadatos de los resultados se envían al bus de eventos predeterminado.
**Rol de ejecución**
Una función de IAM que CloudWatch Logs asume para ejecutar la consulta y entregar los resultados a los destinos especificados.
Antes de crear consultas programadas, asegúrese de tener configurados los permisos y los recursos necesarios.
# Crear una consulta programada
Cree una consulta programada que ejecute automáticamente las consultas de CloudWatch Logs Insights y entregue los resultados a los destinos que elija.
## Requisitos previos
Antes de crear una consulta programada, asegúrese de tener lo siguiente:
+ **Grupos de registros**: uno o más grupos de registros que contienen los datos que desea analizar
+ Función **de IAM de ejecución: función** de IAM con los siguientes permisos:
+ `logs:StartQuery`- Permiso para iniciar consultas de CloudWatch Logs Insights
+ `logs:GetQueryResults`- Permiso para recuperar los resultados de la consulta
+ `logs:DescribeLogGroups`- Permiso para acceder a la información del grupo de registros. Esto solo es necesario para los grupos de registros basados en prefijos para la detección de grupos de registros
+ **Permisos de destino: permisos** de IAM adicionales para el destino elegido:
+ Para los destinos de Amazon S3: `s3:PutObject`
+ **Para el AWS CLI uso de la API**: AWS credenciales configuradas con permisos para llamar a CloudWatch Logs APIs
Para ver ejemplos detallados de políticas de IAM, consulte[Administración de identidades y accesos para Amazon CloudWatch Logs](auth-and-access-control-cwl.md). También debe tenerse en cuenta que solo puede tener 1000 consultas programadas por cuenta.
------
#### [ Console ]
**Para crear una consulta programada (consola)**
1. ¿Abrir la consola CloudWatch de Logs en [https://us-east-1.console.aws.amazon.com/cloudwatch/casa? region=us-east-1 \$1LogsV2:Logs-Insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights).
1. **En el panel de navegación, selecciona Logs Insights.**
1. Seleccione **Crear consulta programada**.
1. En la sección **de definición de consultas**:
1. En **Idioma de consulta**, elija el idioma de consulta que desee utilizar en la lista.
1. Para la **cadena de consulta**, introduzca su consulta de CloudWatch Logs Insights en el cuadro.
1. Para **los grupos de registros**, seleccione los grupos de registros que desee consultar en la lista.
1. En la sección **de configuración del cronograma**:
1. En la **expresión Schedule**, configure cuándo se ejecutará la consulta. Elija una de las opciones predefinidas o introduzca una expresión cron personalizada.
1. **En Efectivo al crearse**, especifique cuándo se activa la programación. Elija comenzar inmediatamente o en una fecha y hora específicas utilizando el YYYY/MM/DD formato.
1. En **Intervalo de tiempo**, especifique el período retrospectivo para cada ejecución de consulta. Introduzca la duración en minutos que define el tiempo transcurrido desde el momento de ejecución de la consulta.
1. **En Continuar indefinidamente**, especifique cuándo finaliza la programación. Elija ejecutar indefinidamente o hasta una fecha y hora específicas utilizando YYYY/MM/DD el formato.
1. La consola muestra las tres siguientes ejecuciones de consultas programadas en función de su configuración y muestra las fechas y horas exactas en UTC en las que se ejecutará la consulta.
1. En la sección **Publicar los resultados de la consulta en S3 (opcional**) (si utilizas el destino S3):
1. Para el **bucket de S3**, selecciona **Esta cuenta** si el bucket de destino está en la misma AWS cuenta, o selecciona **Otra cuenta** si el bucket está en una AWS cuenta diferente e introduce el ID de cuenta de la cuenta propietaria del bucket.
1. Para el **URI de Amazon S3**, introduzca el bucket y el prefijo de Amazon S3 donde se almacenarán los resultados (por ejemplo,`s3://my-bucket/query-results/`). Si seleccionó **Esta cuenta**, puede elegir **Browse Amazon S3** para navegar y seleccionar una ubicación de Amazon S3 existente.
1. (Opcional) Para el **ARN de la clave KMS, introduzca el ARN** de una AWS KMS clave administrada por el cliente para cifrar los resultados de la consulta mediante SSE-KMS. La clave debe estar en la misma AWS región que el bucket de Amazon S3 de destino.
1. En la sección **Función de IAM para publicar los resultados de las consultas en Amazon S3**, elija una de las siguientes opciones:
1. Elija **Crear automáticamente un nuevo rol con los permisos predeterminados** para configurar automáticamente un rol de IAM con los permisos necesarios para que CloudWatch Logs entregue los resultados de las consultas a Amazon S3.
1. Elija **Utilizar un rol existente** para seleccionar un rol de IAM existente con las políticas necesarias para que CloudWatch Logs entregue los resultados de las consultas a Amazon S3. Utilice el campo de búsqueda para buscar y seleccionar el rol de IAM adecuado de la lista.
1. En la sección **Función de IAM para la ejecución programada de consultas**, elija una de las siguientes opciones:
1. Seleccione **Crear automáticamente un nuevo rol con los permisos predeterminados** para configurar automáticamente un rol de IAM con los permisos necesarios para que los CloudWatch registros ejecuten las consultas programadas.
1. Elija **Usar un rol existente para seleccionar un rol** de IAM existente con las políticas necesarias para que los CloudWatch registros ejecuten las consultas programadas. Utilice el campo de búsqueda para buscar y seleccionar el rol de IAM adecuado de la lista.
1. Seleccione **Crear programación** para crear la consulta programada.
------
#### [ AWS CLI ]
**Para crear una consulta programada (AWS CLI)**
+ Utilice el `create-scheduled-query` comando para crear una nueva consulta programada:
```
aws logs create-scheduled-query \
--name "ErrorAnalysisQuery" \
--query-language "CWLI" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)" \
--schedule-expression "cron(8 * * * ? *)" \
--execution-role-arn "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole" \
--log-group-identifiers "/aws/lambda/my-function" "/aws/apigateway/my-api" \
--state "ENABLED"
```
------
#### [ API ]
**Para crear una consulta programada (API)**
+ Utilice la `CreateScheduledQuery` acción para crear una nueva consulta programada. El siguiente ejemplo crea una consulta programada que se ejecuta cada hora:
```
{
"name": "ErrorAnalysisQuery",
"queryLanguage": "CWLI",
"queryString": "fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(8 * * * ? *)",
"executionRoleArn": "arn:aws:iam::123456789012:role/CloudWatchLogsScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/apigateway/my-api"],
"state": "ENABLED"
}
```
------
Tras crear la consulta programada, puede verla y gestionarla desde la página de **consultas programadas** y mediante la ListScheduledQueries API, que muestra todas las consultas programadas con sus nombres, fechas de creación, estado de la última ejecución, hora de la última activación y frecuencia de repetición.
# Visualización y administración de las consultas programadas
La siguiente información está disponible para cada consulta:
**Name**
El nombre exclusivo que asignó a la consulta programada. Seleccione el nombre para ver el historial detallado de configuración y ejecución.
**Fecha de creación**
La fecha en que se creó la consulta programada, que se muestra en YYYY-MM-DD formato.
**Estado de la última ejecución**
El estado de ejecución de la consulta más reciente. Los valores posibles son:
+ **Completa**: la consulta se ejecutó correctamente y los resultados se enviaron a todos los destinos configurados.
+ **Error: no** se pudo ejecutar la consulta o entregar el resultado. Compruebe el historial de ejecuciones para ver los detalles del error.
+ **Consulta no válida**: la consulta no es válida y tiene problemas de sintaxis
+ **Tiempo de espera: se** ha agotado el tiempo de espera de la consulta. El tiempo de espera de una consulta se agota automáticamente después de 60 minutos
**Hora de la última activación**
La fecha y la hora en que se ejecutó la consulta por última vez, mostradas en formato YYYY-MM-DD HH:MM:SS. Muestra **Nunca** si la consulta aún no se ha ejecutado.
**Repitiendo cada**
La frecuencia de programación de la consulta. Muestra la **opción Personalizada** para consultas que utilizan expresiones cron o descripciones de frecuencias específicas para programar de forma más sencilla.
La página de **consultas programadas** proporciona una descripción general de todas las consultas programadas y muestra su estado actual y su historial de ejecución para que pueda ver, supervisar y gestionar todas las consultas programadas desde una ubicación centralizada. Utilice esta información para supervisar el rendimiento de las consultas, identificar problemas y gestionar sus flujos de trabajo de análisis de registros automatizados.
------
#### [ Console ]
**Para ver las consultas programadas (consola)**
1. ¿Abrir la consola CloudWatch de Logs en [https://us-east-1.console.aws.amazon.com/cloudwatch/casa? region=us-east-1 \$1LogsV2:Logs-Insights](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights).
1. ****En la consola de CloudWatch registros, seleccione Consulta programada y Ver consultas programadas.****
------
#### [ AWS CLI ]
**Para ver una lista de las consultas programadas (AWS CLI)**
+ Utilice el `list-scheduled-queries` comando para enumerar todas las consultas programadas:
```
aws logs list-scheduled-queries --max-results 10
```
------
#### [ API ]
**Para enumerar las consultas programadas (API)**
+ Usa la `ListScheduledQueries` acción para recuperar todas las consultas programadas:
```
{
"maxResults": 10
}
```
------
El encabezado de la página de **consultas programadas** muestra el número total de consultas programadas de su cuenta, lo que le ayuda a realizar un seguimiento del uso y a gestionar sus flujos de trabajo de análisis de registros automatizados de forma eficaz.
# Ver el historial de ejecución de consultas programadas
Utilice el historial de ejecución para supervisar el rendimiento de las consultas programadas y solucionar cualquier problema relacionado con la ejecución de las consultas o la entrega de los resultados.
El historial de ejecución muestra el estado de cada consulta ejecutada, incluidas las ejecuciones correctas, los errores y los resultados del procesamiento de destino. Puede utilizar esta información para identificar patrones, diagnosticar problemas y comprobar que las consultas se ejecutan según lo previsto.
------
#### [ Console ]
**Para ver el historial de ejecuciones (consola)**
1. En la consola de CloudWatch registros, seleccione **Consulta programada** y **Ver consultas programadas**.
1. Seleccione la consulta programada que desee examinar.
1. Elija la pestaña **Execution history (Historial de ejecución)**.
------
#### [ AWS CLI ]
**Para ver el historial de ejecuciones (AWS CLI)**
1. Utilice el `get-scheduled-query-history` comando para recuperar el historial de ejecución de una consulta programada:
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 10
```
1. Para filtrar por estado de ejecución, añada el `--execution-statuses` parámetro:
```
aws logs get-scheduled-query-history \
--identifier "DailyErrorMonitoring" \
--start-time 1743379200 \
--end-time 1743465600 \
--max-results 1 \
--execution-statuses "SUCCEEDED"
```
------
#### [ API ]
**Para ver el historial de ejecuciones (API)**
+ Utilice la `GetScheduledQueryHistory` acción para recuperar el historial de ejecuciones:
```
{
"identifier": "DailyErrorMonitoring",
"startTime": 1743379200,
"endTime": 1743465600,
"maxResults": 10,
"executionStatuses": ["SUCCEEDED", "FAILED"]
}
```
------
El historial de ejecuciones muestra:
+ **Estado de ejecución**: en ejecución, completa, fallida, tiempo de espera o InvalidQuery
+ **Hora** de activación: cuando se ejecutó la consulta
+ **Destinos**: estado de procesamiento para cada destino configurado, incluidos S3 y EventBridge
+ **Mensajes de error**: detalles sobre cualquier error en la ejecución de la consulta o en el procesamiento del destino
# Actualización de una consulta programada
Modifique la configuración de la consulta programada para cambiar la cadena de consulta, el cronograma, los destinos o la función de ejecución a medida que cambien sus requisitos.
Puede actualizar cualquier aspecto de una consulta programada, incluida la cadena de consulta, la expresión del programa, los destinos y la función de ejecución. Los cambios entran en vigor inmediatamente para futuras ejecuciones.
------
#### [ Console ]
**Para actualizar una consulta programada (consola)**
1. En la consola de CloudWatch registros, seleccione **Consulta programada** y **Ver consultas programadas**.
1. Seleccione la consulta programada que desee actualizar.
1. Elija **Edit (Edición de)**.
1. Modifique la configuración según sea necesario.
1. Seleccione **Save changes (Guardar cambios)**.
------
#### [ AWS CLI ]
**Para actualizar una consulta programada (AWS CLI)**
+ Utilice el `update-scheduled-query` comando para modificar una consulta programada existente:
```
aws logs update-scheduled-query \
--identifier "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f" \
--description "Monitor for ERROR level logs daily" \
--query-language "LogsQL" \
--query-string "fields @timestamp, @message | filter @message like /ERROR/" \
--log-group-identifiers "/aws/lambda/my-function-1" "/aws/lambda/my-function-2"
```
------
#### [ API ]
**Para actualizar una consulta programada (API)**
1. Utilice la `UpdateScheduledQuery` acción para modificar la configuración de la consulta programada:
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message | filter @message like /WARNING|ERROR/ | stats count() by bin(5m)",
"scheduleExpression": "cron(0 */2 * * ? *)",
"state": "ENABLED"
}
```
1. Para actualizar varios parámetros de configuración a la vez:
```
{
"identifier": "arn:aws:logs:us-east-1:111122223333:scheduled-query:5e0c0228-1c29-4d26-904f-59f1f1ba3c8f",
"queryString": "fields @timestamp, @message, @level | filter @level = 'ERROR'",
"scheduleExpression": "cron(0 8,12,16 * * ? *)",
"executionRoleArn": "arn:aws:iam::111122223333:role/UpdatedScheduledQueryRole",
"logGroupIdentifiers": ["/aws/lambda/my-function", "/aws/lambda/another-function"],
"destinationConfiguration": {
"s3Configuration": {
"destinationIdentifier": "s3://111122223333-sqn-results-bucket/processed-results",
"roleArn": "arn:aws:iam::111122223333:role/Admin"
}
}
}
```
------