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

Entendendo os conceitos de consultas agendadas

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

As consultas agendadas exigem duas funções separadas do IAM: uma para executar consultas e outra para entregar resultados a destinos como buckets do Amazon S3, barramentos de EventBridge eventos da Amazon ou tabelas de pesquisa. 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 de consultas 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.

Essa separação oferece benefícios práticos para suas operações. Do ponto de vista da segurança, se você precisar alterar o local 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 rastrear claramente qual função acessa dados de registro 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.

Cross-region e uso entre contas

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 a partir da conta de monitoramento usando os grupos de log de todas as contas vinculadas.

Abordagem alternativa: use a centralização de CloudWatch registros para replicar dados de registro de várias contas e regiões em uma conta de monitoramento central. Isso permite que você crie consultas agendadas em uma única região que acesse todos os seus registros centralizados, evitando consultas entre regiões e simplificando o gerenciamento de permissões do IAM.

Expressões de cronograma e tratamento de fuso horário

A programação que você define determina quando sua consulta é executada e com que frequência ela é executada. Escolher a expressão de agendamento correta afeta o momento em que você recebe os resultados e a quantidade de dados que 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 se alinhem aos cronogramas operacionais. No console, você também pode agendar consultas usando opções fáceis de calendário.

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 horários comerciais 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 considerar 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

As consultas agendadas suportam 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á principalmente filtrando e agregando dados de log, 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 em várias etapas, a abordagem de pipeline da 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.

Seleção de destinos e casos de uso

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 ambos. Entender 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, os resultados EventBridge são apresentados como eventos aos quais seus aplicativos podem responder instantaneamente. Por padrão, todos os eventos de conclusão de consultas são enviados automaticamente como eventos para o barramento de eventos padrão, permitindo a integração com sistemas de processamento downstream, funções do Lambda ou outras arquiteturas orientadas por eventos. Os resultados só são publicados nos destinos quando a consulta é executada com êxito. Os destinos da tabela de pesquisa são otimizados para manter os dados de referência atualizados. O destino da tabela de pesquisa preenche ou atualiza automaticamente a tabela de pesquisa especificada com os resultados da consulta em cada execução agendada, para que outras consultas possam referenciar os dados mais recentes com o comando. lookup

Formato e estrutura do resultado da consulta

As consultas agendadas fornecem resultados no formato JSON, mas cada tipo de destino recebe uma carga diferente. Para um destino de tabela de pesquisa, os resultados da consulta se tornam o conteúdo da tabela de pesquisa e cada execução substitui esse conteúdo. Para obter mais informações, consulte Configurando destinos da tabela de pesquisa para consultas agendadas.

Os destinos do Amazon S3 recebem as linhas de resultados da consulta. Cada objeto contém uma matriz JSON com uma entrada para cada linha no conjunto de resultados, e cada entrada mapeia os nomes dos campos de saída da consulta de acordo com seus valores. O objeto não contém metadados de consulta nem estatísticas de consulta e omite o @ptr campo mesmo que a consulta solicite, porque esse campo só pode ser usado no console.

EventBridge os destinos recebem metadados da consulta, incluindo as estatísticas da consulta, mas nenhuma linha de resultados. Para recuperar as linhas de uma consulta concluída, chame GetQueryResults com o valor de queryId do evento.

O exemplo a seguir mostra o evento no qual o CloudWatch Logs é publicado EventBridge quando uma consulta agendada é concluída.

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

Essa consulta não é agregada e retornou menos linhas do que a limit de 10.000, portanto, cada um dos 1.842 eventos de log correspondentes se tornou uma linha de saída recordsMatched e resultCount é igual. Uma consulta que agrega, ou uma cujo conjunto de resultados é truncado porlimit, produz um resultCount valor menor que. recordsMatched Para obter mais informações, consulte Compreendendo os registros digitalizados, os registros combinados e a contagem de resultados.

Os principais elementos incluem:

A tabela a seguir descreve cada campo no statistics objeto. Para ver as definições de API desses campos, consulte QueryStatistics.

Compreendendo os registros digitalizados, os registros combinados e a contagem de resultados

Três das estatísticas de consulta contam coisas diferentes, e compará-las diretamente pode ser enganoso. Cada um mede um estágio diferente do processamento da consulta:

Cada estágio restringe os dados. Um comando como o que stats combina vários eventos de log em uma única linha de saída, portanto, resultCount pode ser muito menor que recordsMatched o. Um grande recordsMatched com um pequeno resultCount não significa que faltam linhas no conjunto de resultados.

Exemplo — Agregação

A consulta a seguir conta as mensagens de erro em cada fluxo de log de um grupo de logs em um período de uma hora.

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

Se a consulta ler 1.500.000 eventos de log, 24.318 deles contiveremERROR, e os eventos de registro correspondentes vierem de 12 fluxos de log, a consulta será concluída com as estatísticas a seguir.

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

statsproduz uma linha para cada fluxo de log, então resultCount é 12 e recordsMatched é 24.318. Os 12 valores de errorCount somam 24.318.

Exemplo — Post-aggregation filtro

A consulta a seguir mantém somente os fluxos de log que produziram mais de 1.000 erros.

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

O filter comando final é executado após o agrupamento, então ele remove linhas do conjunto de resultados em vez de registrar eventos da verificação. Se 3 dos 12 fluxos de log tiverem um valor errorCount maior que 1.000, então será resultCount 3 em vez de 12. recordsScannede bytesScanned não altere, porque a consulta lê os mesmos dados de log de qualquer maneira.

Exemplo — Limite

Um limit comando reduz resultCount sem qualquer agregação. A consulta a seguir retorna as 100 mensagens de erro mais recentes.

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

Se a consulta verificar os mesmos 1.500.000 eventos de log e corresponder aos mesmos 24.318, então será 100, porque limita o resultCount conjunto de resultados a 100 limit linhas. No console, você vê essa relação como Mostrando 100 dos 24.318 registros correspondidos.

Cada estatística responde a uma pergunta diferente.