Configurer les alertes et les notifications

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Les conditions d'alerte définissent un code d'état spécifique (par exemple, erreur 404/502/2xx/4xx/5xx), la latence et les seuils de code d'erreur qui, lorsqu'une limite est dépassée, déclenchent des alertes visuelles dans l'interface utilisateur et envoient des notifications via plusieurs canaux, tels que les e-mails, Slack, PagerDuty ou les webhooks. Vous pouvez configurer des alertes au niveau de l'environnement, du proxy API, du service cible ou de la région. Lorsqu'une alerte est déclenchée, vous recevez une notification via la méthode que vous avez définie lors de l'ajout d'alertes et de notifications.

Par exemple, vous pouvez déclencher une alerte et envoyer une notification à l'équipe en charge des opérations lorsque le taux d'erreurs 5xx dépasse 23 % sur une période de 5 minutes sur le proxy API "orders-prod" déployé dans votre environnement de production.

La figure suivante montre comment les alertes s'affichent dans l'interface utilisateur :

Vous trouverez ci-dessous un exemple de notification par e-mail que vous pouvez recevoir lorsqu'une alerte est déclenchée.

Pour en savoir plus, cliquez sur les liens suivants dans le corps de la notification d'alerte :

• Afficher les informations détaillées pour afficher plus d'informations, y compris les paramètres d'alerte et l'activité de chaque condition au cours de la dernière heure.
• "Définition de l'alerte" pour afficher la définition de l'alerte.
• Historique des alertes pour afficher plus d'informations sur l'alerte en question.
• Afficher le livre de lecture pour afficher les actions recommandées, le cas échéant.
• Afficher le rapport d'analyse de l'API pour afficher un rapport personnalisé sur la condition d'alerte.

Les sections suivantes décrivent comment configurer et gérer les alertes et les notifications.

À propos des types d'alertes

La version initiale d'API Monitoring vous permet de créer des règles basées sur des modèles qui spécifient quand déclencher une alerte en fonction d'un ensemble de conditions prédéfinies. Les alertes de ce type sont appelées alertes fixes et sont les seules compatibles avec la version initiale d'API Monitoring.

Par exemple, vous pouvez générer une alerte fixe lorsque :

• Le [taux d'erreurs 5xx] [est supérieur à] [10 %] depuis [10 minutes] en provenance de [target mytarget1]
• Le [nombre d'erreurs 2xx] [est inférieur à] [50] depuis [5 minutes] dans la [région us-east-1]
• La [latence p90] [est supérieure à] [750 ms] depuis [10 minutes] sur [proxy myproxy1]

La version bêta 19.11.13 des rapports de sécurité comporte de nouveaux types d'alertes :

• Alertes relatives au trafic total (version bêta). Type d'alerte permettant de déclencher une alerte lors d'une modification du trafic, en fonction d'un pourcentage spécifié sur une période donnée.
• Alertes d'anomalie (bêta). Type d'alerte dans lequel Edge détecte les problèmes de trafic et de performances au lieu d'avoir à les prédéterminer vous-même. Vous pouvez ensuite déclencher une alerte pour ces anomalies.
• Alertes relatives au délai d'expiration TLS (version bêta). Type d'alerte vous permettant de générer une notification lorsqu'un certificat TLS arrive à expiration.

L'API Monitoring prenant désormais en charge plusieurs types d'alertes, la boîte de dialogue "Créer une alerte" affiche désormais une option de sélection du type d'alerte :

Afficher les paramètres d'alerte

Pour afficher les paramètres d'alerte actuellement définis, cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge.

La page "Alerte" s'affiche, comme illustré sur la figure suivante :

Comme le montre la figure, la page "Alerte" vous permet de :

• afficher un récapitulatif des paramètres d'alerte actuellement définis ;
• afficher l'historique des alertes déclenchées ;
• ajouter des alertes et des notifications ;
• créer un rapport personnalisé à partir d'une alerte ;
• activer ou désactiver une alerte ;
• modifier une alerte ;
• supprimer une alerte ;
• rechercher une chaîne particulière dans la liste des alertes.

Afficher l'historique des alertes déclenchées pour votre organisation

Pour afficher l'historique des alertes déclenchées pour votre organisation au cours des dernières 24 heures, cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge, puis cliquez sur l'onglet Historique.

La page "Historique des alertes" s'affiche.

Cliquez sur le nom de l'alerte pour afficher les détails de celle-ci dans le tableau de bord d'enquête. Vous pouvez filtrer la liste en recherchant tout ou partie du nom de l'alerte.

Ajouter des alertes et des notifications

Pour ajouter des alertes et des notifications, procédez comme suit :

1. Cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge.
2. Cliquez sur +Alerte.
3. Saisissez les informations générales suivantes concernant l'alerte :

   Champ	Description
   Nom de l'alerte	Nom de l'alerte. Utilisez un nom qui décrit le déclencheur et qui aura un sens pour vous. Le nom ne doit pas dépasser 128 caractères.
   Type d'alerte	Sélectionnez Fixe. Pour en savoir plus sur les types d'alertes, consultez la section À propos des types d'alertes.
   Description	Description de l'alerte.
   Environment	Sélectionnez l'environnement dans la liste déroulante.
   État	Bouton permettant d'activer ou de désactiver l'alerte.

4. Définissez la métrique, le seuil et la dimension de la première condition qui déclenchera l'alerte.

   Champ de condition	Description
   Métrique	Sélectionnez l'une des métriques suivantes : Code d'état : sélectionnez un code d'état dans la liste, par exemple 401, 404, 2xx, 4xx ou 5xx HTTP. Remarque : L'API vous permet de définir un plus large éventail de codes d'état. Utilisez l'API pour spécifier un code d'état compris entre 200 et 299, 400 à 599 et les caractères génériques 2xx, 4xx ou 5xx. Voir Créer une alerte. Pour les alertes de limitation de débit (code d'état HTTP 429), définissez la métrique sur un code d'erreur d'arrêt des pics. Vous pouvez utiliser la règle Assign Message pour réécrire le code de réponse HTTP, à partir d'une erreur de proxy ou d'une erreur de cible. API Monitoring ignore tous les codes réécrits et enregistre les codes de réponse HTTP réels. Latence : sélectionnez une valeur de latence dans la liste déroulante. Plus précisément : p50 (50e centile), p90 (90e centile), p95 (95e centile) ou p99 (99e centile). Par exemple, sélectionnez p95 pour configurer une alerte déclenchée lorsque la latence de réponse du 95e centile est supérieure au seuil défini ci-dessous. Code d'erreur : sélectionnez une catégorie, une sous-catégorie et un code d'erreur dans la liste. Vous pouvez également sélectionner l'une des options suivantes dans une catégorie ou une sous-catégorie : Tous - Le total combiné de tous les codes d'erreur de cette catégorie/sous-catégorie doit répondre aux critères de métrique. N'importe lequel - Un seul code d'erreur de cette catégorie/sous-catégorie doit répondre aux critères de métrique. Consultez la documentation de référence sur les codes d'erreur pour en savoir plus. Trafic total (version bêta) : sélectionnez une augmentation ou une diminution du trafic. Consultez la section Alertes relatives au trafic (version bêta) pour en savoir plus.
   Seuil	Configurez le seuil pour la métrique sélectionnée : Code d'état : définissez le seuil en tant que pourcentage, nombre ou transactions par seconde (TPS) au fil du temps. Latence : sélectionnez le seuil en tant que durée de latence totale ou cible (en ms) sur une période donnée. Dans ce cas, une alerte est déclenchée si la latence observée en centile spécifiée, qui est mise à jour à chaque minute en cas de trafic, dépasse la condition de seuil pour la période couvrant la durée spécifiée. Autrement dit, la condition de seuil n'est pas agrégée sur la durée totale. Code d'erreur : définissez le seuil en pourcentage, nombre ou transactions par seconde (TPS) au fil du temps.
   Variable	Cliquez sur + Ajouter une dimension et spécifiez les informations relatives à cette dimension qui doivent renvoyer des résultats, comme le proxy API, le service cible, l'application du développeur ou la région. Si vous définissez une variable spécifique sur : Toutes - Toutes les entités de la dimension doivent répondre aux critères de métrique. Vous ne pouvez pas sélectionner Toutes pour une métrique de type Latence. N'importe laquelle - Applicable à la région uniquement. Une entité de la dimension doit répondre aux critères de métrique, quelle que soit la région. Remarque : Pour les proxies API ou les services cibles, sélectionnez une collection pour prendre en la fonctionnalité "N'importe laquelle". Collections : sélectionnez une collection dans la liste pour spécifier l'ensemble de serveurs proxy d'API ou de services cibles. Dans ce cas, toute entité de la collection doit répondre aux critères. Si vous définissez la dimension sur Cible, vous pouvez sélectionner un service cible ou le service spécifié via une règle Service Callout. La cible d'une règle Service Callout s'affiche sous la forme d'une valeur précédée de "sc://". Par exemple, "sc://my.endpoint.net".

5. Cliquez sur Afficher les données sur la condition pour afficher les données récentes sur la condition au cours de la dernière heure.
   Le taux d'erreur dans le graphique s'affiche en rouge lorsqu'il dépasse le seuil de condition d'alerte.
   

   Cliquez sur Masquer les données de condition pour masquer les données.

6. Cliquez sur + Ajouter une condition pour ajouter des conditions supplémentaires et répétez les étapes 4 et 5.

   Remarque : Si vous spécifiez plusieurs conditions, l'alerte est déclenchée lorsque toutes les conditions sont remplies.

7. Cliquez sur Créer un rapport d'analyse d'API basé sur des critères d'alerte si vous souhaitez créer un rapport personnalisé basé sur les critères d'alerte que vous avez configurés. Cette option est grisée si vous n'êtes pas administrateur d'organisation.

   Pour savoir plus, consultez la page Créer un rapport personnalisé à partir d'une alerte.

   Remarque : Vous pouvez modifier le rapport personnalisé après avoir enregistré l'alerte, comme décrit dans la section Gestion des rapports personnalisés.

8. Cliquez sur + Notification pour ajouter une notification d'alerte.

   Détails de la notification	Description
   Canal	Sélectionnez le canal de notification que vous souhaitez utiliser et spécifiez la destination : e-mail, Slack, PagerDuty ou webhook.
   Destination	Spécifiez la destination en fonction du type de canal sélectionné : E-mail - Adresse e-mail, telle que joe@company.com Slack - URL du canal Slack, telle que https://hooks.slack.com/services/T00000000/B00000000/XXXXX PagerDuty - Code PagerDuty, tel que abcd1234efgh56789 Webhook - URL du webhook, telle que https://apigee.com/test-webhook Consultez la page Format des objets webhook pour obtenir une description de l'objet transmis à l'URL. Transmettez toutes les informations d'identification via l'URL du webhook. Exemple : https://apigee.com/test-webhook?auth_token=1234_abcd. Vous pouvez spécifier l'URL d'un point de terminaison capable d'analyser l'objet webhook afin de le modifier ou de le traiter. Par exemple, vous pouvez spécifier l'URL d'une API, telle qu'une API Edge, ou de tout autre point de terminaison pouvant traiter l'objet. Remarque : Vous ne pouvez spécifier qu'une seule destination par notification. Pour spécifier plusieurs destinations pour un même type de chaîne, ajoutez des notifications supplémentaires.

9. Pour ajouter des notifications supplémentaires, répétez l'étape 8.
10. Si vous avez ajouté une notification, définissez les champs suivants :

    Champ	Description
    Playbook	(Facultatif) Champ de texte libre destiné à fournir une brève description des actions recommandées pour résoudre les alertes lorsqu'elles se déclenchent. Vous pouvez également indiquer un lien vers votre wiki ou la page de votre communauté sur laquelle vous référencez les bonnes pratiques. Les informations contenues dans ce champ seront incluses dans la notification. Le contenu de ce champ ne peut pas dépasser 1 500 caractères.
    Limite	Fréquence d'envoi des notifications. Sélectionnez une valeur dans la liste déroulante. Les valeurs valides incluent: 15 minutes, 30 minutes et 1 heure.

11. Cliquez sur Enregistrer.

Format d'objet webhook

{
  "alertInstanceId": "event-id",
  "alertName": "name",
  "org": "org-name",
  "description": "alert-description",
  "alertId": "alert-id",
  "alertTime": "alert-timestamp",
  "thresholdViolations":{"Count0": "Duration=threshold-duration Region=region Status Code=2xx Proxy=proxy Violation=violation-description"
  },
  "thresholdViolationsFormatted": [
    {
      "metric": "count",
      "duration": "threshold-duration",
      "proxy": "proxy",
      "region": "region",
      "statusCode": "2xx",
      "violation": "violation-description"
    }
  ],
  "playbook": "playbook-link"
}

Les propriétés thresholdViolations et thresholdViolationsFormatted contiennent des informations détaillées sur l'alerte. La propriété thresholdViolations contient une seule chaîne d'informations détaillées, tandis que thresholdViolationsFormatted contient un objet décrivant l'alerte. En règle générale, utilisez la propriété thresholdViolationsFormatted qui est plus simple à décoder.

L'exemple ci-dessus affiche le contenu de ces propriétés dans le cas d'une alerte fixe lorsque vous configurez la métrique d'alerte pour qu'elle se déclenche en fonction du code d'état HTTP 2xx, comme l'indique la propriété statusCode.

Le contenu de ces propriétés dépend du type d'alerte (fixe ou anormale, par exemple) et de la configuration spécifique de l'alerte. Par exemple, si vous créez une alerte fixe basée sur un code d'erreur, la propriété thresholdViolationsFormatted contient une propriété faultCode au lieu d'une propriété statusCode.

Le tableau suivant répertorie toutes les propriétés possibles de la propriété thresholdViolationsFormatted pour différents types d'alerte :

metric, proxy, target, developerApp,
region, statusCode, faultCodeCategory, faultCodeSubCategory,
faultCode, percentile, comparisonType, thresholdValue,
triggerValue, duration, violation

metric, proxy, target, developerApp,
region, comparisonType, thresholdValue, triggerValue,
duration, violation

metric, proxy, target, region,
statusCode, faultCode, percentile, sensitivity,
violation

envName, certificateName, thresholdValue, violation

Créer un rapport personnalisé à partir d'une alerte

Pour créer un rapport personnalisé à partir d'une alerte :

1. Lors de la création d'une alerte, cliquez sur Créez un rapport d'analyse d'API basé sur des conditions d'alerte., comme décrit dans la section Ajouter des alertes et des notifications groupée).

   Une fois l'alerte enregistrée, l'interface utilisateur affiche le message suivant :

   Alert alertName saved successfully. To customize the report generated, click here.

   Cliquez sur le message pour ouvrir dans un nouvel onglet le rapport dont les champs pertinents sont pré-remplis. Par défaut, le rapport personnalisé se nomme : API Monitoring Generated alertName

2. Modifiez le rapport personnalisé si vous le souhaitez, puis cliquez sur Enregistrer.
3. Cliquez sur le nom du rapport dans la liste, puis générez le rapport personnalisé.

Pour gérer le rapport personnalisé créé en fonction des conditions d'alerte :

1. Cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge.
2. Cliquez sur l'onglet Paramètres.
3. Dans la colonne "Rapports", cliquez sur le rapport personnalisé associé à l'alerte que vous souhaitez gérer.

   La page du rapport personnalisé s'affiche dans un nouvel onglet. Si la colonne "Rapports" est vide, aucun rapport personnalisé n'a encore été créé. Vous pouvez modifier l'alerte pour ajouter un rapport personnalisé, si vous le souhaitez.

4. Modifiez le rapport personnalisé si vous le souhaitez, puis cliquez sur Enregistrer.
5. Cliquez sur le nom du rapport dans la liste, puis générez le rapport personnalisé.

Activer ou désactiver une alerte

Pour activer ou désactiver une alerte :

1. Cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge.
2. Cliquez sur le bouton d'activation de la colonne Statut associé à l'alerte que vous souhaitez activer ou désactiver.
   

Modifier une alerte

Pour modifier une alerte, procédez comme suit :

1. Cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge.
2. Cliquez sur le nom de l'alerte que vous souhaitez modifier.
3. Modifiez l'alerte si nécessaire.
4. Cliquez sur Enregistrer.

Supprimer une alerte

Pour supprimer une alerte, procédez comme suit :

1. Cliquez sur Analyser > Règles d'alerte dans l'interface utilisateur Edge.
2. Placez le curseur sur l'alerte que vous souhaitez supprimer et cliquez sur dans le menu "Actions".

Alertes suggérées

Apigee vous recommande de configurer les alertes suivantes pour être averti des problèmes courants. Certaines de ces alertes sont spécifiques à l'implémentation de vos API et ne sont utiles que dans certaines situations. Par exemple, plusieurs alertes affichées ci-dessous ne s'appliquent que si vous utilisez la règle ServiceCallout ou la règle JavaCallout.

Configurer une alerte de code d'état 5xx pour un proxy d'API

L'exemple suivant montre comment configurer, à l'aide de l'interface utilisateur, une alerte déclenchée lorsque le nombre de transactions par seconde (codes de statut 5xx) pour le proxy d'API des hotels de n'importe quelle région dépasse 100 pendant 10 minutes. Pour en savoir plus, consultez la page Ajouter des alertes et des notifications.

Pour en savoir plus sur l'utilisation de l'API, consultez Configurer une alerte de code d'état 5xx pour un proxy à l'aide de l'API.

Configurer une alerte de latence P95 pour un proxy d'API

Vous trouverez ci-dessous un exemple de configuration, à l'aide de l'interface utilisateur, d'une alerte déclenchée lorsque le temps de latence total des réponses pour le 95e centile est supérieur à 100 ms pendant 5 minutes sur le proxy d'API des hôtels de n'importe quelle région. Pour en savoir plus, consultez la page Ajouter des alertes et des notifications.

Pour en savoir plus sur l'utilisation de l'API, consultez la page Configuration d'une alerte de latence P95 pour un proxy d'API à l'aide de l'API.

Configurer une alerte 404 (application introuvable) pour tous les proxys d'API

Vous trouverez ci-dessous un exemple de configuration, à l'aide de l'interface utilisateur, d'une alerte déclenchée lorsque le pourcentage de codes d'état 404 pour tous les proxys d'API dépasse 5 % pendant 5 minutes, quelle que soit la région. Pour en savoir plus, consultez la page Ajouter des alertes et des notifications.

Pour plus d'informations sur l'utilisation de l'API, voir Configurer une alerte 404 (application introuvable) pour tous les proxys d'API utilisant l'API.

Configurer une alerte de comptage de proxys d'API pour les API

Vous trouverez ci-dessous un exemple de configuration, à l'aide de l'interface utilisateur, d'une alerte déclenchée lorsque le nombre de codes 5xx pour les API dépasse 200 pendant 5 minutes, quelle que soit la région. Dans cet exemple, les API sont capturées dans la collection "Critical API Proxies". Pour en savoir plus, consultez les pages suivantes :

• ajouter des alertes et des notifications ;
• Gérer les collections

Pour en savoir plus sur l'utilisation de l'API, consultez la page Configuration d'une alerte de comptage de proxy d'API pour les API utilisant l'API.

Configurer une alerte de taux d'erreur pour les services cibles

Vous trouverez ci-dessous un exemple de configuration, à l'aide de l'interface utilisateur, d'une alerte déclenchée lorsque le taux de codes 500 des services cibles dépasse 10 % pendant une heure, quelle que soit la région. Dans cet exemple, les services cibles sont capturés dans la collection "Critical targets". Pour en savoir plus, consultez les pages suivantes :

• ajouter des alertes et des notifications ;
• Gérer les collections

Pour plus d'informations sur l'utilisation de l'API, consultez la section Configurer une alerte de taux d'erreur pour les services cibles à l'aide de l'API.

Configurer une alerte de taux d'erreur pour la règle Service Callout

Vous trouverez ci-dessous un exemple de configuration, à l'aide de l'interface utilisateur, d'une alerte déclenchée lorsque le taux de codes 500 du service spécifié par la règle Service Callout dépasse 10 % pendant une heure, quelle que soit la région. Pour en savoir plus, consultez les pages suivantes :

• ajouter des alertes et des notifications ;

Pour plus d'informations sur l'utilisation de l'API, consultez la page Configurer une alerte de taux d'erreur pour la règle Service Callout à l'aide de l'API.

Configurer une alerte de code d'erreur de règle

L'exemple suivant illustre comment configurer, à l'aide de l'interface utilisateur, une alerte déclenchée lorsque le nombre de codes d'erreur JWT AlgorithmMismatch pour la règle VerifyJWT est supérieur à 5 pendant 10 minutes pour toutes les API. Pour en savoir plus, consultez les pages suivantes :

• ajouter des alertes et des notifications ;
• Gérer les collections

Pour plus d'informations sur l'utilisation de l'API, consultez la section Configurer une alerte de code d'erreur pour un code d'erreur de règle à l'aide de l'API.