# 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/ScheduledQueries.html). 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:
1. Você cria um alarme de log com uma consulta, expressão de agregação, cronograma e limite.
1. O CloudWatch cria automaticamente uma consulta agendada gerenciada pela AWS que executa sua consulta no cronograma especificado.
1. Cada execução de consulta produz resultados agregados (um único valor ou vários valores de colaborador).
1. 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.
1. 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](Alarm-On-Logs.md#Create_Log_Alarm).
## 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](Alarm-On-Logs.md#Create_Log_Alarm).
## 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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html). Para obter diretrizes sobre como escrever consultas eficientes para alarmes de log, veja [Práticas recomendas e solução de problemas](#log-alarm-best-practices).
## 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](alarm-actions.md).
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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/scheduled-queries-best-practices.html) no *Guia do usuário do Amazon CloudWatch Logs*.