Starte noch heute mit dem Monitoring und erhalte 20% Rabatt auf Deine erste Rechnung. Gültig für alle Versionen.

Stell dir vor, deinen Uptrends Account mit den betrieblichen Managementsystemen deines Unternehmens zu verknüpfen. Wenn du die Warnmeldedaten von Uptrends in deine bestehende Managementabläufe für Ereignisse einspeist, erzeugt dies eine nahtlose Integration des externen Monitorings von Uptrends in die alltäglichen Prozesse deines Teams.

Sollten unsere vordefinierten Integrations-Typen deine DevOps-Software nicht unterstützen, kannst du die Möglichkeit der benutzerdefinierten Integration nutzen, um selbst eine Integration zu entwickeln. Der Schlüssel einer erfolgreichen Integration liegt in dem Wissen, welche Form der Nachricht das andere System erwartet. In der Dokumentation der API des Drittanbieters findest du, welche URL und welche Inhalte du in dieser URL eingeben musst. Sie werden häufig als Webhook-basierte Integrationen bezeichnet, denn sie ermöglichen, dass sich beispielsweise Uptrends in das System „einhaken“ kann, indem es direkte Aufrufe erlaubt. Uptrends kann einen Aufruf bei der Integration initiieren, sobald eine relevante Warnmeldung ausgegeben wird.

Der Inhalt ist in der Regel im JSON-Format (aber XML und andere Formate können ebenfalls verwendet werden) und enthält verschiedene Felder, die in dem System eine bestimmte Bedeutung und Relevanz haben.

Den richtigen Nachrichteninhalt erzeugen

Um den entsprechenden Inhalt für diese Felder in jeder ausgehenden Warnmeldung einzugeben, muss die von dir definierte Nachricht sogenannte Systemvariablen enthalten. Wenn du in deiner Nachricht auf eine Systemvariable verweist, wird sie durch den entsprechenden Inhalt ersetzt, wenn Uptrends eine Warnmeldung generiert. Der Einsatz von Systemvariablen ermöglicht dir, Nachrichtendefinitionen zu programmieren, die den Erwartungen des anderen Systems entsprechen.

Sehen wir uns ein Beispiel an: Eine augenscheinliche Information, die sicherlich Teil einer Warnmeldung sein sollte, ist die nicht formatierte Beschreibung des Fehlers, der von Uptrends identifiziert wurde. Nehmen wir an, das System, zu dem du eine Verbindung herstellen möchtest, verfügt über ein Feld namens „errordescription“. Du kannst die Fehlerbeschreibung von Uptrends in das Feld einfließen lassen, indem du diese Definition in deine JSON-formatierte Nachricht einfügst.

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

Bei Uptrends‘ Systemvariablen steht die textliche Beschreibung des Warnmeldungen auslösenden Fehlers in der Variable {{@alert.description}} bereit, sodass du einfach diese Variable dort in deine Nachricht schreibst, wo sie benötigt wird. Auf gleiche Weise kannst du {{@alert.timestamp}} verwenden, um auf den Zeitpunkt der Warnmeldung zu verweisen, {{@monitor.name}}, um den Prüfobjektnamen einzufügen usw. Alle verfügbaren Systemvariablen werden nachfolgend aufgelistet. Beachte, dass alle Systemvariablen mit {{@...}} benannt sind:

Variable Beschreibung Beispielwert
@alert.alertGuid Einzigartige ID der Warnmeldung. cbfc7769-edb2-46a7-89d0-1e1b1fb0815b
@alert.type Der Typ der Warnmeldung: Fehler: Ein Fehler wurde identifiziert. Ok: Der ursprüngliche Fehler wurde behoben. Erinnerung: Der ursprüngliche Fehler besteht weiterhin. Fehler | Ok | Erinnerung
@alert.timestampUtc Datum und Uhrzeit der Warnmeldung, in UTC-Zeit und nach ISO 8601 formatiert. 2018-11-08T16:26:58
@alert.timestamp Das gleiche Datum mit Uhrzeit wie @alert.timestampUtc, aber in der Zeitzone deines Accounts. Ebenfalls nach ISO 8601 formatiert. 2018-11-08T10:26:58
@alert.firstErrorUtc Datum und Uhrzeit des ursprünglichen Fehlers, der diese Warnmeldung ausgelöst hat, in UTC-Zeit und nach ISO 8601 formatiert. 2018-11-08T16:21:58
@alert.firstError Das gleiche Datum mit Uhrzeit wie @alert.firstErrorUtc, aber in der Zeitzone deines Accounts. Ebenfalls nach ISO 8601 formatiert. 2018-11-08T10:21:58
@alert.errorTypeId Die Fehlertyp-ID des Fehlers, zu dem diese Warnmeldung ausgelöst wurde. 5407
@alert.description Textbeschreibung des Fehlers, der die Warnmeldung ausgelöst hat. DNS – erwartetes Ergebnis nicht gefunden
@alert.firstErrorCheckUrl Die URL des Deep Links, der dich zu den Details des Fehlers führt, der die Warnmeldung ausgelöst hat. https://app.uptrends.com/Report/ProbeLog/Check/30833627687
@alert.firstErrorCheckId Die ID des Fehlers, der die Warnmeldung ausgelöst hat. 30833627687
@alertDefinition.guid Die einzigartige ID der Meldedefinition, die zur Erzeugung dieser Warnmeldung führte. 2C97E464-6112-435B-8C8D-6DEF1E18273A
@alertDefinition.name Der Name der Meldedefinition, die zur Erzeugung dieser Warnmeldung führte. Standard-Warnmeldung
@escalationLevel.id Die ID der Eskalationsstufe, die zur Erzeugung dieser Warnmeldung führte. 1
@escalationLevel.message Die benutzerdefinierte Nachricht, die in der Eskalationsstufe festgelegt wurde. Bitte Checkliste THX-1138 verwenden, um dieses Problem zu untersuchen.
@incident.key Einzigartige ID des Ereignisses, zu dem diese Warnmeldung erfolgte. Eine Fehlerwarnmeldung und eine Ok-Meldung haben denselben Ereignisschlüssel. ba8ffcb7-5de0-489e-b649-f00f0b447e80-0-30099055746
@monitor.monitorGuid Die einzigartige ID des Prüfobjekts deines Accounts, das die Warnmeldung ausgelöst hat. 849b2046-213d-43ad-9efc-5af1faaeb222
@monitor.name Der Name des Prüfobjekts deines Accounts, das die Warnmeldung ausgelöst hat. GalacticResorts.com - DNS
@monitor.notes Alle benutzerdefinierten Anmerkungen, die in den Einstellungen des Prüfobjekts eingegeben wurden. Bitte Amazon Route53 DNS Einträge prüfen.
@monitor.url Die URL oder Netzwerkadresse, die dieses Prüfobjekt testet. https://galacticresorts.com
@monitor.dashboardUrl Die URL eines Deep Links, der dich zum Dashboard dieses Prüfobjekts führt. https://app.uptrends.com/Probe/Dashboard?probeGuids=fe1ad4a2-57c1-49db-af16-ff3a6beaa8d4
@monitor.editUrl Die URL eines Deep Links, der dich zu den Einstellungen dieses Prüfobjekts führt. https://app.uptrends.com/Report/Probe?probeGuid=fe1ad4a2-57c1-49db-af16-ff3a6beaa8d4
@account.accountId Deine Uptrends Account ID. 299840

Fehlermeldungen, OK-Meldungen und Erinnerungen

Wenn du eine Nachrichtendefinition in der Registerkarte Anpassungen erstellst, verwendet Uptrends diese Nachrichtendefinition für alle Fehlertypen: eine Fehlermeldung, wenn der Check einen Alarm generiert, eine OK-Meldung, wenn der Check den Alarm aufgelöst hat und dazwischen Erinnerungen (abhängig von den Einstellungen der Eskalationsstufen).

Der Nachrichteninhalt ist praktisch derselbe für alle Alarmtypen, außer für die timestamp-Werte und die Variable {{@alert.type}}, die den Alarmtyp selbst ausgibt.

Obwohl derselbe Nachrichteninhalt in vielen Situationen ausreicht, ist er unzureichend, wenn du unterschiedliche Inhalte für verschiedene Alarmtypen benötigst oder wenn du ein neues Ereignis in deinem System (basierend auf einer Fehlermeldung) erstellen musst, das eine andere URL erfordert als die Auflösung desselben Ereignisses (basierend auf einer OK-Meldung).

Unterschiedliche Nachrichten für verschiedene Alarmtypen

Um separate Nachrichtendefinitionen für Alarmierungstypen zu erstellen, klicke auf die Schaltfläche „Füge Schritte“ unten auf der Registerkarte Anpassungen. Die Schaltfläche „Füge Schritte“ erzeugt eine zusätzliche konfigurierbare Nachrichtendefinition, die beispielsweise nur für OK-Meldungen genutzt wird. Für jeden Alarmtyp kannst du die geeignete HTTP-Methode (GET/POST/PUT/PATCH/DELETE), URL, Header und Request Body (Anfrage) angeben.

Klicke auf die Kontrollkästchen Fehler Alarm, OK Alarm und Erinnerungs-Alarm über jeder Schritte-Definition, um die gewünschte Einrichtung zu erstellen. Du kannst jeden Alarmtyp einmal aktivieren, aber OK-Alarme und Erinnerungs-Alarme sind optional. Wenn du gar keine OK-Alarme oder Erinnerungen senden möchtest, belasse die Kontrollkästchen einfach deaktiviert.

Fehlermeldungen und OK-Meldungen gehören zusammen

Ob du separate Nachrichten für Fehler- und OK-Meldungen verwendest oder nicht – für das externe System ist es wahrscheinlich nützlich zu wissen, welche Alarme zusammengehören. Schließlich beginnt jedes Ereignis mit einer Fehler-Meldung und endet mit einer OK-Meldung. Um dem externen System bei dieser Identifikation zu helfen, kannst du die Variable {{@incident.key}} in deinen Nachrichten verwenden. Fehlermeldungen und Ok-Meldungen haben denselben Ereignisschlüssel, aber jedes neue Ereignis hat einen einzigartigen Schlüssel. Bei einigen Systemen wird der Ereignisschlüssel als „Deduplication Key“ oder als „Ereignis-ID“ bezeichnet.

Variablen verwenden

Wenn die Anpassungsoption bei einer Integration aktiv ist, kannst du eine oder mehrere Variablen für diese Integration auf der Registerkarte „Allgemein“ verwalten. Die Standardeinstellung für vordefinierte Integrationsvariablen (wie durch „Wert hier eintragen“ angezeigt) ist, dass der Wert für diese Variablen als fester Wert in der Integration definiert ist. Du kannst dann auf der Registerkarte Anpassungen in der Nachrichtendefinition auf diese Variablen verweisen. Weitere Informationen zur Definition und Verwendung von Variablen findest du im Artikel Variablen im Multi-step API Monitoring in der Knowledge Base. Für Integrationen gilt der gleiche Ansatz.

Bei Integrationen verfügst du jedoch über eine weitere Option, die dir noch mehr Kontrolle gibt. Nehmen wir an, du hast eine Integration erstellt, die mit deinem IT-Managementsystem verbindet. Die Integration sendet Informationen aufgrund eines Prüfobjekts und eines Alarms, die eine Warnmeldung ausgelöst haben. Aber sind das ausreichend Informationen für das IT-Managementsystem, um entsprechende Maßnahmen zu aktivieren? Du kannst zusätzliche Informationen dazu senden, wie das neue Ereignis zu behandeln ist. Üblicherweise kannst du diese Information folgendermaßen ausdrücken: Wie sollte das Ereignis durch das externe System geleitet werden? Verschiedene Meldedefinitionen (und damit auch jede Eskalationsstufe) kann besondere Weiterleitungsinformationen bestimmen, die du in der ausgehenden Alarmierungsnachricht integrieren kannst.

Definiere hierfür auf der Registerkarte Allgemein der Integration eine Variable und wähle Wert in Eskalations-Level definieren. Beachte, dass du bei der Integration selbst keinen Wert mehr eintragen kannst. Stattdessen kannst du bei der Angabe der Integration in den Eskalationsstufen deiner Meldedefinitionen Werte für diese Variable dort angeben. Das hat den Vorteil, dass du nur eine einzige Integrationsdefinition für dein IT-Managementsystem erstellen musst, aber die Flexibilität in der Form behältst, dass alle Alarme dort gehandhabt werden.

Prüfen einer Integration anhand von Testnachrichten

Sobald du eine benutzerdefinierte Integration geändert oder erstellt hast, macht es Sinn, sie zu testen, bevor sie aktiviert wird. Auf der Registerkarte Anpassungen im Integrationseditor gibt es die Schaltfläche Sende Test-Alarm, mithilfe dessen du eine Testnachricht an das Drittsystem unter Anwenden der/des von dir erstellten HTTPS-Schritte/s übermitteln kannst. Bei der Testfunktion kannst du wählen, welchen Alarmtyp (Fehler, OK oder Erinnerung) Uptrends für diese spezielle Testnachricht verwenden soll. Du kannst bei Bedarf alle sonstigen angemessenen Werte eingeben und die verbleibenden Daten (die in der Regel Prüfobjektdaten und Alarmdaten sind) werden mit fiktionalen Werten ausgefüllt.

Sobald Uptrends die Nachricht generiert und sie an das Drittsystem oder die API sendet, wird der vollständige Nachrichtentext, der Antwortcode des Servers und der Inhalt angezeigt. Du kannst die Request Header und Inhalte und die Response Header und Inhalte einblenden, um den aus- und eingehenden Traffic, der beim Senden dieser Testnachricht entstanden ist, zu untersuchen.

Prüfen einer Integration anhand von echten Daten

Die oben beschriebene Testfunktion ist nützlich für das statische Testen deiner Nachrichten und Variablen sowie um festzustellen, dass der Kommunikationskanal zum externen System richtig funktioniert. Aber du solltest auch verifizieren können, dass die Integration in der Produktion ebenfalls korrekt funktioniert.

Stelle zunächst sicher, dass eine deiner Meldedefinitionen tatsächlich deine Integration verwendet. Andernfalls wird Uptrends niemals die Integration anstoßen, Nachrichten auszusenden. Weitere Informationen zur Aktivierung von Integrationen in deiner Alarmierungseinrichtung erhältst du in der Academy zum Thema Eskalationsstufen. Dann muss ein Fehler auftreten, sodass dein Prüfobjekt einen tatsächlichen Alarm auslöst. Sobald du einen Alarm unter „Meldestatus“ oder im Dashboard „Alarmierungshistorie“ siehst, klicke darauf, um die Details zu dem Alarm anzuzeigen. Die Registerkarte Details, führt alle wichtigen Eigenschaften des Alarms auf. Die Registerkarte Nachrichten enthält die benötigte Information, um den Nachrichten-Traffic zwischen Uptrends und dem externen System zu untersuchen.

Suche auf der Registerkarte Nachrichten die Integration, die du untersuchen möchtest. Es können auch andere Integrationen angezeigt werden, die ebenfalls von diesem Alarm angestoßen wurden. Erweitere den Integrationsbereich und die darin enthaltenen Anfragen und Antworten. Du siehst den vollständigen Inhalt der ausgehenden Nachricht(en), die vom externen System zurückgesendeten Antworten und jegliche Fehlermeldungen, wenn beim Senden des Alarms ein Problem aufgetreten ist.

Externe IDs oder benutzerdefinierte Daten hinzufügen

Wenn du Uptrends in ein Drittsystem integrierst, solltest du überlegen, ob eine Beziehung zwischen deinen Uptrends-Prüfobjekten und den im Drittsystem von dir definierten Ressourcen (manchmal Komponenten oder Services genannt) besteht. Die Prüfobjekte in deinem Uptrends Account haben einen Namen und eine einzigartige Kennung (eine monitorGuid), die das Drittsystem üblicherweise jedoch nicht kennt. Die im Drittsystem definierten Ressourcen verfügen wahrscheinlich über eigene Kennungen, die wiederum Uptrends nicht kennt.

Wenn ein Prüfobjekt in Uptrends ein Ereignis für eine bestimmte Ressource auf der anderen Seite auslösen soll, musst du eine Art Beziehung zwischen den beiden definieren. In Uptrends kannst du diese Beziehung durch die Kennung (oder andere wichtige Informationen) der externen Ressource/Komponente definieren, indem du sie als benutzerdefinierten Wert in den Einstellungen eines Prüfobjekts eingibst.

Dann können die Alarmierungsdaten, die von Uptrends an das externe System gesendet werden, diese Kennung enthalten, sodass das empfangende System weiß, welche Ressource oder Komponente von der eingehenden Meldung betroffen ist.

Du kannst im Bereich „Metadaten“ auf der Registerkarte Allgemein eines Prüfobjekts benutzerdefinierte Felder hinzufügen. Neben dem externen Wert, den du speichern solltest, muss jedes benutzerdefinierte Feld auch einen einzigartigen Namen haben, sodass wir uns in der Alarmierungsnachricht darauf beziehen können. Beispielsweise könnte das Drittsystem nach dem Komponenten-Konzept arbeiten und jede Komponente verfügt über eine ComponentId als einzigartige Kennung. Diese ComponentId solltest du dann in den Prüfobjekteinstellungen bei Uptrends angeben, sodass die beiden miteinander verknüpft werden können.

Scrolle dazu zum Bereich „Benutzerdefinierte Felder“ in den Einstellungen des Prüfobjekts. Füge ein benutzerdefiniertes Feld hinzu, indem du „ComponentId“ als Feldname und den entsprechenden externen ID-Wert (z. B. 7149488f-0b33-460d-85eb-210c0e80d7ba) als Feldwert eingibst. Klicke auf Speichern, um deine Einstellungen zu bewahren.

Wir können nun sicherstellen, dass der externe Wert als Teil der Alarmierungsnachricht mitgesendet wird. Dazu fügen wir ihn in den Anfragetext (Request Body) der ausgehenden Nachricht ein. Du kannst auch die Funktion {{@CustomField()}} nutzen, um auf das gerade hinzugefügte benutzerdefinierte Feld zu verweisen. Du könntest beispielsweise dieses Fragment in den Request Body einfügen:

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

Beachte, wie der Feldname „ComponentId“ aus den Prüfobjekteinstellungen identisch im Funktionsaufruf @CustomField() eingefügt wurde. Wenn ein echter Alarm ausgelöst wird, wird der folgende Inhalt erzeugt:

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

Das externe System kann diesen Wert verwenden, um ein Ereignis für die richtige Komponente zu melden. Dieses Beispiel hat nur ein benutzerdefiniertes Feld, aber du kannst bei Bedarf mehrere benutzerdefinierte Werte einsetzen.