Comment fonctionnent les Log Alarms Cycle de vie géré des requêtes planifiées Configuration de l'alarme de journal Requête relative aux journaux Expressions d'agrégation Multi-contributor alarmes Traitement de données manquantes États d'évaluation Mise à jour des alarmes Actions et notifications Bonnes pratiques et dépannage

Enregistrer les alarmes

Une alarme de journal surveille les résultats d'une requête CloudWatch Logs Insights exécutée selon un calendrier à l'aide d'une requête planifiée. L'alarme applique une expression d'agrégation aux résultats de la requête pour produire une valeur numérique, et lorsque cette valeur agrégée dépasse un seuil configuré, l'alarme passe à l'ALARMétat et exécute les actions configurées.

Contrairement aux alarmes métriques qui nécessitent des filtres métriques comme étape intermédiaire, Log Alarms évalue directement les données du journal en utilisant le même langage de requête Logs Insights que vous utilisez pour les analyses ad hoc.

Comment fonctionnent les Log Alarms

Les étapes suivantes décrivent le fonctionnement d'une alarme de journal :

Vous créez une alarme de journal avec une requête, une expression d'agrégation, un calendrier et un seuil.
CloudWatch crée automatiquement une requête planifiée AWS gérée qui exécute votre requête selon le calendrier spécifié.
Chaque exécution de requête produit des résultats agrégés (une valeur unique ou plusieurs valeurs contributrices).
CloudWatch évalue les résultats agrégés par rapport à votre seuil en utilisant l' M-out-of-Névaluation des récentes exécutions de requêtes.
Si le seuil est dépassé, l'alarme passe à l'ALARMétat et exécute les actions que vous avez configurées (telles que les notifications Amazon SNS).

Note

Les alarmes de journal évaluent les N dernières exécutions de requêtes. L'alarme passe au ALARM moment où M de ces N exécutions dépasse le seuil.

Pour créer une alarme de journal, consultezCréer une alarme de journal.

Cycle de vie géré des requêtes planifiées

Lorsque vous créez une alarme de journal, crée CloudWatch automatiquement une requête planifiée AWS gérée qui exécute votre requête selon le calendrier spécifié. Il n'est pas nécessaire de créer la requête planifiée séparément.

La requête planifiée AWS gérée présente les caractéristiques suivantes :

Il est visible dans la console CloudWatch Logs sous Requêtes planifiées.
Vous ne pouvez pas le modifier directement. Pour modifier la requête ou sa configuration, mettez à jour l'alarme de journal.
CloudWatch supprime la requête planifiée AWS gérée lorsque vous supprimez l'alarme.

Configuration de l'alarme de journal

Une alarme de journal est configurée avec les paramètres suivants :

QueryStringest la requête CloudWatch Logs Insights à exécuter.
LogGroupIdentifierssont les groupes de journaux à interroger. Spécifiez soit les noms des groupes de journaux, soit les ARN des groupes de journaux.
ScheduledQueryRoleARNest l'ARN du rôle IAM qui permet à CloudWatch Logs d'exécuter la requête planifiée en votre nom.
AggregationExpressiondéfinit la manière dont les résultats des requêtes sont agrégés en une valeur numérique pour l'évaluation des seuils.
ScheduleExpressiondéfinit la fréquence d'exécution de la requête (par exemple,rate(5 minutes)).
StartTimeOffsetdéfinit la fenêtre de retour en secondes pour chaque exécution de requête.
EndTimeOffsetdéfinit la fin de la plage de temps de requête comme un décalage en secondes par rapport à l'heure actuelle.
ComparisonOperatorest la façon dont les résultats agrégés sont comparés au seuil. Valeurs valides: GreaterThanThreshold, GreaterThanOrEqualToThreshold, LessThanThreshold, LessThanOrEqualToThreshold.
Le seuil est la valeur numérique à comparer.
QueryResultsToEvaluateest le nombre d'exécutions de requêtes récentes à évaluer (N in M-out-of-N).
QueryResultsToAlarmest le nombre de résultats de violation nécessaires pour déclencher ALARM (M in M-out-of-N).
TreatMissingDatadéfinit la manière dont les résultats de requête manquants sont traités lors de l'évaluation.

Pour obtenir la liste complète des paramètres et les instructions de création, consultezCréer une alarme de journal.

Requête relative aux journaux

La requête Log Alarm est une requête CloudWatch Logs Insights qui sélectionne et filtre les données du journal à évaluer. La requête s'exécute sur les groupes de journaux spécifiés dans LogGroupIdentifiers pendant la période définie par StartTimeOffset etEndTimeOffset.

La requête utilise la syntaxe de requête CloudWatch Logs Insights. Pour obtenir des instructions sur la rédaction de requêtes efficaces pour Log Alarms, consultezBonnes pratiques et dépannage.

Expressions d'agrégation

L'expression d'agrégation définit la manière dont les résultats de CloudWatch la requête sont résumés en une valeur numérique pour l'évaluation des seuils. L'expression utilise la même syntaxe que la stats commande de CloudWatch Logs Insights.

La syntaxe d'une expression d'agrégation est la suivante :


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

Vous ne pouvez spécifier qu'une seule expression d'agrégation. Le tableau suivant répertorie les fonctions d'agrégation prises en charge.

Fonction	Description	Exemple
`count(*)`	Nombre de toutes les lignes de journal correspondantes.	`count(*)`
`avg(field)`	Valeur moyenne du champ spécifié.	`avg(duration)`
`sum(field)`	Somme du champ spécifié.	`sum(bytesSent)`
`min(field)`	Valeur minimale du champ spécifié.	`min(latency)`
`max(field)`	Valeur maximale du champ spécifié.	`max(latency)`

La bin() fonction n'est pas prise en charge dans la by clause d'expression d'agrégation. Cependant, vous pouvez l'utiliser bin() dans la chaîne de requête elle-même.

Multi-contributor alarmes

Lorsque vous incluez une by clause dans votre expression d'agrégation, l'alarme évalue chaque combinaison unique de valeurs de champ (appelée contributeur) indépendamment. L'alarme passe à ALARM l'état si un contributeur dépasse le seuil.

Par exemple, l'expression suivante regroupe le nombre d'erreurs par nom de service :


count(*) by serviceName

Chaque valeur unique de serviceName est évaluée indépendamment par rapport au seuil. Si un service dépasse le seuil de M exécutions de requêtes sur N, l'alarme passe en ALARM état.

Les limites suivantes s'appliquent aux alarmes multicontributeurs :

Maximum de 5 champs dans la by clause.
Maximum de 500 résultats de contribution renvoyés par exécution de requête.
Un maximum de 100 contributeurs ont été suivis simultanément dans ALARM l'État.

Par défaut, les contributeurs sont triés par ordre alphabétique et seuls les 500 premiers sont renvoyés par exécution de requête. Pour trier les contributeurs en fonction de leur valeur agrégée, spécifiez | sort asc ou | sort desc dans votre expression d'agrégation (par exemple,avg(latency) by serviceName | sort desc). Value-based le tri garantit que les contributeurs les plus significatifs sont évalués en premier lorsque le nombre total dépasse 500.

Pour les alarmes impliquant plusieurs contributeurs, les actions Amazon SNS et Lambda sont exécutées au niveau du contributeur (une fois par contributeur défaillant). Les OpsItem actions de Systems Manager sont exécutées au niveau de l'alarme.

Note

Systems Manager Incident Manager et les actions d'investigation ne sont pas prises en charge pour Log Alarms.

Si un contributeur disparaît des résultats de requête (par exemple, si une ressource éphémère est supprimée), ce contributeur passe à OK l'état quel que soit le paramètre de traitement des données manquant.

Traitement de données manquantes

Des données manquantes se produisent lorsqu'une exécution de requête planifiée ne produit pas de valeur pouvant être évaluée par rapport au seuil. Une telle situation se produit dans les cas suivants :

Aucun journal présent : le groupe de journaux ne contient aucun événement de journal pendant la période de requête.

La requête ne renvoie aucun résultat applicable : les journaux sont présents mais l'expression d'agrégation ne peut pas produire de valeur. Cela se produit lorsque :

Les résultats de requête correspondants n'étaient pas présents selon le filtre de requête.
Le champ référencé dans l'expression d'agrégation n'était pas présent dans les résultats de la requête. Par exemple, count(error-codes) where error-codes n'existe pas dans les événements de journal renvoyés.

Notez que count(*) sur un jeu de résultats vide, renvoie 0, qui est un point de données valide et n'est pas considéré comme manquant.

Vous pouvez configurer la façon dont l'alarme traite les données manquantes à l'aide du TreatMissingData paramètre. Le tableau suivant décrit les options disponibles.

Value	Comportement
`missing`	Traitez le point de données comme manquant. Il s’agit de l’option par défaut.
`notBreaching`	Traitez le point de données manquant comme s'il ne dépassait pas le seuil.
`breaching`	Traitez le point de données manquant comme dépassant le seuil.
`ignore`	Ignorez le point de données manquant et évaluez uniquement les données disponibles.

États d'évaluation

Outre les INSUFFICIENT_DATA états standard et OKALARM, Log Alarms peut signaler les états d'évaluation suivants EvaluationState sur le terrain. Ces états fournissent un contexte supplémentaire expliquant pourquoi l'alarme est dans son état actuel.

State	Description
`EVALUATION_FAILURE`	Un problème de CloudWatch service temporaire a empêché l'évaluation. Cela peut se produire lorsque le service rencontre des problèmes lors de l'évaluation des résultats des requêtes en raison d'erreurs de service, ou lorsque certains résultats de requête (mais pas tous) ont échoué. L'alarme passe à`INSUFFICIENT_DATA`. Nous recommandons une surveillance manuelle jusqu'à ce que le problème soit résolu.
`EVALUATION_ERROR`	Une erreur de configuration du client a empêché l'évaluation. Cela peut se produire en raison d'autorisations insuffisantes, d'une requête non valide ou d'un échec de tous les résultats de la requête. L'alarme passe à l'état `INSUFFICIENT_DATA` immédiat. Reportez-vous au `StateReason` champ pour plus de détails.
`PARTIAL_DATA`	La requête a renvoyé le maximum de 500 groupes de contributeurs, mais davantage de groupes correspondaient. L'alarme évalue les contributeurs disponibles, mais les résultats peuvent être incomplets.

Mise à jour des alarmes

Lorsque vous mettez à jour la requête, l'expression d'agrégation, le calendrier ou les groupes de journaux d'une alarme de journal, l'alarme passe à l'alarme INSUFFICIENT_DATA jusqu'à ce que suffisamment de nouveaux points de données soient collectés. Les modifications apportées au seuil ou aux M-out-of-N valeurs ne déclenchent pas cette réinitialisation.

Actions et notifications

Les alarmes de journal prennent en charge les actions suivantes :

Notifications Amazon SNS
Invocations de fonctions Lambda
OpsItem Création d'un gestionnaire de systèmes

Pour la matrice complète de support aux actions, voirActions d'alerte.

Lorsqu'une alarme de journal passe à l'état, la notification d'action inclut les informations suivantes :

Informations de modification de la configuration d'alarme standard (nom de l'alarme, description, détails de configuration).
Informations sur les changements d'état (nouvel état, motif de l'état, horodatage).
Les notifications par e-mail d'Amazon SNS incluent également un lien profond vers la console CloudWatch Logs Insights affichant les résultats complets des requêtes.

L'exemple suivant montre une notification par e-mail Amazon SNS pour une alarme de journal à valeur unique (sans BY clause) :


{
    "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'exemple suivant montre une notification par e-mail Amazon SNS pour une alarme de journal multi-contributeurs (avec une BY clause). Chaque contributeur fautif génère une notification distincte :


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

Inclusion de lignes de journal dans les notifications

Vous pouvez éventuellement inclure des lignes de journal des résultats de requête bruts dans les notifications d'alarme en réglant le ActionLogLineCount paramètre sur une valeur comprise entre 1 et 50. Il s'agit des événements de journal sous-jacents sur lesquels l'expression d'agrégation est évaluée, et non des valeurs agrégées. La valeur par défaut est 0, ce qui signifie qu'aucune ligne de journal n'est incluse.

Note

Les lignes de journal sont incluses uniquement dans les notifications par e-mail d'Amazon SNS. Les actions Lambda n'incluent pas de lignes de journal dans leurs charges utiles.

Important

L'inclusion de lignes de journal dans les notifications peut exposer les données sensibles de vos journaux dans les messages Amazon SNS. Vérifiez le contenu de votre journal avant d'activer cette fonctionnalité.

Pour inclure des lignes de journal, le rôle de lignes de journal doit disposer de l'logs:GetQueryResultsautorisation requise. Le nombre de lignes de journal incluses dans une notification est limité par le nombre demandé, le total des résultats disponibles et la limite de taille de la charge utile Amazon SNS.

Bonnes pratiques et dépannage

Bonnes pratiques

Optimisation des requêtes

Testez les requêtes manuellement dans CloudWatch Logs Insights avant de les utiliser dans une alarme de journal afin de vérifier les performances et les résultats attendus.
Utilisez les commandes de filtrage dès le début de votre requête afin de réduire le volume de données traitées.
Limitez les plages temporelles des requêtes (StartTimeOffset) pour éviter les délais d'attente avec les groupes de journaux à volume élevé.
Utilisez les index de champs pour optimiser les performances des requêtes.

Planification des horaires

Choisissez une fréquence planifiée qui permet de terminer les requêtes avant la prochaine exécution. Pour les groupes de journaux à volume élevé, utilisez des intervalles plus longs (par exemple, 10 minutes au lieu de 5).
Tenez compte des délais d'ingestion des journaux lors du réglage StartTimeOffset. Un petit écart entre l'heure actuelle EndTimeOffset et l'heure actuelle permet d'éviter d'évaluer des données incomplètes.
Répartissez les planifications Log Alarm sur l'ensemble de votre compte pour éviter d'atteindre les limites de simultanéité des requêtes planifiées. Les exécutions simultanées de requêtes sur votre compte ne peuvent pas dépasser 100. Tenez compte de ce quota lors de la création de plusieurs alarmes de journal dont les horaires se chevauchent.

Réglage des seuils

Commencez par des valeurs plus élevées QueryResultsToEvaluate (N) pour réduire le bruit d'alarme dû aux pics transitoires.
Pour les événements rares (tels que les erreurs qui se produisent rarement), définissez sur TreatMissingData notBreaching pour que l'alarme reste en état OK lorsqu'aucun journal ne correspond.
Pour les signaux continus (tels que les journaux de trafic), pensez à les configurer TreatMissingData breaching pour détecter le moment où les données de journal attendues cessent d'arriver.

Multi-contributor design

Choisissez des champs significatifs pour la clause BY qui représentent des ressources ou des dimensions distinctes que vous souhaitez surveiller indépendamment.
Sachez que seuls les 500 premiers contributeurs sont renvoyés par exécution de requête. Si vous en attendez plus, affinez votre requête ou utilisez moins de champs de clause BY.
Utilisez le | sort asc suffixe | sort desc ou dans votre expression d'agrégation pour hiérarchiser les valeurs les plus élevées ou les plus faibles en fonction de votre opérateur de comparaison lorsque la limite de 500 contributeurs est atteinte.

Résolution des problèmes

L'alarme reste dans INSUFFISANT_DATA

Cause possible	Résolution
Le rôle d'exécution de requêtes planifiée ne dispose pas d'autorisations	Vérifiez que le rôle possède `logs:StartQuery` `logs:StopQuerylogs:GetQueryResults`, et que `logs:DescribeLogGroups` les autorisations sont limitées aux groupes de journaux appropriés.
Le groupe de journaux n'existe pas ou a été supprimé	Vérifiez que les ARN du groupe de journaux dans la configuration de l'alarme sont corrects et accessibles.
Alarme récemment créée ou mise à jour	Après la création ou la mise à jour de la configuration, l'alarme reste dans INSUFFISANT_DATA jusqu'à ce que suffisamment de requêtes soient exécutées pour satisfaire la fenêtre d'évaluation. M-out-of-N
La requête planifiée n'est pas en cours d'exécution	Vérifiez la requête planifiée AWS gérée dans la console CloudWatch Logs pour vérifier qu'elle s'exécute dans les délais.
Le champ d'agrégation n'est pas présent dans les résultats de la requête	Le champ référencé dans l'expression d'agrégation doit être présent dans les résultats de la requête. Par exemple, si votre agrégation l'est`avg(latency)`, assurez-vous que la requête produit un `latency` champ. Si le champ n'est pas présent, le résultat est considéré comme une donnée manquante.
Retard d'ingestion du journal	Une requête planifiée ne peut évaluer que les événements de journal qui ont été ingérés au moment de son exécution. `StartTimeOffset`et `EndTimeOffset` définissez la fenêtre de requête par rapport au temps d'exécution T — [T − StartTimeOffset, T − EndTimeOffset] — mais ils ne tiennent pas compte du délai d'ingestion. Si des événements sont toujours ingérés pour la fenêtre que vous interrogez, la requête s'exécute avant qu'ils ne soient disponibles et les ignore. `EndTimeOffset`Utilisez-le pour reculer suffisamment la fenêtre pour que l'ingestion soit complète pour toute la gamme. Exemple : supposons que les journaux mettent jusqu'à 2 minutes à devenir consultables une fois que les événements se sont produits. `StartTimeOffset=60, EndTimeOffset=0`— fenêtre [T−60s, T]. La fenêtre se termine au moment de l'exécution, de sorte que les événements récents ne sont pas encore ingérés et sont ignorés. `StartTimeOffset=180, EndTimeOffset=120`— fenêtre [T−180s, T−120s]. La fenêtre se termine il y a 2 minutes, date à laquelle tous les événements sont ingérés et évaluables.

L'alarme indique EVALUATION_ERROR

Cela indique un problème de configuration du client. Consultez le StateReason champ pour plus de détails. Causes courantes :

Syntaxe de requête non valide ou mal formée.
Autorisations insuffisantes sur le rôle d'exécution des requêtes planifiées.
Toutes les exécutions de requêtes ont échoué (par exemple, les autorisations des groupes de journaux ont été révoquées).

L'alarme indique EVALUATION_FAILURE

Cela indique un problème de CloudWatch service temporaire. L'alarme se rétablit automatiquement lorsque le problème est résolu. S'il persiste au-delà de quelques minutes, consultez le tableau de bord de l'état du CloudWatch service.

L'alarme affiche PARTIAL_DATA

La requête a renvoyé le maximum de 500 groupes de contributeurs, mais davantage de groupes correspondaient. L'alarme évalue les contributeurs disponibles, mais les résultats peuvent être incomplets. Pensez à affiner votre requête ou à réduire le nombre de champs de clause BY.

Les lignes de journal n'apparaissent pas dans les notifications

Verify ActionLogLineCount est réglé sur une valeur comprise entre 1 et 50.
Vérifiez que le rôle des lignes de journal dispose logs:GetQueryResults d'autorisations limitées aux groupes de journaux appropriés.
Les lignes de journal sont incluses uniquement dans les notifications par e-mail d'Amazon SNS. Les autres types d'actions n'incluent pas les lignes de journal.
Les requêtes utilisant unmask() ne peuvent pas inclure de lignes de journal dans les notifications (rejetées au moment de la création).

Pour d'autres bonnes pratiques en matière d'optimisation, de surveillance et d'autorisation des requêtes, consultez les meilleures pratiques relatives aux requêtes planifiées dans le guide de l'utilisateur Amazon CloudWatch Logs.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Alarmes ProMQL

Alarmes composites