Configuration d’une intégration personnalisée

Imaginez connecter votre compte Uptrends au logiciel de gestion de votre organisation. Intégrer vos données d’alerte d’Uptrends avec vos processus de gestion d’incidents existants permet un fonctionnement transparent dans les procédures quotidiennes que vos équipes utilisent déjà.

Si nos types d’intégration prédéfinis n’incluent pas votre logiciel DevOps, vous pouvez utiliser l’option d’intégration personnalisée pour créer l’intégration vous-même. La clé pour construire une intégration réussie est de connaître le type de message attendu par l’autre système. La documentation de l’API du tiers vous indique quelle URL utiliser et quel contenu envoyer à cet URL. Souvent appelées intégrations webhook, elles permettent à Uptrends de se connecter à l’autre système avec des appels directs. Uptrends peut initier un appel à l’intégration dès qu’une alerte pertinente apparaît.

Le contenu est généralement au format JSON (mais XML et d’autres formats conviennent également) et contient les différents champs qui ont une signification et une importance particulières dans ce système.

Créer le bon contenu de message

Pour remplir un contenu pertinent pour ces champs dans chaque message d’alerte sortant, le corps du message que vous définissez doit contenir des variables dites système. Lorsque vous faites référence à une variable système dans le contenu de votre message, elle est remplacée par le contenu approprié lorsqu’Uptrends génère une alerte. L’utilisation de variables système vous permet d’écrire des définitions de message qui répondent aux attentes de l’autre système.

Prenons un exemple. Une information évidente qui devrait probablement faire partie de tout message d’alerte est une description en texte clair de l’erreur détectée par Uptrends. Supposons que le système auquel vous souhaitez vous connecter possède un champ appelé “errordescription”. Vous pouvez insérer la description d’erreur d’Uptrends dans ce champ en incluant cette définition dans votre message au format JSON:

{ "errordescription": "{{@alert.description}}" }

Dans les variables système d’Uptrends, la description textuelle de l’erreur qui déclenche une alerte est disponible dans la variable {{@ alert.description}}, il vous suffit donc de placer cette variable là où vous en avez besoin dans votre message. De même, vous pouvez utiliser {{@ alert.timestamp}} pour faire référence à l’heure de l’alerte, {{@ monitor.name}} pour inclure le nom du moniteur, etc. Toutes les variables système disponibles sont répertoriées ci-dessous. Remarquez que toutes les variables système sont nommées {{@ …}}:

VariableDescriptionExemple de valeur
@alert.alertGuidIdentifiant unique de cette alertecbfc7769-edb2-46a7-89d0-1e1b1fb0815b
@alert.typeLe type de ce message d'alerte :
  • Alerte : une nouvelle erreur a été détectée.
  • Ok : l'erreur d'origine a été résolue.
  • Rappel : l'erreur d'origine est toujours en cours.
Alerte | Ok | Rappel
@alert.timestampUtcLa date et heure de l'alerte, exprimées en heure UTC et formatées en ISO 8601.2018-11-08T16:26:58
@alert.timestampLa même date et heure que @ alert.timestampUtc, mais dans le fuseau horaire de votre compte. Également formaté en ISO 8601.2018-11-08T10:26:58
@alert.firstErrorUtcDate et heure de l'erreur d'origine qui a déclenché cette alerte, exprimées en heure UTC et formatées en ISO 8601.2018-11-08T16:21:58
@alert.firstErrorLa même date et heure que @ alert.firstErrorUtc, mais dans le fuseau horaire de votre compte. Également formaté en ISO 8601.2018-11-08T10:21:58
@alert.responseBodyContient le corps de la réponse reçue lorsqu'il est disponible. Notez que le corps de la réponse peut contenir des caractères qui doivent être encodés, par exemple en utilisant @JsonEncode ou @XmlEncode. Le corps de la réponse sera tronqué lorsque sa taille dépasse 1 Mo.{"Status": "error"}
@alert.timestampUtcFormattedLa date et l'heure de l'alerte, exprimées en heure UTC et formatées selon la localisation de votre compte8/28/2020 10:23 PM
@alert.timestampFormattedLa même date et heure que @ alert.timestampUtc, mais dans le fuseau horaire et la localisation de votre compte8/28/2020 12:23 PM
@alert.firstErrorUtcFormattedLa date et l'heure de l'erreur à l'origine de l'alerte, exprimées en heure UTC et formatées selon la localisation de votre compte8/28/2020 10:23 PM
@alert.firstErrorFormattedLa même date et heure que @ alert.firstErrorUtc, mais dans le fuseau horaire et la localisation de votre compte8/28/2020 12:23 PM
@alert.errorTypeId

L'identifiant du type d'erreur de l'erreur qui a déclenché cette alerte, voir Types d'erreur pour une liste des types d'erreur

5407
@alert.descriptionDescription textuelle de l'erreur qui a déclenché cette alerteRésultat DNS attendu introuvable
@alert.firstErrorCheckUrlL'URL d'un lien profond qui décrit l'erreur qui a déclenché cette alertehttps://app.uptrends.com/Report/ProbeLog/Check/30833627687
@alert.firstErrorCheckIdL'identifiant de l'erreur qui a déclenché cette alerte30833627687
@alert.serverIpv4L'adresse IPv4 du serveur sur lequel la vérification a été effectuée178.217.84.4
@alert.serverIpv6L'adresse IPv6 du serveur sur lequel la vérification a été effectuée2a02:2658:103e:4:461:81bb:adbe:82a5
@alert.resolvedIpAddressL'adresse IP qui a été utilisée pour effectuer la vérification. Peut être une adresse ipv4 ou ipv6178.217.84.4 OR 2a02:2658:103e:4:461:81bb:adbe:82a5
@alert.firstErrorDescriptionLa description de l'erreur du premier contrôle du moniteur qui a reçu l'erreurRésultat DNS attendu introuvable
@alertDefinition.guidL'identifiant unique de la définition d'alerte qui a été utilisée pour générer cette alerte2C97E464-6112-435B-8C8D-6DEF1E18273A
@alertDefinition.nameLe nom de la définition d'alerte qui a été utilisée pour générer cette alerteAlerte par défaut
@escalationLevel.idL'identifiant du niveau d'escalade utilisé pour générer cette alerte1
@escalationLevel.messageLe message personnalisé qui a été spécifié dans le niveau d'escaladeMerci d'utiliser la checklist de contrôle THX-1138 pour enquêter sur ce problème.
@incident.keyIdentifiant unique de l'incident associé à cette alerte. Une alerte d'erreur et une alerte Ok partagent la même clé d'incident.ba8ffcb7-5de0-489e-b649-f00f0b447e80-0-30099055746
@monitor.monitorGuidL'identifiant unique du moniteur de votre compte qui a déclenché cette alerte849b2046-213d-43ad-9efc-5af1faaeb222
@monitor.nameLe nom du moniteur de votre compte qui a déclenché cette alerteGalacticResorts.com - DNS
@monitor.notesToutes les notes personnalisées rajoutées dans les paramètres du moniteurMerci de vérifier les entrées DNS d'Amazon Route53
@monitor.typeContient le type de moniteurTransaction
@monitor.urlL'URL ou l'adresse réseau vérifié par ce moniteur.https://galacticresorts.com
@monitor.dashboardUrlL'URL d'un lien profond qui vous mène au tableau de bord de ce moniteur.https://app.uptrends.com/Probe/Dashboard?probeGuids=fe1ad4a2-57c1-49db-af16-ff3a6beaa8d4
@monitor.editUrlL'URL d'un lien profond qui vous amène aux paramètres de ce moniteur.https://app.uptrends.com/Report/Probe?probeGuid=fe1ad4a2-57c1-49db-af16-ff3a6beaa8d4
@account.accountIdVotre identifiant de compte Uptrends299840

Le contenu inséré doit être formaté correctement

Étant donné que le message d’alerte sortant sera le plus souvent au format JSON, il faut respecter des règles pour garder un syntaxe JSON valide. Pour ce faire, certains caractères, tels que les sauts de ligne ou les guillemets, devront être encodés avant de pouvoir être insérés dans le message d’alerte sortant au format JSON. Sinon, ils invalideraient la structure JSON du message sortant, ce qui pourrait générer une erreur chez le récepteur et donc empêcher la prise en compte de l’alerte entrante.

Par exemple, si un champ ‘Notes’ du moniteur (que vous pouvez ajouter au message d’alerte à l’aide de la variable système @monitor.notes) contient de tels caractères (sauts de ligne, guillemets,…), il briserait la structure JSON du message sortant.

Exemple :
{ "notes": "{{@monitor.notes}}" }
Pourrait donner :
{"notes": "Notes de moniteur avec un saut de ligne ou "des guillemets" "}

La structure JSON est cassée et entraînera probablement une gestion incorrecte de l’alerte du côté récepteur. Pour résoudre ce problème, il y a une option qui permet de coder (ou décoder) des bouts de texte pour que le format du message JSON ou XML soit respecté. Avec cette fonction, tous les caractères qui doivent être échappés afin de maintenir le format JSON valide seront automatiquement encodés.

Pour utiliser cette fonction, encapsulez la variable système ou le texte souhaité avec la syntaxe suivante :
{{@JsonEncode (votre-variable-ici)}}

Par exemple, la variable système de notes de moniteur mentionnée précédemment doit être enveloppée comme suit :
{ "Notes": "{{@JsonEncode({{@monitor.notes}})}}"}

En utilisant la fonction @JsonEncode , le texte JSON mentionné précédemment contenant une référence aux notes du moniteur se résout maintenant à :
{"Notes": "Notes de moniteur avec \nun saut de ligne ou \" des guillemets \"" }

Comme vous pouvez le voir, les notes du moniteur sont maintenant insérés correctement, encodées de manière à ne pas casser la structure JSON.

Si vous utilisez XML au lieu de JSON, pas de souci - nous avons une fonction similaire pour l’encodage XML ! Utilisez cette fonction pour encapsuler vos variables système : {{@XmlEncode ()}}.

Messages d’erreur, messages OK et rappels

Lorsque vous créez une définition de message dans l’onglet Personnalisations , Uptrends utilise cette définition de message pour tous les types d’erreur : une alerte d’erreur lorsque la vérification a généré l’alerte pour la première fois, une alerte OK lorsque la vérification résout l’alerte et des alertes de rappel (selon les paramètres de vos niveaux d’escalade) entre les deux.

Le contenu du message est pratiquement le même pour tous les types d’alerte, à l’exception des valeurs d’horodatage et de la variable {{@ alert.type}}, à l’origine du type d’alerte.

Bien que satisfaisant dans de nombreuses situations, l’utilisation du même contenu de message ne suffit pas si vous avez besoin d’un contenu différent pour différents types d’alerte ou si vous devez créer un nouvel incident dans votre système (basé sur une alerte d’erreur) nécessitant une URL différente de celui utilisé pour résoudre ce même incident (sur la base d’une alerte OK).

Des messages séparés pour différents types d’alerte

Pour créer des définitions de message distinctes pour les différents types d’alerte, cliquez sur le bouton “Ajouter des étapes” en bas de l’onglet Personnalisations . Le bouton “Ajouter des étapes” crée une définition de message supplémentaire que vous pouvez utiliser, par exemple, pour seulement les alertes OK. Pour chaque type d’alerte, vous pouvez désormais spécifier la méthode HTTP appropriée (GET / POST / PUT / PATCH / DELETE), l’URL, les en-têtes et le corps de la requête.

Cochez les cases Alerte d’erreur, Alerte OK et Alerte de rappel en haut de chaque définition d’étape pour créer la configuration souhaitée. Les cases cochées s’appliquent à toutes les étapes ; les alertes OK et les alertes de rappel sont facultatives. Si vous ne souhaitez pas envoyer d’alertes OK ou d’alertes de rappels, laissez simplement ces cases décochées.

Les alertes d’erreur et les alertes OK vont de pair

Que vous utilisiez ou non des messages distincts pour les alertes d’erreur et OK, il est utile pour le système externe de savoir quelles alertes vont ensemble. Après tout, chaque incident commence par une alerte d’erreur et se termine par une alerte OK. Pour que le système externe le comprenne, vous pouvez utiliser la variable {{@ incident.key}} dans vos messages. Les alertes d’erreur et OK partagent la même clé d’incident, mais chaque nouvel incident a une clé différente et unique. Dans certains systèmes, la clé d’incident est appelée clé de déduplication ou ID d’incident.

Utilisation de variables

Lorsque l’option Personnaliser est active dans une intégration, vous pouvez gérer une ou plusieurs variables pour cette intégration dans l’onglet Principal. Pour les variables d’intégration prédéfinies (comme indiqué par Spécifier la valeur ici), la valeur par défaut est une valeur fixe. Vous pouvez ensuite faire référence à ces variables dans la définition de message dans l’onglet Personnalisations . Pour en savoir plus sur la définition et l’utilisation des variables, lisez cet article dans la base de connaissances sur l’utilisation des variables dans une configuration d’API multi-étapes. La même approche s’applique aux intégrations.

Pour celles-ci cependant, vous avez une option supplémentaire qui ajoute encore plus de puissance. Supposons que vous ayez créé une intégration qui se connecte à votre système de gestion informatique. L’intégration envoie des informations basées sur le moniteur et sur l’alerte qui ont déclenché le message d’alerte. Mais est-ce suffisant pour que le système de gestion informatique puisse prendre les mesures appropriées ? Pour être sûr, vous pouvez envoyer des informations supplémentaires sur la façon de gérer le nouvel incident. Autrement dit, comment l’incident doit-il être acheminé via le système externe ? Différentes définitions d’alerte (en fait, à l’intérieur des niveaux d’escalade) peuvent spécifier des informations de routage uniques, que vous pouvez inclure dans le message d’alerte sortant.

Pour ce faire, définissez une variable dans l’onglet Principal de l’intégration et choisissez Spécifier la valeur dans le niveau d’escalade. Remarquez que vous ne pouvez plus lui donner de valeur dans l’intégration elle-même. C’est plutôt dans les niveaux d’escalade de vos définitions d’alerte, où vous allez spécifier des valeurs pour cette variable. Par conséquent, vous n’avez besoin de créer qu’une seule définition d’intégration pour votre système de gestion informatique, tout en conservant une flexibilité dans la manière dont toutes les alertes y sont traitées.

Vérification d’une intégration à l’aide de messages de test

Une fois que vous avez créé ou modifié une intégration personnalisée, il est recommandé de la tester avant de l’utiliser en production. L’onglet de personnalisation de l’éditeur d’intégration comporte un bouton intitulé Envoyer un message de test qui vous permet d’envoyer un message de test au système tiers à l’aide des étapes HTTPS que vous avez créées. Lorsque vous utilisez cette fonction de test, vous pouvez sélectionner le type d’alerte (une alerte d’erreur, une alerte OK ou une alerte de rappel) qu’Uptrends doivt utiliser pour ce message de test particulier. Vous pouvez remplir les autres valeurs si nécessaire, et les données restantes (qui seraient normalement des données de surveillance pertinentes et des données d’alerte) seront remplies de valeurs fictives.

Une fois qu’Uptrends génère le message et l’envoie au système tiers ou à l’API, le contenu complet du message, le code de réponse du serveur et le contenu s’affichent. Vous pouvez développer les en-têtes et le contenu des requêtes et des réponses pour inspecter le trafic sortant et entrant associé à ce message de test.

Vérification d’une intégration à l’aide de données en direct

Bien qu’un test statique décrit dans la section précédente soit utile pour tester le fonctionnement de votre message et vos variables et établir que le canal de communication vers le système externe fonctionne correctement, il est bon d’avoir aussi la possibilité de vérifier que l’intégration fonctionne correctement dans une situation réelle.

Tout d’abord, vérifiez que l’une de vos définitions d’alerte utilise réellement votre intégration. Sinon, Uptrends ne déclenche jamais l’intégration pour envoyer des messages. Pour plus d’informations sur la façon d’activer les intégrations dans votre configuration d’alerte, lisez cette leçon de l’Académie sur les niveaux d’escalade.

Ensuite, une situation d’erreur doit se produire pour que votre surveillance génère une véritable alerte. Dès que vous voyez une alerte dans le status des alertes ou dans le tableau de bord du journal des alertes, cliquez dessus pour révéler les détails de cette alerte. L’onglet Détails répertorie toutes les propriétés clés de l’alerte ; l’onglet Messages contient les informations dont vous avez besoin pour inspecter le trafic des messages entre Uptrends et le système externe.

Dans l’onglet Messages, recherchez l’intégration que vous souhaitez inspecter ; il peut y avoir d’autres intégrations qui ont également été déclenchées par cette alerte. Développez le panneau d’intégration contenant les requêtes et réponses. Vous verrez le contenu complet du ou des messages sortants, les réponses renvoyées par le système externe et éventuellement des messages d’erreur qui se sont produits en cas de problème lors de l’envoi du message d’alerte.

Inclure des identifiants externes ou des données personnalisées

Lorsque vous intégrez Uptrends à un système tiers, il est utile de configurer une relation entre vos moniteurs Uptrends et les ressources (parfois appelées composants ou services) que vous avez définies dans le système tiers. Les moniteurs de votre compte Uptrends ont un nom et un identifiant unique (un monitorGuid), mais ceux-ci ne sont généralement pas connus dans le système tiers. Les ressources définies dans le système tiers ont probablement aussi leur propre identifiant, qu’Uptrends ne connaît pas non plus.

Si vous souhaitez qu’un moniteur dans Uptrends déclenche un incident pour une ressource spécifique de l’autre côté, vous devez définir une sorte de relation entre les deux. Dans Uptrends, vous pouvez définir cette relation en prenant l’identifiant (ou d’autres informations importantes) de la ressource/composant externe et en l’ajoutant en tant que valeur personnalisée dans les paramètres d’un moniteur.

Par conséquent, les données d’alerte envoyées au système externe par Uptrends peuvent inclure cet identifiant, de sorte que le système récepteur sache quelle ressource ou composant est affecté par l’alerte entrante.

Vous pouvez ajouter des champs personnalisés dans la section Métadonnées de l’onglet Principal d’un moniteur. Mis à part la valeur externe que vous souhaitez stocker, chaque champ personnalisé doit également avoir un nom unique de façon à pouvoir y faire référence dans un message d’alerte. Par exemple, supposons que votre système tiers ait le concept de composants et que chaque composant ait un ComponentId comme identifiant unique. Il faudrait spécifier ce ComponentId dans les paramètres du moniteur d’Uptrends, afin que les deux puissent être liés ensemble.

Pour ce faire, recherchez la section Champs personnalisés dans les paramètres de votre moniteur. Ajoutez un champ personnalisé en remplissant « ComponentId » comme nom de champ et une valeur externe appropriée (par exemple, 7149488f-0b33-460d-85eb-210c0e80d7ba) comme valeur de champ. Cliquez sur Enregistrer pour sauvegarder les nouveaux paramètres.

Désormais la valeur externe va être envoyée dans le message d’alerte ; il fait partie du corps de la requête du message sortant. Vous pouvez utiliser la fonction {{@CustomField ()}} pour faire référence au champ personnalisé que vous venez d’ajouter. Par exemple, vous pouvez ajouter ce fragment au corps de la requête :

{ "Component": "{{@CustomField(ComponentId)}}" }

Remarquez que le nom de champ “ComponentId” que nous avons utilisé dans les paramètres du moniteur est littéralement inclus dans l’appel de fonction @CustomField (). Lorsqu’une véritable alerte est déclenchée, le contenu suivant sera généré :

{ "Component": "7149488f-0b33-460d-85eb-210c0e80d7ba" }

Le système externe peut utiliser cette valeur pour créer un incident pour le composant indiqué. Cet exemple utilise un seul champ personnalisé, mais vous pouvez en utiliser plusieurs si vous le souhaitez.

En utilisant ce site, vous consentez à l’utilisation de cookies conformément à notre Politique de cookies.