Come funzionano i Log Alarm Ciclo di vita delle query pianificate gestite Configurazione Log Alarm Richiesta di registro Espressioni di aggregazione Multi-contributor allarmi Trattamento dei dati mancanti Stati di valutazione Aggiornamento dell'allarme Azioni e notifiche Best practice e risoluzione dei problemi

Registra allarmi

Un Log Alarm monitora i risultati di una query di CloudWatch Logs Insights eseguita secondo una pianificazione utilizzando una query pianificata. L'allarme applica un'espressione di aggregazione ai risultati della query per produrre un valore numerico e, quando quel valore aggregato supera una soglia configurata, l'allarme passa allo stato ed esegue le azioni configurate. ALARM

A differenza degli allarmi metrici che richiedono filtri metrici come fase intermedia, Log Alarms valuta direttamente i dati di registro utilizzando lo stesso linguaggio di interrogazione di Logs Insights utilizzato per l'analisi ad hoc.

Come funzionano i Log Alarm

I passaggi seguenti descrivono come funziona un Log Alarm:

Si crea un Log Alarm con una query, un'espressione di aggregazione, una pianificazione e una soglia.
CloudWatch crea automaticamente una AWS Scheduled Query gestita che esegue la query secondo la pianificazione specificata.
Ogni esecuzione di query produce risultati aggregati (un valore singolo o più valori del collaboratore).
CloudWatch valuta i risultati aggregati rispetto alla soglia specificata utilizzando la M-out-of-N valutazione delle esecuzioni di query recenti.
Se la soglia viene superata, l'allarme passa allo ALARM stato ed esegue le azioni configurate (come le notifiche di Amazon SNS).

Nota

Log Alarms valuta le ultime N esecuzioni di query. L'allarme passa a ALARM quando M di quelle N esecuzioni superano la soglia.

Per creare un allarme di registro, vedere. Crea un avviso di registro

Ciclo di vita delle query pianificate gestite

Quando si crea un Log Alarm, crea CloudWatch automaticamente una query pianificata AWS gestita che esegue la query secondo la pianificazione specificata. Non è necessario creare la Scheduled Query separatamente.

L'interrogazione pianificata AWS gestita presenta le seguenti caratteristiche:

È visibile nella console CloudWatch Logs in Query pianificate.
Non è possibile modificarlo direttamente. Per modificare la query o la sua configurazione, aggiorna il Log Alarm.
CloudWatch elimina la Scheduled Query AWS gestita quando si elimina l'allarme.

Configurazione Log Alarm

Un Log Alarm è configurato con i seguenti parametri:

QueryStringè la query di CloudWatch Logs Insights da eseguire.
LogGroupIdentifierssono i gruppi di log da interrogare. Specificare i nomi dei gruppi di log o gli ARN dei gruppi di log.
ScheduledQueryRoleARNè l'ARN del ruolo IAM che consente a CloudWatch Logs di eseguire la query pianificata per tuo conto.
AggregationExpressiondefinisce come i risultati della query vengono aggregati in un valore numerico per la valutazione della soglia.
ScheduleExpressiondefinisce la frequenza di esecuzione della query (ad esempio,rate(5 minutes)).
StartTimeOffsetdefinisce la finestra di lookback in secondi per ogni esecuzione di query.
EndTimeOffsetdefinisce la fine dell'intervallo di tempo della query come un offset in secondi rispetto all'ora corrente.
ComparisonOperatorè il modo in cui i risultati aggregati vengono confrontati con la soglia. Valori validi: GreaterThanThreshold, GreaterThanOrEqualToThreshold, LessThanThreshold, LessThanOrEqualToThreshold.
La soglia è il valore numerico con cui effettuare il confronto.
QueryResultsToEvaluateè il numero di esecuzioni di query recenti da valutare (N in M-out-of-N).
QueryResultsToAlarmè il numero di risultati di violazione necessari per l'attivazione ALARM (M in M-out-of-N).
TreatMissingDatadefinisce come vengono trattati i risultati delle query mancanti durante la valutazione.

Per l'elenco completo dei parametri e delle istruzioni per la creazione, vedereCrea un avviso di registro.

Richiesta di registro

La query Log Alarm è una query di CloudWatch Logs Insights che seleziona e filtra i dati di registro da valutare. La query viene eseguita sui gruppi di log specificati nell'LogGroupIdentifiersintervallo di tempo definito da StartTimeOffset e. EndTimeOffset

La query utilizza la sintassi delle query CloudWatch di Logs Insights. Per linee guida sulla scrittura di query efficienti per Log Alarms, vedere. Best practice e risoluzione dei problemi

Espressioni di aggregazione

L'espressione di aggregazione definisce come CloudWatch riepilogare i risultati della query in un valore numerico per la valutazione della soglia. L'espressione utilizza la stessa sintassi del stats comando in Logs Insights. CloudWatch

La sintassi per un'espressione di aggregazione è la seguente:


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

È possibile specificare una sola espressione di aggregazione. La tabella seguente elenca le funzioni di aggregazione supportate.

Funzioni di aggregazione supportate
Funzione	Description	Esempio
`count(*)`	Conteggio di tutte le righe di registro corrispondenti.	`count(*)`
`avg(field)`	Valore medio del campo specificato.	`avg(duration)`
`sum(field)`	Somma del campo specificato.	`sum(bytesSent)`
`min(field)`	Valore minimo del campo specificato.	`min(latency)`
`max(field)`	Valore massimo del campo specificato.	`max(latency)`

La bin() funzione non è supportata nella by clausola di espressione di aggregazione. Tuttavia, è possibile utilizzarla bin() nella stringa di query stessa.

Multi-contributor allarmi

Quando includi una by clausola nell'espressione di aggregazione, l'allarme valuta ogni combinazione unica di valori di campo (chiamata contributore) in modo indipendente. L'allarme passa a ALARM indicare se un collaboratore supera la soglia.

Ad esempio, l'espressione seguente raggruppa i conteggi degli errori in base al nome del servizio:


count(*) by serviceName

Ogni valore univoco di serviceName viene valutato indipendentemente rispetto alla soglia. Se un servizio supera la soglia nelle esecuzioni di query M su N, l'allarme entra nello stato. ALARM

I seguenti limiti si applicano agli allarmi con più contributori:

Massimo 5 campi nella clausola. by
Massimo 500 risultati restituiti dai collaboratori per esecuzione di una query.
Massimo 100 contributori monitorati contemporaneamente nello ALARM stato.

Per impostazione predefinita, i contributori vengono ordinati alfabeticamente e vengono restituiti solo i primi 500 per esecuzione della query. Per ordinare invece i contributori in base al loro valore aggregato, specifica | sort asc o | sort desc nell'espressione di aggregazione (ad esempio,). avg(latency) by serviceName | sort desc Value-based l'ordinamento assicura che i contributori più importanti vengano valutati per primi quando il numero totale supera i 500.

Per gli allarmi con più contributori, le azioni di Amazon SNS e Lambda vengono eseguite a livello di contributore (una volta per collaboratore che viola). OpsItem Le azioni di Systems Manager vengono eseguite a livello di allarme.

Nota

Systems Manager Incident Manager e le azioni di indagine non sono supportate per Log Alarms.

Se un collaboratore scompare dai risultati della query (ad esempio, una risorsa temporanea viene interrotta), tale collaboratore passa allo stato indipendentemente dall'impostazione di trattamento dei dati mancante. OK

Trattamento dei dati mancanti

I dati mancanti si verificano quando l'esecuzione di una query pianificata non produce un valore che possa essere valutato rispetto alla soglia. Questo succede nei seguenti casi:

Nessun registro presente: il gruppo di log non contiene eventi di registro nell'intervallo di tempo della query.

La query non restituisce risultati applicabili: i log sono presenti ma l'espressione di aggregazione non può produrre un valore. Ciò accade quando:

I risultati delle query corrispondenti non erano presenti secondo il filtro di query.
Il campo a cui si fa riferimento nell'espressione di aggregazione non era presente nei risultati della query. Ad esempio, count(error-codes) where error-codes non esiste negli eventi di registro restituiti.

Nota che count(*) su un set di risultati vuoto restituisce 0, che è un datapoint valido e non viene considerato mancante.

È possibile configurare il modo in cui l'allarme tratta i dati mancanti utilizzando il parametro. TreatMissingData La tabella seguente descrive le opzioni disponibili.

Opzioni di trattamento dei dati mancanti
Valore	Comportamento
`missing`	Considera il datapoint come mancante. Questa è l’impostazione predefinita.
`notBreaching`	Considera il datapoint mancante come se non superasse la soglia.
`breaching`	Considera il datapoint mancante come se violasse la soglia.
`ignore`	Ignora il datapoint mancante e valuta solo i dati disponibili.

Stati di valutazione

Oltre agli INSUFFICIENT_DATA stati standard e OKALARM, Log Alarms può riportare EvaluationState sul campo i seguenti stati di valutazione. Questi stati forniscono un contesto aggiuntivo sul motivo per cui l'allarme si trova nello stato attuale.

Log Alarm (stati di valutazione)
Stato	Description
`EVALUATION_FAILURE`	Un problema temporaneo del CloudWatch servizio ha impedito la valutazione. Ciò può verificarsi quando il servizio riscontra problemi nella valutazione dei risultati delle query a causa di errori di servizio o quando alcuni (ma non tutti) i risultati delle query hanno esito negativo. L'allarme passa a. `INSUFFICIENT_DATA` Consigliamo il monitoraggio manuale fino alla risoluzione del problema.
`EVALUATION_ERROR`	Un errore di configurazione del client ha impedito la valutazione. Ciò può verificarsi a causa di autorizzazioni insufficienti, di una query non valida o quando tutti i risultati della query non sono riusciti. L'allarme passa a Immediatamente. `INSUFFICIENT_DATA` Fai riferimento al `StateReason` campo per i dettagli.
`PARTIAL_DATA`	La query ha restituito un massimo di 500 gruppi di collaboratori, ma più gruppi corrispondenti. L'allarme valuta i contributori disponibili, ma i risultati potrebbero essere incompleti.

Aggiornamento dell'allarme

Quando si aggiorna la query, l'espressione di aggregazione, la pianificazione o i gruppi di log di un Log Alarm, l'allarme viene attivato INSUFFICIENT_DATA fino a quando non vengono raccolti nuovi punti dati sufficienti. Le modifiche alla soglia o ai M-out-of-N valori non attivano questo ripristino.

Azioni e notifiche

Log Alarm supporta le seguenti azioni:

Notifiche Amazon SNS
Invocazioni della funzione Lambda
OpsItem Creazione di Systems Manager

Per la matrice completa di supporto alle azioni, vedereOperazione per gli allarmi.

Quando uno stato di transizione di Log Alarm cambia, la notifica dell'azione include le seguenti informazioni:

Informazioni standard sulla modifica della configurazione dell'allarme (nome dell'allarme, descrizione, dettagli di configurazione).
Informazioni sulla modifica dello stato (nuovo stato, motivo dello stato, timestamp).
Le notifiche e-mail di Amazon SNS includono anche un collegamento diretto alla console CloudWatch Logs Insights che mostra i risultati completi delle query.

L'esempio seguente mostra una notifica e-mail di Amazon SNS per un Log Alarm a valore singolo (senza clausola): 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...
}

L'esempio seguente mostra una notifica e-mail di Amazon SNS per un Log Alarm multi-contributore (con una clausola). BY Ogni collaboratore responsabile della violazione genera una notifica separata:


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

Inclusione di righe di registro nelle notifiche

Facoltativamente, è possibile includere righe di registro dei risultati delle interrogazioni non elaborate nelle notifiche di allarme impostando il ActionLogLineCount parametro su un valore compreso tra 1 e 50. Questi sono gli eventi di registro sottostanti su cui viene valutata l'espressione di aggregazione, non i valori aggregati. Il valore predefinito è 0, il che significa che non sono incluse righe di registro.

Nota

Le righe di registro sono incluse solo nelle notifiche e-mail di Amazon SNS. Le azioni Lambda non includono le righe di registro nei rispettivi payload.

Importante

L'inclusione di righe di registro nelle notifiche potrebbe esporre i dati sensibili dei log nei messaggi Amazon SNS. Controlla il contenuto del registro prima di abilitare questa funzionalità.

Per includere le righe di registro, il ruolo log lines deve disporre dell'logs:GetQueryResultsautorizzazione. Il numero di righe di log incluse in una notifica è limitato dal numero di richieste, dai risultati totali disponibili e dal limite di dimensione del payload di Amazon SNS.

Best practice e risoluzione dei problemi

Best practice

Ottimizzazione delle query

Prova manualmente le query in CloudWatch Logs Insights prima di utilizzarle in un Log Alarm per verificare le prestazioni e i risultati attesi.
Utilizza i comandi di filtro nelle prime fasi della query per ridurre il volume di dati elaborati.
Limita gli intervalli di tempo delle query (StartTimeOffset) per evitare i timeout con gruppi di log ad alto volume.
Utilizza gli indici di campo per ottimizzare le prestazioni delle query.

Pianificazione della pianificazione

Scegliete una frequenza di pianificazione che consenta il completamento delle query prima dell'esecuzione successiva. Per i gruppi di log ad alto volume, utilizzate intervalli più lunghi (ad esempio, 10 minuti anziché 5).
Tieni conto dei ritardi di inserimento dei log durante l'impostazione. StartTimeOffset Un piccolo intervallo tra l'ora corrente EndTimeOffset e quella corrente consente di evitare la valutazione di dati incompleti.
Distribuisci le pianificazioni di Log Alarm su tutto il tuo account per evitare di raggiungere i limiti di concorrenza di Scheduled Query. Le esecuzioni simultanee di query sul tuo account non possono superare i 100. Tieni conto di questa quota quando crei più allarmi di registro con pianificazioni sovrapposte.

Regolazione della soglia

Inizia con valori QueryResultsToEvaluate (N) più alti per ridurre il rumore di allarme causato dai picchi transitori.
Per eventi sparsi (come gli errori che si verificano raramente), imposta in TreatMissingData modo da notBreaching mantenere l'allarme nello stato OK quando nessun registro corrisponde.
Per i segnali continui (come i registri del traffico), considera l'impostazione TreatMissingData per rilevare quando i dati breaching di registro previsti smettono di arrivare.

Multi-contributor progettazione

Scegliete campi significativi per la clausola BY che rappresentano risorse o dimensioni distinte che desiderate monitorare in modo indipendente.
Tieni presente che vengono restituiti solo i primi 500 contributori per esecuzione della query. Se ti aspetti di più, restringi la ricerca o utilizza meno campi della clausola BY.
Utilizzate il | sort asc suffisso | sort desc o nell'espressione di aggregazione per dare priorità ai valori più alti o più bassi in base all'operatore di confronto quando viene raggiunto il limite di 500 collaboratori.

Risoluzione dei problemi

L'allarme rimane in INSUFFICIENT_DATA

Possibile causa	Risoluzione
Il ruolo di esecuzione pianificata delle query non ha le autorizzazioni	Verifica che il ruolo disponga di`logs:StartQuery`, `logs:StopQuerylogs:GetQueryResults`, e `logs:DescribeLogGroups` le autorizzazioni siano limitate ai gruppi di log corretti.
Il gruppo di log non esiste o è stato eliminato	Verifica che gli ARN del gruppo di log nella configurazione degli allarmi siano corretti e accessibili.
Allarme creato o aggiornato di recente	Dopo la creazione o l'aggiornamento della configurazione, l'allarme rimane in INSUFFICIENT_DATA fino al completamento di un numero sufficiente di esecuzioni di query per soddisfare la finestra di valutazione. M-out-of-N
L'interrogazione pianificata non è in esecuzione	Controlla la Scheduled Query AWS gestita nella console CloudWatch Logs per verificare che venga eseguita nei tempi previsti.
Campo di aggregazione non presente nei risultati della query	Il campo a cui si fa riferimento nell'espressione di aggregazione deve essere presente nei risultati della query. Ad esempio, se l'aggregazione è`avg(latency)`, assicurati che la query produca un campo. `latency` Se il campo non è presente, il risultato viene considerato come dato mancante.
Registra il ritardo di ingestione	Una query pianificata può valutare solo gli eventi di registro che sono stati inseriti al momento dell'esecuzione. `StartTimeOffset`e `EndTimeOffset` definiscono la finestra di interrogazione relativa al tempo di esecuzione T — [T − StartTimeOffset, T − EndTimeOffset] — ma non tengono conto del ritardo di inserimento. Se gli eventi della finestra su cui si esegue la query sono ancora in fase di acquisizione, la query viene eseguita prima che siano disponibili e li salta. Utilizzatela `EndTimeOffset` per spostare la finestra all'indietro abbastanza da completare l'inserimento per l'intero intervallo. Esempio: supponiamo che i log impieghino fino a 2 minuti per diventare interrogabili dopo il verificarsi degli eventi. `StartTimeOffset=60, EndTimeOffset=0`— finestra [T−60s, T]. La finestra termina al momento dell'esecuzione, quindi gli eventi recenti non vengono ancora inseriti e vengono persi. `StartTimeOffset=180, EndTimeOffset=120`— finestra [T−180s, T−120s]. La finestra termina 2 minuti nel passato, a quel punto tutti gli eventi sono acquisiti e valutabili.

L'allarme mostra EVALUATION_ERROR

Ciò indica un problema di configurazione del client. Controlla il StateReason campo per i dettagli. Cause comuni:

Sintassi di interrogazione non valida o non valida.
Autorizzazioni insufficienti per il ruolo pianificato di esecuzione delle query.
Tutte le esecuzioni delle query non sono riuscite (ad esempio, le autorizzazioni dei gruppi di log sono state revocate).

L'allarme mostra EVALUATION_FAILURE

Ciò indica un problema temporaneo CloudWatch del servizio. L'allarme si ripristina automaticamente quando il problema si risolve. Se il problema persiste per più di qualche minuto, controlla la dashboard dello stato del CloudWatch servizio.

L'allarme mostra PARTIAL_DATA

La query ha restituito un massimo di 500 gruppi di collaboratori, ma più gruppi corrispondenti. L'allarme valuta i contributori disponibili, ma i risultati potrebbero essere incompleti. Valuta la possibilità di restringere la query o ridurre il numero di campi della clausola BY.

Le righe di registro non vengono visualizzate nelle notifiche

Verify ActionLogLineCount è impostato su un valore compreso tra 1 e 50.
Verifica che il ruolo log lines abbia un ambito di logs:GetQueryResults autorizzazione limitato ai gruppi di log corretti.
Le righe di registro sono incluse solo nelle notifiche e-mail di Amazon SNS. Gli altri tipi di azioni non includono le righe di registro.
Le query utilizzate unmask() non possono includere righe di registro nelle notifiche (rifiutate al momento della creazione).

Per ulteriori best practice sull'ottimizzazione, il monitoraggio e l'autorizzazione delle query, consulta le best practice per le query pianificate nella Amazon CloudWatch Logs User Guide.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Allarmi ProMQL

Allarmi compositi