Comment fonctionnent les alarmes de journal Cycle de vie des requêtes planifiées gérées Configuration de l'alarme de journal Requête de journaux Expressions d'agrégation Multi-contributor alarmes Traitement de données manquantes États d'évaluation Mise à jour d'alarme 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, les alarmes de journal évaluent directement les données du journal en utilisant le même langage de requête Logs Insights que celui que vous utilisez pour les analyses ad hoc.

Comment fonctionnent les alarmes de journal

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 M-out-of-N évaluant les 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épassent le seuil.

Pour créer une alarme de journal, voirCréation d'une alarme de journal.

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

Lorsque vous créez une alarme de journal, il 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 du 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 les noms des groupes de journaux ou 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 rétrospective 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 requis 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 la liste complète des paramètres et les instructions de création, voirCréation d'une alarme de journal.

Requête de 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 la plage de temps définie par StartTimeOffset etEndTimeOffset.

La requête utilise la syntaxe de requête de 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 du seuil. L'expression utilise la même syntaxe que la stats commande dans 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.

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 à l'ALARMétat.

Les limites suivantes s'appliquent aux alarmes multi-contributeurs :

Maximum de 5 champs dans la by clause.
Maximum de 500 résultats de contributeurs renvoyés par exécution de requête.
Maximum de 100 contributeurs 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 importants sont évalués en premier lorsque le nombre total dépasse 500.

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

Note

Systems Manager Incident Manager et les actions d'investigation ne sont pas pris en charge pour les alarmes de journal.

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 dans la plage de temps de requête.

La requête ne renvoie aucun résultat applicable : des 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 conformément au 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) où error-codes n'existe pas dans les événements du journal renvoyés.

Notez que count(*) sur un résultat vide, le jeu de résultats 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.

Options de traitement des données manquantes
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 ne dépassant 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.

États d'évaluation de Log Alarm
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) échouent. 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 lorsque tous les résultats de la requête ont échoué. L'alarme passe en mode `INSUFFICIENT_DATA` immédiat. Reportez-vous au `StateReason` champ pour plus de détails.
`PARTIAL_DATA`	La requête a renvoyé un maximum de 500 groupes de contributeurs, mais un plus grand nombre de groupes correspondaient. L'alarme évalue les contributeurs disponibles, mais les résultats peuvent être incomplets.

Mise à jour d'alarme

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 en mode 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 de Systems Manager

Pour la matrice complète de prise en charge des actions, voirActions d'alerte.

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

Informations de modification de configuration d'alarme standard (nom de l'alarme, description, détails de configuration).
Informations sur le changement d'état (nouvel état, raison de l'état, horodatage).
Les notifications par e-mail 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 clause) : 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'exemple suivant montre une notification par e-mail Amazon SNS concernant une alarme de journal multicontributeur (avec une BY clause). Chaque contributeur à une violation 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...
}

Inclure les 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 du 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 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. Le nombre de lignes de journal incluses dans une notification est limité par le nombre demandé, le nombre total de résultats disponibles et la limite de 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 au début de votre requête pour réduire le volume de données traitées.
Limitez les plages temporelles des requêtes (StartTimeOffset) pour éviter les délais d'expiration liés aux groupes de journaux à volume élevé.
Utilisez des index de champs pour optimiser les performances des requêtes.

Planification des horaires

Choisissez une fréquence de planification qui permet aux requêtes de se terminer 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 programmes Log Alarm sur l'ensemble de votre compte pour éviter d'atteindre les limites de simultanéité des requêtes planifiées. Le nombre d'exécutions de requêtes simultanées sur votre compte ne peut pas dépasser 100. Tenez compte de ce quota lors de la création de plusieurs alarmes de journal dont les plannings se chevauchent.

Réglage du seuil

Commencez par des valeurs QueryResultsToEvaluate (N) plus élevées pour réduire le bruit d'alarme dû aux pics transitoires.
Pour les événements rares (tels que les erreurs qui se produisent rarement), configurez cette TreatMissingData option notBreaching pour maintenir l'alarme en état OK lorsqu'aucun journal ne correspond.
Pour les signaux continus (tels que les journaux de trafic), pensez TreatMissingData à configurer 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 davantage, 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 INSUSUFFISENT_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 dispose`logs:StartQuery`, `logs:StopQuerylogs:GetQueryResults`, et que `logs:DescribeLogGroups` les autorisations sont étendues aux bons groupes de journaux.
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 INSUSUFFISENT_DATA jusqu'à ce que le nombre d'exécutions de requêtes soit suffisant 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.
Champ d'agrégation absent 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 du journal qui ont été ingérés au moment de son exécution. `StartTimeOffset`et `EndTimeOffset` définissent 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 en cours d'ingestion pour la fenêtre que vous interrogez, la requête s'exécute avant qu'ils ne soient disponibles et les ignore. `EndTimeOffset`À utiliser pour reculer suffisamment la fenêtre pour que l'ingestion soit complète pour l'ensemble de la gamme. Exemple : supposons que les journaux mettent jusqu'à 2 minutes à être interrogeables 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. Les événements récents ne sont donc pas encore ingérés et sont manqué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 planifiée des requêtes.
Toutes les exécutions de requêtes ont échoué (par exemple, les autorisations de groupe 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 CloudWatch de santé du service.

L'alarme indique PARTIAL_DATA

La requête a renvoyé un maximum de 500 groupes de contributeurs, mais un plus grand nombre de groupes correspondaient. L'alarme évalue les contributeurs disponibles, mais les résultats peuvent être incomplets. Envisagez de restreindre votre requête ou de réduire le nombre de champs de clause BY.

Les lignes de journal n'apparaissent pas dans les notifications

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

Pour connaître les meilleures pratiques supplémentaires en matière d'optimisation, de surveillance et d'autorisation des requêtes, consultez les bonnes 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