

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á.

# Automatizando a análise de registros com consultas programadas
<a name="ScheduledQueries"></a>

As consultas agendadas permitem que você automatize a execução de consultas do CloudWatch Logs Insights em uma programação regular. Em vez de executar consultas manualmente para analisar seus dados de log, você pode configurar consultas programadas para serem executadas automaticamente e entregar resultados para destinos como buckets do Amazon S3 ou barramentos de eventos da Amazon. EventBridge Essa automação é ideal para gerar relatórios regulares, monitorar tendências ou acionar processos posteriores com base nos resultados da análise de registros.

As consultas agendadas oferecem suporte aos três idiomas de consulta disponíveis no CloudWatch Logs Insights:
+ [**Linguagem de consulta do Logs Insights (Logs Insights QL)**](CWL_AnalyzeLogData_LogsInsights.md)
+ [**OpenSearch Linguagem de processamento de serviços canalizados (PPL)**](CWL_AnalyzeLogData_PPL.md)
+ [**OpenSearch Linguagem de consulta estruturada de serviços (SQL)**](CWL_AnalyzeLogData_SQL.md)

**Topics**
+ [

# Compreender os conceitos de consultas agendadas
](scheduled-queries-concepts.md)
+ [

# Referência da expressão do cronograma
](scheduled-queries-schedule-reference.md)
+ [

# Práticas recomendadas
](scheduled-queries-best-practices.md)
+ [

# Introdução às consultas agendadas
](scheduled-queries-getting-started.md)
+ [

# Configurando destinos do S3 para consultas agendadas
](scheduled-queries-s3-destination.md)
+ [

# Solução de problemas de consultas agendadas
](scheduled-queries-troubleshooting.md)

# Compreender os conceitos de consultas agendadas
<a name="scheduled-queries-concepts"></a>

Antes de criar consultas agendadas, entenda esses conceitos-chave que afetam a forma como suas consultas são executadas e onde os resultados são entregues.

## Separação de funções do IAM
<a name="scheduled-queries-iam-roles"></a>

As consultas agendadas exigem duas funções separadas do IAM: uma para executar consultas e outra para entregar resultados aos barramentos de eventos do Amazon S3 ou da Amazon. EventBridge Entender por que essa separação existe ajuda você a configurar as permissões corretamente e a usar os benefícios operacionais e de segurança que ela oferece.

A arquitetura de duas funções divide as responsabilidades entre acesso e entrega de dados. A função de execução da consulta acessa seus dados de log e executa consultas, enquanto a função de entrega de destino grava os resultados no destino escolhido. Essa separação segue o princípio do menor privilégio: cada função tem somente as permissões necessárias para sua função específica.

**Função de execução da consulta**  
Permite que o CloudWatch CloudWatch Logs execute consultas do Logs Insights em seu nome. Essa função precisa de permissões para acessar seus grupos de registros e executar consultas, mas não precisa acessar os recursos de destino. Permissões obrigatórias:  
+ `logs:StartQuery`
+ `logs:StopQuery`
+ `logs:GetQueryResults`
+ `logs:DescribeLogGroups`
+ `logs:Unmask`se for necessário desmascarar dados
**Para grupos de registros criptografados pelo KMS:** `kms:Decrypt` e `kms:DescribeKey` permissões para a chave KMS usada para criptografar os grupos de registros. Essas permissões também precisam ser adicionadas.  
**Requisito de relação de confiança:** a função de execução da consulta deve incluir uma política de confiança que permita que o serviço CloudWatch Logs (`logs.amazonaws.com`) assuma a função. Sem essa relação de confiança, as consultas agendadas falharão com erros de permissão.  
Exemplo de política de confiança para a função de execução da consulta:  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "logs.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```
Exemplo de política de permissões para a função de execução da consulta:  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:StartQuery",
                "logs:StopQuery",
                "logs:GetQueryResults",
                "logs:DescribeLogGroups"
            ],
            "Resource": "*"
        }
    ]
}
```

**Função de entrega de destino**  
Permite que o CloudWatch Logs forneça os resultados da consulta para o destino escolhido. Essa função só precisa de permissões para o serviço de destino específico, seguindo o princípio do privilégio mínimo. As permissões necessárias variam de acordo com o tipo de destino.  
**Requisito de relação de confiança:** a função de entrega de destino também deve incluir uma política de confiança que permita que o serviço CloudWatch Logs (`logs.amazonaws.com`) assuma a função.  
Exemplo de política de permissões para a função de entrega de destino do S3:  

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::your-scheduled-query-results-bucket/*"
        }
    ]
}
```

Essa separação oferece benefícios práticos para suas operações. Do ponto de vista da segurança, se você precisar alterar onde os resultados são entregues, modifique apenas a função de entrega de destino sem alterar as permissões de execução da consulta. Para fins de conformidade e auditoria, você pode monitorar claramente qual função acessa dados de log confidenciais e qual função grava em sistemas externos. Isso facilita a demonstração de que sua infraestrutura de análise de registros segue as melhores práticas de segurança.

## Uso entre regiões e entre contas
<a name="scheduled-queries-cross-account"></a>

Uma consulta agendada é criada em uma região específica e executada nessa região. No entanto, você pode consultar grupos de registros e fornecer resultados em todas as regiões e contas. Você precisa configurar uma ou mais AWS contas como contas de *monitoramento* e vinculá-las a várias *contas de origem*. Uma conta de monitoramento é uma AWS conta central que pode visualizar e interagir com os dados de observabilidade gerados pelas contas de origem. Uma conta de origem é uma AWS conta individual que gera dados de observabilidade para os recursos que residem nela. As contas de origem compartilham os dados de observabilidade com a conta de monitoramento. Assim, você pode configurar consultas agendadas da conta de monitoramento usando os grupos de registros de todas as contas vinculadas.

**Consultando grupos de registros entre regiões**  
Sua consulta agendada pode acessar grupos de registros em qualquer região. Especifique grupos de log usando seu formato ARN completo:. `arn:aws:logs:region:account-id:log-group:log-group-name` As necessidades `logs:StartQuery` e `logs:GetQueryResults` permissões da função de execução da consulta para grupos de registros em todas as regiões de destino.

**Importante**  
Ao consultar grupos de registros ou fornecer resultados em várias regiões, os dados de registro ultrapassam os limites regionais. Considere o seguinte:  
**Requisitos de residência de dados** - Garanta que a transferência de dados entre regiões esteja em conformidade com as políticas de governança de dados e os requisitos regulatórios de sua organização
**Custos de transferência de dados** - a transferência de dados entre regiões incorre em custos adicionais
**Latência de rede** - consultas que acessam grupos de registros em regiões distantes podem ter maior latência
Para otimizar o desempenho e a economia, crie consultas agendadas na mesma região dos seus grupos de registros primários.

**Abordagem alternativa:** use a [centralização de CloudWatch registros](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatchLogs_Centralization.html) para replicar dados de registro de várias contas e regiões em uma conta de monitoramento central. Isso permite criar consultas agendadas em uma única região que acessa todos os seus registros centralizados, evitando consultas entre regiões e simplificando o gerenciamento de permissões do IAM.

## Expressões de programação e tratamento de fuso horário
<a name="scheduled-queries-schedule-expressions"></a>

O cronograma que você define determina quando sua consulta é executada e com que frequência ela é executada. A escolha da expressão de agendamento correta afeta quando você recebe os resultados e a quantidade de dados que você consulta. Compreender os tipos de expressão ajuda você a escolher entre simplicidade e precisão.

As expressões Cron fornecem controle preciso sobre o tempo, permitindo que você especifique horários, dias da semana ou dias do mês exatos. Use expressões cron quando precisar que as consultas sejam executadas em horários comerciais específicos ou estejam alinhadas aos cronogramas operacionais. No console, você também pode agendar consultas usando opções fáceis de calendário.

**Expressão cron**  
Execute consultas em horários específicos. Formato: `cron(minute hour day-of-month month day-of-week year)`. Exemplos:  
+ `cron(0 9 * * ? *)`- Todos os dias às 9:00 UTC
+ `cron(0 18 ? * MON-FRI *)`- Dias úteis às 18h UTC
+ `cron(0 0 1 * ? *)`- Primeiro dia de cada mês à meia-noite UTC
+ `cron(0 12 ? * SUN *)`- Todos os domingos ao meio-dia UTC
+ `cron(30 8 1 1 ? *)`- 1º de janeiro às 8h30 UTC

Todas as consultas agendadas são executadas em UTC, independentemente do fuso horário local ou da localização AWS dos recursos. Isso é particularmente importante quando você agenda consultas para o horário comercial ou análises urgentes. Por exemplo, se sua empresa opera no Horário do Leste dos EUA e você quer um relatório diário às 9h ET, você precisa contabilizar a diferença UTC (14:00 UTC durante o horário de verão, 13:00 UTC caso contrário). Planeje suas expressões de agendamento com o UTC em mente para garantir que as consultas sejam executadas nos horários pretendidos.

## Escolhendo um idioma de consulta
<a name="scheduled-queries-query-languages"></a>

As consultas agendadas oferecem suporte a três linguagens de consulta diferentes, e sua escolha afeta a forma como você escreve as consultas e a facilidade com que sua equipe pode mantê-las. O idioma certo depende dos seus requisitos de análise e das habilidades existentes da sua equipe.

Se você está filtrando e agregando principalmente dados de registro, a linguagem de consulta do CloudWatch Logs Insights oferece a sintaxe mais direta. Para transformações de dados complexas em que você precisa remodelar ou enriquecer dados por meio de várias etapas, a abordagem de pipeline do PPL facilita o acompanhamento da lógica. Quando você precisa realizar uniões ou agregações complexas semelhantes às operações de banco de dados, o SQL fornece uma sintaxe familiar que equipes experientes em bancos de dados podem adotar rapidamente.

**CloudWatch Linguagem de consulta do Logs Insights (CWLI)**  
Criado especificamente para análise de registros com sintaxe intuitiva. Ideal para:  
+ Análise e filtragem de registros com base em texto
+ Agregações e estatísticas de séries temporais
+ Equipes novatas na análise de registros

**OpenSearch Linguagem de processamento de serviços canalizados (PPL)**  
Linguagem de consulta baseada em pipeline com poderosos recursos de transformação de dados. Ideal para:  
+ Transformações e enriquecimento complexos de dados
+ Fluxos de trabalho de processamento de dados em várias etapas
+ Equipes familiarizadas com o processamento baseado em pipelines

**OpenSearch Linguagem de consulta estruturada de serviços (SQL)**  
Sintaxe SQL padrão para consultas familiares no estilo de banco de dados. Ideal para:  
+ Junções e agregações complexas
+ Inteligência de negócios e relatórios
+ Equipes com forte experiência em SQL

## Seleção de destinos e casos de uso
<a name="scheduled-queries-destinations"></a>

O local onde você envia os resultados da consulta determina o que você pode fazer com eles. Essa escolha molda todo o seu fluxo de trabalho posterior, esteja você criando análises de longo prazo, acionando respostas automatizadas ou ambas. Compreender os pontos fortes de cada tipo de destino ajuda você a projetar a arquitetura certa para seu caso de uso.

Os destinos do Amazon S3 são otimizados para armazenamento e processamento em lote. Quando você precisa manter os resultados das consultas por meses ou anos, analisar tendências ao longo do tempo ou inserir dados em plataformas de análise, o Amazon S3 fornece armazenamento econômico com retenção ilimitada. EventBridge os destinos são otimizados para automação em tempo real. Quando os resultados da consulta devem acionar ações imediatas, como enviar alertas, iniciar fluxos de trabalho ou atualizar sistemas, EventBridge fornece resultados como eventos aos quais seus aplicativos podem responder instantaneamente. Por padrão, todos os eventos de conclusão da consulta são enviados automaticamente como eventos para o barramento de eventos padrão, permitindo a integração com sistemas de processamento downstream, funções Lambda ou outras arquiteturas orientadas a eventos. Os resultados só são publicados nos destinos quando a consulta é executada com sucesso.

**Destinos do Amazon S3**  
Armazene os resultados da consulta como arquivos JSON para retenção de longo prazo e processamento em lote. Ideal para:  
+ Análise histórica e arquivamento de dados
+ Integração com lagos de dados e plataformas de análise
+ Requisitos de conformidade e auditoria
+ Armazenamento econômico de grandes conjuntos de resultados

**EventBridge destinos**  
Envie os resultados da consulta como eventos para processamento e automação em tempo real. Você pode recuperar os resultados da consulta usando o QueryID enviado no evento em até 30 dias somente, pois armazenamos os resultados por 30 dias. Ideal para:  
+ Acionando respostas automatizadas aos resultados da consulta
+ Integração com fluxos de trabalho sem servidor e funções Lambda
+ Sistemas de alerta e notificação em tempo real
+ Arquiteturas e microsserviços orientados por eventos

## Formato e estrutura do resultado da consulta
<a name="scheduled-queries-result-format"></a>

Para destinos do Amazon S3 - os resultados da consulta são entregues no formato JSON com a mesma estrutura da resposta da GetQueryResults API. Para a Amazon, EventBridge entender o formato dos resultados de consultas programadas ajuda você a projetar fluxos de trabalho de processamento e integração posteriores.

Os resultados da consulta são entregues no formato JSON com a seguinte estrutura:

```
{
    "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, @log\n| sort @timestamp desc\n| limit 10000",
        "logGroupIdentifiers": [
            "/aws/lambda/my-function"
        ],
        "status": "Complete",
        "startTime": 1763465460,
        "statistics": {
            "recordsMatched": 0,
            "recordsScanned": 0,
            "estimatedRecordsSkipped": 0,
            "bytesScanned": 0,
            "estimatedBytesSkipped": 0,
            "logGroupsScanned": 1
        }
    }
}
```

Os principais elementos incluem:
+ `statistics`- Métricas de desempenho de consultas, incluindo registros correspondidos, digitalizados, bytes processados e dados estimados ignorados
+ `startTime`- Quando a execução da consulta começou (timestamp Unix)
+ `queryString`- A consulta real que foi executada
+ `queryId`- ID de consulta da consulta usando quais resultados podem ser recuperados
+ `logGroupIdentifiers`- Lista de grupos de registros que foram consultados
+ `status`- Status de execução da consulta (Concluída, Falha, etc.)

# Referência da expressão do cronograma
<a name="scheduled-queries-schedule-reference"></a>

Use essas tabelas de referência para criar expressões de agendamento para suas consultas agendadas. Todos os horários são em UTC.

**Sintaxe da expressão Cron**

Formato: `cron(minute hour day-of-month month day-of-week year)`.


| Caso de uso | Expressão cron | Description | Use quando | 
| --- | --- | --- | --- | 
| Horários diários | cron(0 9 \$1 \$1 ? \$1) | Todos os dias às 9:00 UTC | Relatórios diários | 
|  | cron(0 \$1/6 \$1 \$1 ? \$1) | A cada 6 horas (00:00, 06:00, 12:00, 18:00 UTC) | Monitoramento frequente | 
|  | cron(30 2 \$1 \$1 ? \$1) | Todos os dias às 2h30 UTC | Análise fora do pico | 
| Horário comercial | cron(0 9-17 ? \$1 MON-FRI \$1) | A cada hora, das 9h às 17h, de segunda a sexta-feira UTC | Monitoramento de negócios | 
|  | cron(0 18 ? \$1 MON-FRI \$1) | Dias de semana às 18h UTC | Fim do dia útil | 
|  | cron(0 8,12,17 ? \$1 MON-FRI \$1) | 8h, meio-dia e 17h nos dias úteis UTC | Principais momentos de negócios | 
| Programações semanais | cron(0 12 ? \$1 SUN \$1) | Todos os domingos ao meio-dia UTC | Resumos semanais | 
|  | cron(0 9 ? \$1 MON \$1) | Todas as segundas-feiras às 9:00 UTC | Relatórios de início da semana | 
|  | cron(0 23 ? \$1 FRI \$1) | Todas as sextas-feiras às 23:00 UTC | Limpeza de fim de semana | 
| Programações mensais | cron(0 0 1 \$1 ? \$1) | Primeiro dia de cada mês à meia-noite UTC | Relatórios mensais | 
|  | cron(0 9 L \$1 ? \$1) | Último dia de cada mês às 9:00 UTC | Processamento no final do mês | 
|  | cron(0 10 1 1,4,7,10 ? \$1) | Primeiro dia de cada trimestre às 10:00 UTC | Análise trimestral | 
| Alta frequência | cron(\$1/15 \$1 \$1 \$1 ? \$1) | A cada 15 minutos | Monitoramento em tempo real | 
|  | cron(0,30 \$1 \$1 \$1 ? \$1) | A cada 30 minutos (às :00 e às :30) | Verificações frequentes | 
|  | cron(0 \$1/2 \$1 \$1 ? \$1) | A cada 2 horas | Intervalos regulares | 
| Casos especiais | cron(30 8 1 1 ? \$1) | 1º de janeiro às 8:30 UTC | Relatórios anuais | 
|  | cron(0 6 \$1 \$1 SAT,SUN \$1) | Fins de semana às 6:00 UTC | Processamento de fim de | 
|  | cron(0 0 ? \$1 MON\$11 \$1) | Primeira segunda-feira de cada mês à meia-noite UTC | Planejamento mensal | 

**Referência de campo de expressão Cron**


| Campo | Valores | Curingas | Exemplos | 
| --- | --- | --- | --- | 
| Minuto (1º) | 0-59 | \$1 , - / | 0(hora máxima), \$1/15 (a cada 15 minutos), 0,30 (duas vezes por hora) | 
| Hora (2ª) | 0-23 | \$1 , - / | 9(9h), \$1/2 (a cada 2 horas), 9-17 (horário comercial) | 
| Day-of-month (3º) | 1-13, L, W | \$1 , - / ? | 1(1º dia), L (último dia), ? (ao usar day-of-week) | 
| Mês (4º) | 1-12 ou JAN-DEZ | \$1 , - / | 1(janeiro),JAN, 1,4,7,10 (trimestral) | 
| Day-of-week (5º) | 1-7 ou DOM-SÁB | \$1 , - / ? \$1 L | MON-FRI(dias úteis),SUN, MON\$11 (1ª segunda-feira) | 
| Ano (6º) | 1970-2199 | \$1 , - / | \$1(todos os anos), 2024 (ano específico), 2024-2026 (intervalo) | 

**Caracteres curinga e expressões especiais**

**`*` (asterisco)**  
Corresponde a todos os valores no campo. Exemplo: `*` no campo da hora significa a cada hora.

**`?`(ponto de interrogação)**  
Sem valor específico. Use em day-of-month ou day-of-week quando o outro for especificado. Exemplo: Use `?` in day-of-month ao especificar `MON-FRI` em day-of-week.

**`-` (traço)**  
Faixa de valores. Exemplo: `MON-FRI` (de segunda a sexta-feira), `9-17` (das 9h às 17h).

**`,`(vírgula)**  
Vários valores específicos. Exemplo: `MON,WED,FRI` (segunda, quarta, sexta-feira), `8,12,17` (8h, meio-dia, 17h).

**`/`(corte)**  
Valores ou incrementos da etapa. Exemplo: `0/15` em minutos significa a cada 15 minutos começando no minuto 0 (0, 15, 30, 45). `*/2`em horas significa a cada 2 horas.

**`L`(último)**  
Último dia do mês ou última ocorrência do dia da semana. Exemplo: `L` in day-of-month significa último dia do mês. `FRIL`significa última sexta-feira do mês.

**`W`(dia da semana)**  
Dia da semana mais próximo. Exemplo: `15W` significa o dia da semana mais próximo do 15º dia do mês.

**`#`(enésima ocorrência)**  
Nona ocorrência de um dia da semana em um mês. Exemplo: `MON#1` significa primeira segunda-feira do mês, `FRI#2` significa segunda sexta-feira do mês.

**Padrões comuns e melhores práticas**
+ **Para aplicativos de negócios:** uso `MON-FRI` e horário comercial (por exemplo,`9-17`) para evitar a execução de consultas durante fins de semana ou fora do horário comercial.
+ **Para monitoramento de alta frequência:** use incrementos como `*/15` (a cada 15 minutos), mas esteja atento aos limites de simultaneidade de consultas.
+ **Para eficiência de recursos:** agende consultas que consomem muitos recursos fora do horário de pico usando os horários matinais, como o UTC. `2-6`
+ **Para relatórios mensais:** use `L` para o último dia do mês ou datas específicas, como `1` para o primeiro dia, para garantir um tempo consistente.

# Práticas recomendadas
<a name="scheduled-queries-best-practices"></a>

Siga estas melhores práticas para garantir operações de consulta programadas confiáveis e eficientes:

**Otimização de consultas**  
+ Teste as consultas manualmente antes do agendamento para verificar o desempenho e os resultados
+ Use índices de filtro logo no início da consulta para reduzir o processamento de dados
+ Limite os intervalos de tempo para evitar tempos limite com grupos de registros de alto volume
+ Considere a complexidade da consulta e os limites de tempo de execução

**Planejamento do cronograma**  
+ Evite execuções sobrepostas garantindo que as consultas sejam concluídas antes da próxima execução programada
+ Considere atrasos na ingestão de registros ao definir intervalos de tempo
+ Use expressões cron para horários específicos
+ Distribua as programações para garantir que você não atinja o limite de simultaneidade de consultas

**Monitoramento e manutenção**  
+ Monitore o histórico de execução regularmente para identificar falhas ou problemas de desempenho
+ Revise e atualize as funções do IAM periodicamente para manter a segurança
+ Teste a acessibilidade do destino antes da implantação na produção

**Autorização**  
+ Todas as autorizações APIs de consulta agendada são autorizadas no recurso de consulta agendada e não nos recursos que ele recebe na entrada, como grupos de registros. Configure as políticas do IAM adequadamente
+ Gerencie a autorização de grupos de registros usando a função de execução passada no APIs

# Introdução às consultas agendadas
<a name="scheduled-queries-getting-started"></a>

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
<a name="create-scheduled-query"></a>

Crie uma consulta agendada que execute automaticamente as consultas do CloudWatch Logs Insights e entregue os resultados aos destinos escolhidos.

## Pré-requisitos
<a name="create-scheduled-query-prerequisites"></a>

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
<a name="scheduled-queries-management"></a>

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
<a name="scheduled-queries-execution-history"></a>

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
<a name="scheduled-queries-updating"></a>

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"
           }
       }
   }
   ```

------

# Configurando destinos do S3 para consultas agendadas
<a name="scheduled-queries-s3-destination"></a>

Configure o Amazon S3 como um destino para armazenar seus resultados de consulta programados como arquivos JSON para retenção e análise de longo prazo.

Ao usar o Amazon S3 como destino, os resultados da consulta são armazenados como arquivos JSON no bucket e prefixo especificados. Essa opção é ideal para arquivar resultados, realizar análises em lote ou integrar-se a outros AWS serviços que processam dados do S3.

Você pode entregar os resultados da consulta para um bucket do Amazon S3 na mesma AWS conta da consulta agendada ou para um bucket em uma conta diferente AWS . Opcionalmente, você também pode criptografar os resultados da consulta usando uma AWS KMS chave gerenciada pelo cliente (SSE-KMS).

## Entregando resultados para um bucket do Amazon S3 na mesma conta
<a name="scheduled-queries-s3-same-account"></a>

Quando o bucket do Amazon S3 de destino está na mesma AWS conta da consulta agendada, você pode navegar e selecionar o bucket diretamente do console.

**Para configurar um destino Amazon S3 com a mesma conta (console)**

1. Na seção **Publicar resultados da consulta no S3**, para **bucket do S3**, selecione **Esta** conta.

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/`,) ou escolha Procurar no **Amazon S3 para navegar e selecionar um local existente do Amazon** S3.

1. (Opcional) Para criptografar os resultados com uma AWS KMS chave gerenciada pelo cliente, insira o ARN da chave AWS KMS no campo ARN da chave **KMS**. A chave deve estar na mesma AWS região do bucket Amazon S3 de destino. Se você não especificar uma AWS KMS chave, as configurações de criptografia padrão do bucket serão aplicadas.

1. Na seção **Função do IAM para publicar resultados da consulta no Amazon S3**, escolha **Criar automaticamente uma nova função com permissões padrão** para configurar automaticamente as permissões necessárias ou escolha **Usar uma função existente para selecionar uma função** do IAM existente com as políticas necessárias.

A função do IAM de entrega de destino exige as seguintes permissões:

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::my-bucket/prefix/*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "111122223333"
                }
            }
        }
    ]
}
```

## Entregando resultados para um bucket do Amazon S3 em outra conta
<a name="scheduled-queries-s3-cross-account"></a>

Você pode entregar resultados de consultas programadas para um bucket do Amazon S3 em uma conta diferente AWS . Ao usar um bucket entre contas, você deve fornecer o URI do Amazon S3 e o ID da conta da conta proprietária do bucket.

**Para configurar um destino do Amazon S3 entre contas (console)**

1. Na seção **Publicar resultados da consulta no S3**, para o **bucket do S3**, selecione **Outra conta** e forneça o ID da conta proprietária do bucket como entrada.

1. Para o **URI do Amazon S3**, insira o URI completo do Amazon S3 do bucket de destino e o prefixo na outra conta (por exemplo,). `s3://cross-account-bucket/query-results/`

1. (Opcional) Para criptografar os resultados com uma AWS KMS chave gerenciada pelo cliente, insira o ARN da chave AWS KMS no campo ARN da chave **KMS**. A chave deve estar na mesma AWS região do bucket Amazon S3 de destino.

1. Na seção **Função do IAM para publicar resultados da consulta no Amazon S3**, escolha **Criar automaticamente uma nova função com permissões padrão** para configurar automaticamente as permissões necessárias ou escolha **Usar uma função existente para selecionar uma função** do IAM existente com as políticas necessárias.

A entrega entre contas requer permissões de ambos os lados. A função do IAM de entrega de destino na conta de origem exige as seguintes permissões:

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::cross-account-bucket/prefix/*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "123456789012"
                }
            }
        }
    ]
}
```

A política de bucket do Amazon S3 na conta de destino deve conceder permissão à função IAM da conta de origem para gravar objetos:

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowScheduledQueryRolePutObject",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/my-s3-delivery-role"
            },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::cross-account-bucket/prefix/*"
        }
    ]
}
```

## Criptografando resultados com uma chave gerenciada pelo AWS KMS cliente
<a name="scheduled-queries-s3-kms-encryption"></a>

Opcionalmente, você pode especificar uma AWS KMS chave gerenciada pelo cliente para criptografar os resultados da consulta entregues ao Amazon S3 usando o SSE-KMS. A AWS KMS chave pode estar na mesma conta da consulta agendada ou em uma conta diferente.

Quando você especifica uma AWS KMS chave, a consulta agendada usa essa chave para criptografar os resultados via SSE-KMS. Quando você não especifica uma AWS KMS chave, as configurações de criptografia padrão do bucket se aplicam. Se o bucket estiver configurado com criptografia SSE-KMS padrão usando uma chave gerenciada pelo cliente, a função do IAM de entrega de destino ainda deverá ter `kms:GenerateDataKey` permissão nessa chave.

A função do IAM de entrega de destino exige `kms:GenerateDataKey` permissão na AWS KMS chave. O exemplo a seguir mostra as permissões necessárias para um destino do Amazon S3 com uma chave gerenciada pelo AWS KMS cliente:

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::my-bucket/prefix/*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "111122223333"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "kms:GenerateDataKey",
            "Resource": "arn:aws:kms:us-east-1:111122223333:key/key-id",
            "Condition": {
                "StringEquals": {
                    "kms:ViaService": "s3.us-east-1.amazonaws.com"
                },
                "StringLike": {
                    "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::my-bucket*"
                }
            }
        }
    ]
}
```

Quando a AWS KMS chave está em uma conta diferente da função do IAM de entrega de destino, a política de AWS KMS chaves na conta proprietária da chave deve conceder explicitamente acesso à função:

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowScheduledQueryRoleToEncrypt",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:role/my-s3-delivery-role"
            },
            "Action": "kms:GenerateDataKey",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "kms:ViaService": "s3.us-east-1.amazonaws.com"
                },
                "StringLike": {
                    "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::my-bucket*"
                }
            }
        }
    ]
}
```

**nota**  
Quando a AWS KMS chave e a função do IAM de entrega de destino estão na mesma conta, a política de identidade do IAM sozinha é suficiente se a política de AWS KMS chaves incluir a declaração raiz padrão “Ativar políticas do IAM”. Uma concessão explícita de política de AWS KMS chaves só é necessária se a política de chaves não for delegada ao IAM.

A função do IAM para publicar os resultados da consulta no Amazon S3 deve ser configurada separadamente da função do IAM para a execução programada da consulta. Essa separação permite um controle de acesso refinado, em que a função de execução pode executar consultas, enquanto a função do Amazon S3 trata especificamente da entrega dos resultados. Ambas as funções devem incluir uma política de confiança que permita que o serviço CloudWatch Logs (`logs.amazonaws.com`) assuma a função.

# Solução de problemas de consultas agendadas
<a name="scheduled-queries-troubleshooting"></a>

Use esses tópicos de solução de problemas para resolver problemas comuns com consultas agendadas.

## A execução da consulta falha com erros de permissão
<a name="scheduled-queries-permission-errors"></a>

Resolva erros de permissão que impedem que consultas agendadas sejam executadas ou entreguem resultados aos destinos.

Os erros de permissão ocorrem quando a função de execução não tem as permissões necessárias para ler os grupos de registros ou gravar nos recursos de destino.

**Para resolver erros de permissão**

1. Verifique se a função de execução tem`logs:StartQuery`,`logs:GetQueryResults`, e `logs:DescribeLogGroups` permissões para os grupos de registros de destino.

1. Certifique-se de que a função de execução tenha permissões de gravação para os recursos de destino (como `s3:PutObject` para buckets do S3).

1. Verifique se a política de confiança permite que CloudWatch os Logs assumam a função de execução. A função deve confiar no serviço de registros principal (`logs.amazonaws.com`) em sua política de confiança.

As causas comuns incluem a falta de permissões do IAM, recursos incorretos ARNs na política ou problemas de configuração da política de confiança.

Para evitar erros de permissão, use o princípio do menor privilégio ao criar funções de execução e testar permissões antes de implantar consultas agendadas na produção.

## O tempo limite da consulta
<a name="scheduled-queries-timeout"></a>

Resolva erros de tempo limite que ocorrem quando as consultas agendadas excedem o limite máximo de tempo de execução.

Os tempos limite de consulta ocorrem quando a consulta leva mais de 60 minutos para processar o intervalo de dados especificado, geralmente devido a grandes conjuntos de dados ou a uma lógica de consulta complexa.

**Para resolver erros de tempo limite**

1. Reduza o intervalo de tempo diminuindo o deslocamento da hora de início para processar menos dados por execução.

1. Otimize a consulta adicionando filtros no início da consulta para reduzir a quantidade de dados processados. Use índices de filtro para reduzir o tamanho da digitalização de dados.

1. Considere dividir consultas complexas em consultas mais simples e focadas.

As causas comuns incluem consultar grandes intervalos de tempo, processar grupos de registros de alto volume ou usar agregações complexas sem a filtragem adequada.

Para evitar tempos limite, teste as consultas manualmente no CloudWatch Logs Insights com o volume de dados esperado e otimize o desempenho antes do agendamento.

## Falha no processamento de destino
<a name="scheduled-queries-destination-processing-fails"></a>

Resolva falhas que ocorrem quando os resultados da consulta agendada não podem ser entregues aos destinos configurados.

Falhas no processamento de destino acontecem quando o bucket ou barramento de EventBridge eventos do Amazon S3 de destino está inacessível ou configurado incorretamente.

**Para resolver falhas em que os resultados da consulta não estão sendo publicados no destino**

1. Verifique se o bucket especificado do Amazon S3 existe e está acessível.

1. Verifique se a configuração de destino está correta URIs.

1. Certifique-se de que a função de execução tenha as permissões necessárias para gravar no destino.

As causas comuns incluem recursos de destino excluídos ou renomeados URIs, destino incorreto ou problemas de conectividade de rede.

Para evitar falhas no destino, valide regularmente as configurações do destino e monitore a disponibilidade dos recursos do destino.

## Erros de consulta inválidos
<a name="scheduled-queries-invalid-query"></a>

Resolva erros de sintaxe e lógica em cadeias de caracteres de consulta agendadas que impedem a execução bem-sucedida.

Erros de consulta inválidos ocorrem quando a string de consulta contém erros de sintaxe, faz referência a campos inexistentes ou usa recursos de linguagem de consulta não compatíveis.

**Para resolver erros de consulta inválidos**

1. Teste sua consulta manualmente no CloudWatch Logs Insights para verificar a sintaxe e a lógica.

1. Verifique se todos os campos de registro referenciados existem em seus grupos de registros de destino.

1. Verifique se os recursos de linguagem de consulta que você está usando são compatíveis com consultas agendadas.

As causas comuns incluem erros de digitação nos nomes dos campos, sintaxe de consulta incorreta ou uso de recursos de consulta não suportados no ambiente de execução agendada.

Para evitar erros de consulta inválidos, sempre teste as consultas interativamente antes de programar e use os recursos de descoberta de campo para verificar os nomes dos campos.

## Erros de simultaneidade de consultas
<a name="scheduled-queries-concurrency-errors"></a>

Há alguns pontos importantes mencionados abaixo que você deve ter em mente quando os erros de simultaneidade são vistos, pois as consultas programadas usam a mesma cota das consultas de insights do Cloudwatch Logs. É recomendável distribuir suas agendas para evitar atingir o limite de simultaneidade.
+ **Cota:** você pode executar até 100 consultas simultâneas do CloudWatch Logs Insights por conta. AWS 
+ **Painéis:** as consultas adicionadas aos CloudWatch painéis também contam para esse limite de simultaneidade, pois são executadas quando o painel é carregado ou atualizado.
+ **OpenSearch Serviço PPL/SQL:** você pode executar até 15 consultas OpenSearch PPL ou OpenSearch SQL simultâneas por conta. AWS 
+ **Consultas entre contas: a cota de simultaneidade se aplica tanto a consultas** individuais quanto a consultas entre contas. Ao usar a observabilidade CloudWatch entre contas, as consultas iniciadas em uma conta de monitoramento em relação a uma conta de origem vinculada também contam para o limite de simultaneidade da conta de monitoramento.
+ **Grupos de registros de acesso infrequente:** para grupos de registros na classe de registros de acesso infrequente, o número máximo de consultas simultâneas do Logs Insights é limitado a cinco.