As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Introdução às consultas agendadas Ao criar uma consulta agendada, você configurará vários componentes principais que definem como sua consulta é executada e onde os resultados são entregues. A compreensão desses componentes ajudará você a configurar uma análise automatizada eficaz de registros. Cada consulta agendada consiste nos seguintes componentes principais: **Configuração de consulta** A string de consulta do CloudWatch Logs Insights, os grupos de registros de destino e a linguagem de consulta a serem usados na análise. **Expressão de programação** Uma expressão cron ou calendário de frequência que define quando a consulta é executada. Você pode especificar configurações de fuso horário para garantir que as consultas sejam executadas no horário local correto. O console exibe uma descrição legível por humanos de sua agenda, como “Execute consultas todas as terças-feiras às 15:10 por um intervalo de 5 minutos, com efeito imediato, em UTC, até indefinidamente”. **Intervalo de tempo** O período de retrospectiva para cada execução de consulta, definido por uma diferença de horário de início em relação ao tempo de execução. Isso determina a quantidade de dados históricos que cada execução de consulta analisará. **Prévia do cronograma de execução** O console mostra as próximas três execuções de consulta agendadas com datas e horários exatos (por exemplo, 2025/10/28 15:10, UTC; 2025/11/04 15:10, UTC; 2025/11/11 15:10, UTC), ajudando você a verificar se a programação está configurada corretamente. **Destinos** Onde os resultados da consulta são entregues após a execução bem-sucedida. Os destinos compatíveis incluem buckets do Amazon S3 e, por padrão, os metadados dos resultados são enviados para o barramento de eventos padrão. **Perfil de execução** Uma função do IAM que o CloudWatch Logs assume para executar a consulta e entregar resultados aos destinos especificados. Antes de criar consultas agendadas, verifique se você tem as permissões e os recursos necessários configurados. # Criação de uma consulta agendada Crie uma consulta agendada que execute automaticamente as consultas do CloudWatch Logs Insights e entregue os resultados aos destinos escolhidos. ## Pré-requisitos Antes de criar uma consulta agendada, verifique se você tem o seguinte: + **Grupos de registros** - Um ou mais grupos de registros contendo os dados que você deseja analisar + **Função do IAM de execução** — uma função do IAM com as seguintes permissões: + `logs:StartQuery`- Permissão para iniciar consultas do CloudWatch Logs Insights + `logs:GetQueryResults`- Permissão para recuperar os resultados da consulta + `logs:DescribeLogGroups`- Permissão para acessar as informações do grupo de registros. Isso só é necessário para grupos de registros baseados em prefixos para descoberta de grupos de registros + **Permissões de destino** - Permissões adicionais do IAM para o destino escolhido: + Para destinos do Amazon S3: `s3:PutObject` + **Para AWS CLI e uso da API** - AWS Credenciais configuradas com permissões para chamar CloudWatch o Logs APIs Para obter exemplos detalhados de políticas do IAM, consulte[Gerenciamento de identidade e acesso para Amazon CloudWatch Logs](auth-and-access-control-cwl.md). Também deve ser observado que você pode ter apenas 1000 consultas agendadas por conta. ------ #### [ Console ] **Para criar uma consulta agendada (console)** 1. Abra o console de CloudWatch registros em [https://us-east-1.console.aws.amazon.com/cloudwatch/casa? region=us-east-1](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights) \$1logsV2:Logs-Insights. 1. No painel de navegação, escolha **Logs Insights**. 1. Escolha **Criar consulta agendada**. 1. Na seção **Definição da consulta**: 1. Em **Idioma de consulta**, escolha o idioma de consulta a ser usado na lista. 1. Em Cadeia de **caracteres de consulta**, insira sua consulta do CloudWatch Logs Insights na caixa. 1. Em **Grupos de registros**, selecione os grupos de registros a serem consultados na lista. 1. Na seção **Configuração do cronograma**: 1. Em **Schedule expression**, configure quando a consulta é executada. Escolha entre as opções predefinidas ou insira uma expressão cron personalizada. 1. **Em Efetivo após a criação**, especifique quando o cronograma se torna ativo. Escolha começar imediatamente ou em uma data e hora específicas usando o YYYY/MM/DD formato. 1. Em **Intervalo de tempo**, especifique o período de retrospectiva para cada execução de consulta. Insira a duração em minutos que define a distância entre o tempo de execução da consulta. 1. **Em Continuar indefinidamente**, especifique quando a programação termina. Escolha executar indefinidamente ou até uma data e hora específicas usando o YYYY/MM/DD formato. 1. O console exibe as próximas três execuções de consulta agendadas com base na sua configuração, mostrando as datas e horários exatos em UTC em que a consulta será executada. 1. Na seção **Post query results to S3 - opcional** (se estiver usando o destino S3): 1. Para o **bucket do S3**, selecione **Esta conta** se o bucket de destino estiver na mesma AWS conta ou selecione **Outra conta** se o bucket estiver em uma AWS conta diferente e forneça o ID da conta proprietária do bucket como entrada. 1. Para o **URI do Amazon S3**, insira o bucket e o prefixo do Amazon S3 onde os resultados serão armazenados (por exemplo,). `s3://my-bucket/query-results/` Se você selecionou **Esta conta**, você pode escolher **Navegar no Amazon S3** para navegar e selecionar um local existente do Amazon S3. 1. (Opcional) Para ARN da **chave KMS, insira o ARN** de uma chave AWS KMS gerenciada pelo cliente para criptografar os resultados da consulta usando o SSE-KMS. A chave deve estar na mesma AWS região do bucket Amazon S3 de destino. 1. Na **função do IAM para publicar resultados de consultas na seção Amazon S3**, escolha uma das seguintes opções: 1. Escolha **Criar automaticamente uma nova função com permissões padrão** para configurar automaticamente uma função do IAM com as permissões necessárias para que os CloudWatch Logs entreguem os resultados da consulta ao Amazon S3. 1. Escolha **Usar uma função existente** para selecionar uma função do IAM existente com as políticas necessárias para que CloudWatch os registros entreguem os resultados da consulta ao Amazon S3. Use o campo de pesquisa para encontrar e selecionar a função apropriada do IAM na lista. 1. Na seção **Função do IAM para execução agendada de consultas**, escolha uma das seguintes opções: 1. Escolha **Criar automaticamente uma nova função com permissões padrão** para configurar automaticamente uma função do IAM com as permissões necessárias para que o CloudWatch Logs execute consultas agendadas. 1. Escolha **Usar uma função existente** para selecionar uma função do IAM existente com as políticas necessárias para que CloudWatch os registros executem consultas agendadas. Use o campo de pesquisa para encontrar e selecionar a função apropriada do IAM na lista. 1. Escolha **Criar agendamento** para criar a consulta agendada. ------ #### [ AWS CLI ] **Para criar uma consulta agendada (AWS CLI)** + Use o `create-scheduled-query` comando para criar uma nova consulta agendada: ``` 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 criar uma consulta agendada (API)** + Use a `CreateScheduledQuery` ação para criar uma nova consulta agendada. O exemplo a seguir cria uma consulta agendada que é executada a 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" } ``` ------ Depois de criar a consulta agendada, você pode visualizá-la e gerenciá-la na página **Consultas agendadas** e usando a ListScheduledQueries API, que mostra todas as consultas agendadas com seus nomes, datas de criação, status da última execução, hora da última ativação e frequência de repetição. # Visualizando e gerenciando consultas agendadas As informações a seguir estão disponíveis para cada consulta: **Nome** O nome exclusivo que você atribuiu à consulta agendada. Selecione o nome para ver a configuração detalhada e o histórico de execução. **Data de Criação** A data em que a consulta agendada foi criada, exibida no YYYY-MM-DD formato. **Status da última execução** O status de execução da consulta mais recente executada. Os possíveis valores incluem: + **Concluído** - A consulta foi executada com sucesso e os resultados foram entregues a todos os destinos configurados. + **Falha** - A execução da consulta ou a entrega do resultado falharam. Verifique o histórico de execução para obter detalhes do erro. + **Consulta inválida** - A consulta é inválida e tem problemas sintáticos + **Tempo limite** - O tempo limite da consulta atingiu o tempo limite. Uma consulta expira automaticamente após 60 minutos **Hora da última ativação** A data e a hora em que a consulta foi executada pela última vez, exibidas no formato YYYY-MM-DD HH:MM:SS. Mostra **Nunca** se a consulta ainda não tiver sido executada. **Repetindo cada** A frequência do agendamento para a consulta. Mostra **Personalizado** para consultas usando expressões cron ou descrições de frequência específicas para agendas mais simples. A página **Consultas agendadas** fornece uma visão geral de todas as consultas agendadas, mostrando o status atual e o histórico de execução para que você possa visualizar, monitorar e gerenciar todas as consultas agendadas a partir de um local centralizado. Use essas informações para monitorar o desempenho das consultas, identificar problemas e gerenciar seus fluxos de trabalho automatizados de análise de registros. ------ #### [ Console ] **Para visualizar consultas agendadas (console)** 1. Abra o console de CloudWatch registros em [https://us-east-1.console.aws.amazon.com/cloudwatch/casa? region=us-east-1](https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#logsV2:logs-insights) \$1logsV2:Logs-Insights. 1. No console de CloudWatch registros, escolha **Consulta agendada**, **Exibir consultas agendadas**. ------ #### [ AWS CLI ] **Para listar consultas agendadas ()AWS CLI** + Use o `list-scheduled-queries` comando para listar todas as consultas agendadas: ``` aws logs list-scheduled-queries --max-results 10 ``` ------ #### [ API ] **Para listar consultas agendadas (API)** + Use a `ListScheduledQueries` ação para recuperar todas as consultas agendadas: ``` { "maxResults": 10 } ``` ------ O cabeçalho da página **Consultas agendadas** mostra o número total de consultas agendadas em sua conta, ajudando você a monitorar seu uso e gerenciar seus fluxos de trabalho automatizados de análise de registros de forma eficaz. # Visualizando o histórico de execução de consultas agendadas Use o histórico de execução para monitorar o desempenho de suas consultas agendadas e solucionar quaisquer problemas com a execução da consulta ou a entrega de resultados. O histórico de execução mostra o status de cada execução de consulta, incluindo execuções bem-sucedidas, falhas e resultados do processamento de destino. Você pode usar essas informações para identificar padrões, diagnosticar problemas e verificar se suas consultas estão sendo executadas conforme o esperado. ------ #### [ Console ] **Para ver o histórico de execução (console)** 1. No console de CloudWatch registros, escolha **Consulta agendada**, **Exibir consultas agendadas**. 1. Selecione a consulta agendada que você deseja examinar. 1. Escolha a guia **Execution history (Histórico de execução)**. ------ #### [ AWS CLI ] **Para ver o histórico de execução (AWS CLI)** 1. Use o `get-scheduled-query-history` comando para recuperar o histórico de execução de uma consulta agendada: ``` aws logs get-scheduled-query-history \ --identifier "DailyErrorMonitoring" \ --start-time 1743379200 \ --end-time 1743465600 \ --max-results 10 ``` 1. Para filtrar por status de execução, adicione o `--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 o histórico de execução (API)** + Use a `GetScheduledQueryHistory` ação para recuperar o histórico de execução: ``` { "identifier": "DailyErrorMonitoring", "startTime": 1743379200, "endTime": 1743465600, "maxResults": 10, "executionStatuses": ["SUCCEEDED", "FAILED"] } ``` ------ O histórico de execução exibe: + **Status de execução** - Em execução, concluída, com falha, tempo limite ou InvalidQuery + **Tempo de acionamento** - Quando a consulta foi executada + **Destinos** - Status de processamento para cada destino configurado, incluindo S3 e EventBridge + **Mensagens de erro** - Detalhes sobre quaisquer falhas na execução da consulta ou no processamento do destino # Atualizando uma consulta agendada Modifique sua configuração de consulta agendada para alterar a sequência de caracteres de consulta, o cronograma, os destinos ou a função de execução à medida que seus requisitos evoluem. Você pode atualizar qualquer aspecto de uma consulta agendada, incluindo a sequência de caracteres de consulta, a expressão do cronograma, os destinos e a função de execução. As alterações entram em vigor imediatamente para futuras execuções. ------ #### [ Console ] **Para atualizar uma consulta agendada (console)** 1. No console de CloudWatch registros, escolha **Consulta agendada**, **Exibir consultas agendadas**. 1. Selecione a consulta agendada que você deseja atualizar. 1. Escolha **Editar**. 1. Modifique a configuração conforme necessário. 1. Escolha **Salvar alterações**. ------ #### [ AWS CLI ] **Para atualizar uma consulta agendada (AWS CLI)** + Use o `update-scheduled-query` comando para modificar uma consulta agendada 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 atualizar uma consulta agendada (API)** 1. Use a `UpdateScheduledQuery` ação para modificar a configuração da consulta agendada: ``` { "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 atualizar vários parâmetros de configuração ao mesmo tempo: ``` { "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" } } } ``` ------