Como funcionam os alarmes de log Ciclo de vida de consultas agendadas gerenciadas Configuração de alarmes de log Consulta de logs Expressões de agregação Alarmes com vários colaboradores Tratamento de dados ausentes Estados de avaliação Atualização de alarme Ações e notificações Práticas recomendas e solução de problemas

Alarmes de log

Um alarme de log monitora os resultados de uma consulta do CloudWatch Logs Insights que é executada em uma programação usando uma Consulta Agendada. O alarme aplica uma expressão de agregação aos resultados da consulta para produzir um valor numérico e, quando esse valor agregado ultrapassa um limite configurado, o alarme passa para o estado ALARM e executa as ações configuradas.

Ao contrário dos alarmes de métrica que exigem filtros de métrica como etapa intermediária, os alarmes de log avaliam diretamente os dados de log usando a mesma linguagem de consulta do Logs Insights que você utiliza para análise ad-hoc.

Como funcionam os alarmes de log

As etapas mostradas a seguir descrevem como um alarme de log funciona:

Você cria um alarme de log com uma consulta, expressão de agregação, cronograma e limite.
O CloudWatch cria automaticamente uma consulta agendada gerenciada pela AWS que executa sua consulta no cronograma especificado.
Cada execução de consulta produz resultados agregados (um único valor ou vários valores de colaborador).
O CloudWatch avalia os resultados agregados em relação ao seu limite usando a avaliação M-out-of-N em execuções recentes de consultas.
Se o limite for violado, o alarme passa para o estado ALARM e executa suas ações configuradas (como notificações do Amazon SNS).

nota

Os alarmes de log avaliam as últimas N execuções de consultas. O alarme muda para ALARM quando M dessas N execuções violam o limite.

Para criar um alarme de log, consulte Criar um alarme de log.

Ciclo de vida de consultas agendadas gerenciadas

Quando você cria um alarme de log, o CloudWatch cria automaticamente uma consulta agendada gerenciada pela AWS que executa sua consulta no cronograma especificado. Não é necessário criar a consulta agendada separadamente.

A consulta agendada gerenciada pela AWS tem as seguintes características:

É visível no console do CloudWatch Logs em Consultas Agendadas.
Não é possível modificá-la diretamente. Para alterar a consulta ou sua configuração, atualize o alarme de log.
O CloudWatch exclui a consulta agendada gerenciada pela AWS quando você exclui o alarme.

Configuração de alarmes de log

Um alarme de log é configurado com os seguintes parâmetros:

QueryString é a consulta do CloudWatch Logs Insights a ser executada.
LogGroupIdentifiers são os grupos de logs a serem consultados. Especifique os nomes dos grupos de logs ou os ARNs do grupo de logs.
ScheduledQueryRoleARN é o ARN do perfil do IAM que permite que o CloudWatch Logs execute a consulta agendada em seu nome.
AggregationExpression define como os resultados da consulta são agregados em um valor numérico para avaliação do limite.
ScheduleExpression define a frequência com que a consulta é executada (por exemplo, rate(5 minutes)).
StartTimeOffset define a janela de retrospectiva em segundos para cada execução de consulta.
EndTimeOffset define o final do intervalo de tempo da consulta como um deslocamento em segundos em relação à hora atual.
ComparisonOperator é como os resultados agregados são comparados ao limite. Valores válidos: GreaterThanThreshold, GreaterThanOrEqualToThreshold, LessThanThreshold, LessThanOrEqualToThreshold.
Threshold é o valor numérico com o qual comparar.
QueryResultsToEvaluate é o número de execuções de consultas recentes a serem avaliadas (N em M-out-of-N).
QueryResultsToAlarm é o número de resultados de violação necessários para acionar ALARM (M em M-out-of-N).
TreatMissingData define como os resultados de consultas ausentes são tratados durante a avaliação.

Para obter a lista completa de parâmetros e instruções de criação, veja Criar um alarme de log.

Consulta de logs

A consulta do alarme de log é uma consulta do CloudWatch Logs Insights que seleciona e filtra os dados de log a serem avaliados. A consulta é executada nos grupos de logs especificados em LogGroupIdentifiers no intervalo de tempo definido por StartTimeOffset e EndTimeOffset.

A consulta usa a sintaxe de consulta do CloudWatch Logs Insights. Para obter diretrizes sobre como escrever consultas eficientes para alarmes de log, veja Práticas recomendas e solução de problemas.

Expressões de agregação

A expressão de agregação define como o CloudWatch resume os resultados da consulta em um valor numérico para avaliação do limite. A expressão utiliza a mesma sintaxe do comando stats no CloudWatch Logs Insights.

A sintaxe de uma expressão de agregação é a seguinte:


statistic_func_expression [by field1, field2, ...] [| sort asc|desc]

Você pode especificar apenas uma única expressão de agregação. A tabela mostrada a seguir lista as funções de agregação compatíveis.

Funções de agregação compatíveis
Função	Descrição	Exemplo
`count(*)`	Contagem de todas as linhas de log correspondentes.	`count(*)`
`avg(field)`	O valor médio do campo especificado.	`avg(duration)`
`sum(field)`	Soma do campo especificado.	`sum(bytesSent)`
`min(field)`	Valor mínimo do campo especificado.	`min(latency)`
`max(field)`	Valor máximo do campo especificado.	`max(latency)`

A função bin() não é compatível com a cláusula by da expressão de agregação. Porém, é possível usar bin() na própria string de consulta.

Alarmes com vários colaboradores

Quando você inclui uma cláusula by em sua expressão de agregação, o alarme avalia cada combinação exclusiva de valores de campo (chamada de colaborador) de maneira independente. O alarme muda para o estado ALARM se algum colaborador violar o limite.

Por exemplo, a expressão mostrada a seguir agrupa as contagens de erro por nome do serviço:


count(*) by serviceName

Cada valor exclusivo de serviceName é avaliado de maneira independente em relação ao limite. Se algum serviço exceder o limite em M de N execuções de consulta, o alarme entrará no estado ALARM.

Os seguintes limites se aplicam aos alarmes de vários colaboradores:

Máximo de 5 campos na cláusula by.
Máximo de 500 resultados de colaboradores retornados por execução de consulta.
Máximo de 100 colaboradores rastreados no estado ALARM simultaneamente.

Por padrão, os colaboradores são classificados alfabeticamente e somente os primeiros 500 são retornados por execução de consulta. Em vez disso, para classificar os colaboradores pelo valor agregado, especifique | sort asc ou | sort desc em sua expressão de agregação (por exemplo, avg(latency) by serviceName | sort desc). A classificação baseada em valores garante que os colaboradores mais significativos sejam avaliados primeiro quando o número total exceder 500.

Para alarmes de vários colaboradores, as ações do Amazon SNS e do Lambda são executadas no nível do colaborador (uma vez por colaborador que comete violação). As ações do Systems Manager OpsItem são executadas no nível do alarme.

nota

O Systems Manager Incident Manager e as ações de investigação não são compatíveis com alarmes de log.

Se um colaborador desaparecer dos resultados da consulta (por exemplo, um recurso efêmero for encerrado), esse colaborador passará para o estado OK, independentemente da configuração de tratamento de dados ausentes.

Tratamento de dados ausentes

Dados ausentes ocorrem quando a execução de uma consulta agendada não produz um valor que possa ser avaliado em relação ao limite. Isso acontece nos seguintes casos:

Nenhum log presente — o grupo de logs não contém eventos de log no intervalo de tempo da consulta.

A consulta não retorna resultados aplicáveis — os logs estão presentes, mas a expressão de agregação não consegue produzir um valor. Isso acontece quando:

Os resultados da consulta correspondente não estavam presentes de acordo com o filtro de consulta.
O campo referenciado na expressão de agregação não estava presente nos resultados da consulta. Por exemplo, count(error-codes) em que error-codes não existe nos eventos de logs retornados.

Observe que count(*) em um conjunto de resultados vazio retorna 0, que é um ponto de dados válido e não é tratado como ausente.

É possível configurar como o alarme trata os dados ausentes usando o parâmetro TreatMissingData. A tabela a seguir descreve as opções disponíveis.

Opções de tratamento de dados ausentes
Valor	Comportamento
`missing`	Trate o ponto de dados como ausente. Esse é o padrão.
`notBreaching`	Tratar dados de pontos ausentes como não violando o limite.
`breaching`	Tratar dados de pontos ausentes como violando o limite.
`ignore`	Ignorar o ponto de dados ausente e avaliar somente os dados disponíveis.

Estados de avaliação

Além dos estados padrão OK, ALARM e INSUFFICIENT_DATA, os alarmes de log podem relatar os seguintes estados de avaliação no campo EvaluationState. Esses estados fornecem contexto adicional sobre por que o alarme está no estado atual.

Estados de avaliação do alarme de log
Estado	Descrição
`EVALUATION_FAILURE`	Um problema transitório do serviço CloudWatch impediu a avaliação. Isso pode ocorrer quando o serviço enfrenta problemas na avaliação dos resultados da consulta devido a erros do serviço ou quando alguns (mas não todos) os resultados da consulta falham. O alarme muda para `INSUFFICIENT_DATA`. Recomendamos o monitoramento manual até que o problema seja resolvido.
`EVALUATION_ERROR`	Um erro de configuração do cliente impediu a avaliação. Isso pode ocorrer devido a permissões insuficientes, consulta inválida ou quando todos os resultados da consulta falharam. O alarme muda para `INSUFFICIENT_DATA` imediatamente. Consulte o campo `StateReason` para obter detalhes.
`PARTIAL_DATA`	A consulta retornou o máximo de 500 grupos de colaboradores, no entanto, mais grupos corresponderam. O alarme avalia os colaboradores disponíveis, mas os resultados podem estar incompletos.

Atualização de alarme

Quando você atualiza a consulta, a expressão de agregação, o agendamento ou os grupos de logs de um alarme de log, o alarme passa para INSUFFICIENT_DATA até que novos pontos de dados suficientes sejam coletados. Alterações no limite ou nos valores M-out-of-N não acionam essa redefinição.

Ações e notificações

Os alarmes dde log são compatíveis com as seguintes ações:

Notificações do Amazon SNS
Invocações da função do Lambda
Criação do OpsItem do Systems Manager

Para ver a matriz completa de ações compatíveis, consulte Ações de alarme.

Quando um alarme de log muda de estado, a notificação de ação inclui as seguintes informações:

Informações padrão de alteração da configuração do alarme (nome do alarme, descrição, detalhes da configuração).
Informações sobre mudança de estado (novo estado, motivo do estado, data e hora).
As notificações por e-mail do Amazon SNS também incluem um link direto para o console do CloudWatch Logs Insights que mostra os resultados completos da consulta.

O exemplo mostrado a seguir mostra uma notificação por e-mail do Amazon SNS para um alarme de log de valor único (sem uma cláusula BY):


{
    "AlarmName": "HighErrorCount",
    "NewStateValue": "ALARM",
    "NewStateReason": "Threshold Crossed: 3 out of the last 5 query results [142.0 (10/06/26 12:15:00), 135.0 (10/06/26 12:10:00), 120.0 (10/06/26 12:05:00)] were greater than the threshold (100.0) (minimum 3 datapoints for OK -> ALARM transition).",
    "NewStateReasonData": {
        "version": "1.0",
        "queryDate": "2026-06-10T12:15:30.000+0000",
        "threshold": 100.0,
        "queryResultsToEvaluate": 5,
        "queryResultsToAlarm": 3,
        "results": [
            {
                "queryResultId": "scheduled-query-execution-id-3",
                "status": "COMPLETE",
                "timestamp": "2026-06-10T12:15:00.000+0000",
                "value": 142.0
            }
            // Additional results...
        ]
    },
    "StateChangeTime": "2026-06-10T12:15:30.000+0000",
    "OldStateValue": "OK"
    // Additional fields...
}

O exemplo mostrado a seguir mostra uma notificação por e-mail do Amazon SNS para um alarme de log com vários colaboradores (com uma cláusula BY). Cada colaborador em violação gera uma notificação separada:


{
    "AlarmName": "EndpointLatency",
    "NewStateValue": "ALARM",
    "NewStateReason": "5 out of 10 contributors evaluated to ALARM",
    "StateChangeTime": "2026-06-10T12:20:15.000+0000",
    "OldStateValue": "OK",
    "AlarmContributorId": "a1b2c3d4e5f6g7h8",
    "AlarmContributorAttributes": {
        "endpoint": "/api/orders"
    }
    // Additional fields...
}

Incluindo linhas de log nas notificações

De maneira opcional, você pode incluir linhas de log de resultados de consultas brutas em notificações de alarme definindo o parâmetro ActionLogLineCount para um valor entre 1 e 50. Esses são os eventos de logs subjacentes nos quais a expressão de agregação é avaliada, não os valores agregados. O valor padrão é 0, o que significa que nenhuma linha de log é inclusa.

nota

As linhas de log são incluídas apenas nas notificações por e-mail do Amazon SNS. As ações do Lambda não incluem linhas de log em suas cargas.

Importante

Incluir linhas de log nas notificações pode expor dados sensíveis de seus logs nas mensagens do Amazon SNS. Revise o conteúdo do seu log antes de habilitar esse atributo.

Para incluir linhas de log, a função de linhas de log deve ter a permissão logs:GetQueryResults. O número de linhas de log incluídas em uma notificação é limitado pela contagem solicitada, pelo total de resultados disponíveis e pelo limite de tamanho de carga útil do Amazon SNS.

Práticas recomendas e solução de problemas

Práticas recomendadas

Otimização de consultas

Teste as consultas manualmente no CloudWatch Logs Insights antes de usá-las em um alarme de log para verificar a performance e os resultados esperados.
Utilize comandos de filtro logo no início da consulta para reduzir o volume de dados processados.
Limite os intervalos de tempo de consulta (StartTimeOffset) para evitar tempos limite com grupos de logs de alto volume.
Utilize índices de campo para otimizar a performance da consulta.

Planejamento do cronograma

Escolha uma frequência de cronograma que permita que as consultas sejam concluídas antes da próxima execução. Para grupos de logs de alto volume, utilize intervalos maiores (por exemplo, 10 minutos em vez de 5).
Considere os atrasos na ingestão de logs ao definir StartTimeOffset. Uma pequena lacuna entre EndTimeOffset e a hora atual ajuda a evitar a avaliação de dados incompletos.
Distribua os cronogramas de alarme de log em toda a sua conta para evitar atingir os limites de simultaneidade da Consulta Agendada. As execuções simultâneas de consultas em sua conta não podem ultrapassar de 100. Considere essa cota ao criar vários alarmes de log com horários sobrepostos.

Ajuste de limite

Comece com valores mais altos de QueryResultsToEvaluate (N) para reduzir o ruído de alarme causado por picos transitórios.
Para eventos esparsos (como erros que raramente ocorrem), defina TreatMissingData como notBreaching para manter o alarme no estado OK quando nenhum log corresponder.
Para sinais contínuos (como logs de tráfego), considere configurar TreatMissingData como breaching para detectar quando os dados de log esperados param de chegar.

Design com vários colaboradores

Escolha campos significativos para a cláusula BY que representem recursos ou dimensões distintos que você deseja monitorar de maneira independente.
Lembre-se de que apenas os primeiros 500 colaboradores são retornados por execução de consulta. Se você espera mais, restrinja sua consulta ou utilize menos campos da cláusula BY.
Utilize o sufixo | sort desc ou | sort asc em sua expressão de agregação para priorizar os valores mais altos ou mais baixos com base no seu operador de comparação quando o limite de 500 colaboradores for atingido.

Solução de problemas

O alarme permanece em INSUFFICIENT_DATA

Possível causa	Resolução
A função de execução de consultas agendadas não tem permissões	Verifique se a função tem as permissões `logs:StartQuery`, `logs:StopQuery`, `logs:GetQueryResults` e `logs:DescribeLogGroups` definidas para os grupos de logs corretos.
O grupo de logs não existe ou foi excluído	Verifique se os ARNs do grupo de logs na configuração do alarme estão corretos e acessíveis.
Alarme criado ou atualizado recentemente	Após a criação ou atualização da configuração, o alarme permanece em INSUFFICIENT_DATA até que execuções de consulta suficientes sejam concluídas para satisfazer a janela de avaliação M-out-of-N.
A consulta agendada não está sendo executada	Verifique a consulta agendada gerenciada pela AWS no console do CloudWatch Logs para verificar se ela está sendo executada dentro do cronograma.
Campo de agregação ausente nos resultados da consulta	O campo referenciado na expressão de agregação deve estar presente nos resultados da consulta. Por exemplo, se sua agregação for `avg(latency)`, certifique-se de que a consulta produza um campo `latency`. Se o campo não estiver presente, o resultado será tratado como dado ausente.
Atraso na ingestão de logs	Uma consulta agendada só pode avaliar eventos de logs que tenham sido ingeridos no momento em que é executada. `StartTimeOffset` e `EndTimeOffset` definem a janela de consulta em relação ao tempo de execução T — [T − StartTimeOffset, T − EndTimeOffset] — mas elas não levam em conta o atraso na ingestão. Se os eventos ainda estiverem sendo ingeridos para a janela que você consulta, a consulta será executada antes de estarem disponíveis e os ignorará. Use `EndTimeOffset` para deslocar a janela para trás o suficiente para que a ingestão seja concluída em todo o intervalo. Exemplo: suponha que os logs demorem até 2 minutos para serem consultados após a ocorrência dos eventos. `StartTimeOffset=60, EndTimeOffset=0` — janela [T−60s, T]. A janela termina no momento da execução, logo, os eventos recentes ainda não foram ingeridos e foram perdidos. `StartTimeOffset=180, EndTimeOffset=120` — janela [T−180s, T−120s]. A janela termina 2 minutos no passado, momento em que todos os eventos foram ingeridos e estão avaliáveis.

O alarme mostra EVALUATION_ERROR

Isso indica um problema na configuração do cliente. Veja os detalhes no campo StateReason. Causas comuns:

Sintaxe de consulta inválida ou malformada.
Permissões insuficientes da função de execução da consulta agendada.
Todas as execuções de consultas falharam (por exemplo, permissões de grupos de logs revogadas).

O alarme mostra EVALUATION_FAILURE

Isso indica um problema transitório no serviço CloudWatch. O alarme é recuperado de maneira automática quando o problema é resolvido. Se persistir além de alguns minutos, verifique o painel de integridade do serviço CloudWatch.

O alarme mostra PARTIAL_DATA

A consulta retornou o máximo de 500 grupos de colaboradores, no entanto, mais grupos corresponderam. O alarme avalia os colaboradores disponíveis, mas os resultados podem estar incompletos. Considere restringir sua consulta ou reduzir o número de campos da cláusula BY.

As linhas de log não aparecem nas notificações

Verifique se ActionLogLineCount está definido com um valor entre 1 e 50.
Verifique se a função de linhas de log tem a permissão logs:GetQueryResults definida para os grupos de logs corretos.
As linhas de log são incluídas apenas nas notificações por e-mail do Amazon SNS. Outros tipos de ação não incluem linhas de log.
As consultas que usam unmask() não podem incluir linhas de log nas notificações (rejeitadas no momento da criação).

Para obter melhores práticas adicionais sobre otimização, monitoramento e autorização de consultas, consulte as Melhores práticas de consultas agendadas no Guia do usuário do Amazon CloudWatch Logs.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Alarmes do PromQL

Alarmes compostos