Démarrez aujourd'hui et bénéficiez de 20% de réduction sur votre première facture. Disponible sur toutes les formules.

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 {{@ ...}}:

Variable Description Exemple de valeur
@alert.alertGuid Identifiant unique de cette alerte cbfc7769-edb2-46a7-89d0-1e1b1fb0815b
@alert.type

Le 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.timestampUtc Date et heure de l'alerte, exprimées en heure UTC et formatées en ISO 8601. 2018-11-08T16:26:58
@alert.timestamp La 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.firstErrorUtc Date 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.firstError La 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.errorTypeId

L'identifiant de l'erreur qui a déclenché cette alerte, voir les Types d'erreur pour une liste complète.

5407
@alert.description Description textuelle de l'erreur qui a déclenché cette alerte Résultat DNS attendu introuvable
@alert.firstErrorCheckUrl L'URL d'un lien profond qui décrit l'erreur qui a déclenché cette alerte. https://app.uptrends.com/Report/ProbeLog/Check/30833627687
@alert.firstErrorCheckId L'identifiant de l'erreur qui a déclenché cette alerte. 30833627687
@alertDefinition.guid L'identifiant unique de la définition d'alerte qui a été utilisée pour générer cette alerte 2C97E464-6112-435B-8C8D-6DEF1E18273A
@alertDefinition.name Le nom de la définition d'alerte qui a été utilisée pour générer cette alerte Alerte par défaut
@escalationLevel.id L'identifiant du niveau d'escalade utilisé pour générer cette alerte 1
@escalationLevel.message Le message personnalisé qui a été spécifié dans le niveau d'escalade Merci d'utiliser la checklist de contrôle THX-1138 pour enquêter sur ce problème.
@incident.key Identifiant 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.monitorGuid L'identifiant unique du moniteur de votre compte qui a déclenché cette alerte 849b2046-213d-43ad-9efc-5af1faaeb222
@monitor.name Le nom du moniteur de votre compte qui a déclenché cette alerte GalacticResorts.com - DNS
@monitor.notes Toutes les notes personnalisées rajoutées dans les paramètres du moniteur Merci de vérifier les entrées DNS d'Amazon Route53
@monitor.url L'URL ou l'adresse réseau vérifié par ce moniteur. https://galacticresorts.com
@monitor.dashboardUrl L'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.editUrl L'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.accountId Votre identifiant de compte Uptrends 299840

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.