Alerts mithilfe der Alert-API verwalten

Sie können Alerts in einer IBM Cloud Monitoring Instanz verwalten, indem Sie die Monitoring API.

Informationen zur Verwendung von cURL finden Sie unter cURL-Befehl.

Details zu einem Benutzeralert abrufen

Sie können den folgenden cURL-Befehl verwenden, um Informationen zu einem Alert abzurufen:

curl -X GET <REST_API_ENDPOINT>/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json"

Wo

  • <REST_API_ENDPOINT> gibt den Endpunkt an, auf den der REST-API-Aufruf abzielt. Weitere Informationen finden Sie unter MonitoringREST-API-Endpunkte. Der öffentliche Endpunkt für eine Instanz, die in der Region 'us-south' verfügbar ist, ist beispielsweise folgender: https://us-south.monitoring.cloud.ibm.com/api

  • Sie können mehrere Header übergeben, indem Sie -H verwenden.

    Authorization und IBMInstanceID sind Header, die für die Authentifizierung erforderlich sind.

    Der Header TeamID ist optional. Wenn Sie diesen Header angeben, begrenzen Sie die Anforderung auf die Daten und Ressourcen, die für das angegebene Team verfügbar sind.

    Informationen zum Abrufen eines Autorisierungstokens (AUTH_TOKEN) und der GUID finden Sie unter Header für IAM-Tokens.

  • <ALERT_ID> gibt die ID der Meldung an, die Sie ändern möchten.

Der Antwortteil für einen Alert sieht beispielsweise wie folgt aus:

{
  "alert": {
    "autoCreated": false,
    "condition": "min(min(dallas_prod)) = 0",
    "createdOn": 1551358413000,
    "enabled": false,
    "id": 23211,
    "modifiedOn": 1551634372000,
    "name": "Monitoring Uptime Alert",
    "filter": "env in (\"prod\")",
    "notificationChannelIds": [
      4
    ],
    "segmentBy": [
      "host.hostname"
    ],
    "segmentCondition": {
      "type": "ANY"
    },
    "notificationCount": 60,
    "rateOfChange": false,
    "reNotify": false,
    "severity": 0,
    "severityLabel": "HIGH",
    "teamId": 493,
    "timespan": 60000000,
    "type": "MANUAL",
    "version": 9
  }
}

Alert erstellen

Sie können den folgenden cURL-Befehl verwenden, um einen Alert zu erstellen:

curl -X POST <REST_API_ENDPOINT>/api/alerts -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json" -d @alert.json

Wo

  • <REST_API_ENDPOINT> gibt den Endpunkt an, auf den der REST-API-Aufruf abzielt. Weitere Informationen finden Sie unter MonitoringREST-API-Endpunkte. Der öffentliche Endpunkt für eine Instanz, die in der Region 'us-south' verfügbar ist, ist beispielsweise folgender: https://us-south.monitoring.cloud.ibm.com/api

  • Sie können mehrere Header übergeben, indem Sie -H verwenden.

    Authorization und IBMInstanceID sind Header, die für die Authentifizierung erforderlich sind.

    Der Header TeamID ist optional. Wenn Sie diesen Header angeben, begrenzen Sie die Anforderung auf die Daten und Ressourcen, die für das angegebene Team verfügbar sind.

    Informationen zum Abrufen eines Autorisierungstokens (AUTH_TOKEN) und der GUID finden Sie unter Header für IAM-Tokens.

  • Sie können Daten übergeben, um den Alert in der Datei alert.json zu erstellen, indem Sie -d verwenden.

    Wenn Sie einen Alert erstellen, schließen Sie die folgenden Parameter ein: type, name, severity, timespan, condition, segmentby, segmentConditionn, filter, notificationChannelIds, enabled

    Weitere Informationen hierzu finden Sie im Abschnitt Alertschema.

Das folgende Beispiel zeigt die Parameter für den Anforderungshauptteil, die Sie für die Erstellung eines Alerts festlegen können:

{
  "alert": {
    "version": null,
    "name": "My Alert!",
    "description": null,
    "teamId": null,
    "enabled": false,
    "filter": null,
    "type": "MANUAL",
    "condition": "avg(timeAvg(uptime)) <= 0",
    "timespan": 600000000,
    "notificationChannelIds": [],
    "reNotify": false,
    "reNotifyMinutes": 30,
    "segmentBy": [
      "host.hostName"
    ],
    "segmentCondition": {
      "type": "ANY"
    },
    "severityLabel": "LOW"
  }
}

Alert aktualisieren

Um einen vorhandenen Alert zu aktualisieren, benötigen Sie die ID dieses Alerts.

Sie können den folgenden cURL-Befehl verwenden, um einen Alert zu aktualisieren:

curl -X PUT <REST_API_ENDPOINT>/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json" -d @alert.json

Wo

  • <REST_API_ENDPOINT> gibt den Endpunkt an, auf den der REST-API-Aufruf abzielt. Weitere Informationen finden Sie unter MonitoringREST-API-Endpunkte. Der öffentliche Endpunkt für eine Instanz, die in der Region 'us-south' verfügbar ist, ist beispielsweise folgender: https://us-south.monitoring.cloud.ibm.com/api

  • Sie können mehrere Header übergeben, indem Sie -H verwenden.

    Authorization und IBMInstanceID sind Header, die für die Authentifizierung erforderlich sind.

    Der Header TeamID ist optional. Wenn Sie diesen Header angeben, begrenzen Sie die Anforderung auf die Daten und Ressourcen, die für das angegebene Team verfügbar sind.

    Informationen zum Abrufen eines Autorisierungstokens (AUTH_TOKEN) und der GUID finden Sie unter Header für IAM-Tokens.

  • <ALERT_ID> gibt die ID der Meldung an, die Sie ändern möchten.

  • Sie können Daten übergeben, um den Alert in der Datei alert.json zu erstellen, indem Sie -d verwenden.

    Weitere Informationen hierzu finden Sie im Abschnitt Alertschema.

Das folgende Beispiel zeigt die Parameter für den Anforderungshauptteil, die Sie für die Aktualisierung eines Alerts festlegen können:

{
  "alert": {
      "type": "MANUAL",
      "id": 23212,
      "version": 10,
      "name": "CheckNginxConnections",
      "description": "Active connections of nginx server",
      "enabled": false,
      "severity": 2,
      "timespan": 1000000,
      "condition": "avg(avg(nginx.net.connections)) > 1000",
      "segmentBy": [
          "host.hostName"
      ],
      "segmentCondition": {
          "type": "ANY"
      },
      "notificationChannelIds": [
          2
      ]
    }
}

Alert löschen

Um einen vorhandenen Alert zu löschen, benötigen Sie die ID dieses Alerts.

Sie können den folgenden cURL-Befehl verwenden, um einen Alert zu löschen:

curl -X DELETE <REST_API_ENDPOINT>/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json"

Wo

  • <REST_API_ENDPOINT> gibt den Endpunkt an, auf den der REST-API-Aufruf abzielt. Weitere Informationen finden Sie unter MonitoringREST-API-Endpunkte. Der öffentliche Endpunkt für eine Instanz, die in der Region 'us-south' verfügbar ist, ist beispielsweise folgender: https://us-south.monitoring.cloud.ibm.com/api

  • Sie können mehrere Header übergeben, indem Sie -H verwenden.

    Authorization und IBMInstanceID sind Header, die für die Authentifizierung erforderlich sind.

    Der Header TeamID ist optional. Wenn Sie diesen Header angeben, begrenzen Sie die Anforderung auf die Daten und Ressourcen, die für das angegebene Team verfügbar sind.

    Informationen zum Abrufen eines Autorisierungstokens (AUTH_TOKEN) und der GUID finden Sie unter Header für IAM-Tokens.

  • <ALERT_ID> gibt die ID der Ausschreibung an, die Sie löschen möchten.

Alle Benutzeralerts abrufen

Sie können den folgenden cURL-Befehl verwenden, um Informationen zu allen Alerts abzurufen:

curl -X GET <REST_API_ENDPOINT>/api/alerts?from=<START_TIMESTAMP>&to=<END_TIMESTAMP> -H "Authorization: Bearer $AUTH_TOKEN" -H "IBMInstanceID: $GUID"

Wo

  • <REST_API_ENDPOINT> gibt den Endpunkt an, auf den der REST-API-Aufruf abzielt. Weitere Informationen finden Sie unter MonitoringREST-API-Endpunkte. Der öffentliche Endpunkt für eine Instanz, die in der Region 'us-south' verfügbar ist, ist beispielsweise folgender: https://us-south.monitoring.cloud.ibm.com/api

  • Sie können mehrere Header übergeben, indem Sie -H verwenden.

    Authorization und IBMInstanceID sind Header, die für die Authentifizierung erforderlich sind. Informationen zum Abrufen eines Autorisierungstokens (AUTH_TOKEN) und der GUID finden Sie unter Header für IAM-Tokens.

  • to und from sind Abfrageparameter, die Sie definieren müssen, um den Zeitraum zu konfigurieren, über den Sie Informationen zu Alerts benötigen.

Weitere Informationen zum Antwortformat finden Sie unter Alertschema.

Alertschema: Anforderungshauptteil

{
  "alerts": [
    {
      "alert": {
        "version": null,
        "name": "",
        "description": null,
        "teamId": null,
        "enabled": false,
        "filter": null,
        "type": "",
        "condition": "",
        "timespan": 600000000,
        "notificationChannelIds": [],
        "reNotify": false,
        "reNotifyMinutes": 30,
        "segmentBy": [],
        "segmentCondition": {
          "type": ""
        },
        "severityLabel": ""
      }
    }
  ]
}

Alertschema: Antwortteil

{
  "alerts": [
    {
    "alert": {
      "autoCreated": false,
      "condition": "",
      "createdOn": 1551358413000,
      "enabled": false,
      "id": 23211,
      "modifiedOn": 1551634372000,
      "name": "",
      "filter": "",
      "notificationChannelIds": [],
      "segmentBy": [],
      "segmentCondition": {
        "type": "ANY"
      },
      "notificationCount": 60,
      "rateOfChange": false,
      "reNotify": false,
      "severity": 0,
      "severityLabel": "",
      "teamId": 493,
      "timespan": 60000000,
      "type": "",
      "version": 9
      }
    }
  ]
}

Fehlerantwortcodes

In der folgenden Tabelle sind allgemeine Fehlerantwortcodes aufgeführt:

RC
RC Beschreibung
400 Die Alertkonfiguration ist nicht gültig.
401 Unbefugter Zugriff.
404 Die Alert-ID wird nicht erkannt.
409 Es gibt eine Versionsabweichung.
422 Der Alertname ist nicht gültig. Der Name wird bereits verwendet.

Hauptteilparameter

id (integer)

ID eines Alerts.

condition (string)

Definiert den Schwellenwert, der für den Alert konfiguriert ist. Dieser Parameter ist nur für MANUAL-Alerts erforderlich.

Sie können zum Beispiel eine Konsition wie folgt definieren: avg(timeAvg(uptime)) <= 0

createdOn (integer)

Definiert die Erstellungszeit eines Alerts in Millisekunden.

Dieser Parameter gibt die Unix-Zeitmarke für die Erstellung des Alerts zurück.

description (string)

Dieser Parameter beschreibt den Alert.

Die Beschreibung ist verfügbar, wenn Sie einen Alert im Abschnitt Alerts der Überwachungsbenutzerschnittstelle anzeigen und dieser in Benachrichtigungs-E-Mails eingeschlossen ist.

enabled (boolean)

Definiert den Status eines Alerts.

Dieser Parameter ist standardmäßig auf true gesetzt und der Alert wird bei der Erstellung aktiviert.

filter (string)

Definiert den Geltungsbereich des Alerts durch die Konfiguration von Segmenten.

Wenn dieses Feld leer ist, sind alle Metrikquellen eingeschlossen. Der Bereich ist auf Alles gesetzt.

Zum Beispiel können Sie Filter wie die folgenden definieren:

kubernetes.namespace.name='production'

container.image='nginx'*.

kubernetes.namespace.name='production' and container.image='nginx'*.

name (Zeichenfolge)

Name des Alerts. Muss eindeutig sein.

Der Name identifiziert den Alert im Abschnitt Alerts der Überwachungsbenutzerschnittstelle und wird in Benachrichtigungs-E-Mails eingeschlossen.

modifiedOn (integer)

Definiert den Zeitpunkt der letzten Änderung eines Alerts in Millisekunden.

Dieser Parameter definiert die Unix-Zeitmarke für die letzte Änderung des Alerts.

notificationChannelIds (array)

Listet die Benachrichtigungskanäle auf, die konfiguriert sind, um eine Benachrichtigung zu senden, wenn ein Alert ausgelöst wird.

Gültige Optionen sind EMAIL, PAGER_DUTY, WEBHOOK, VICTOROPS und SLACK.

"notificationChannelIds": [
      "EMAIL",
      "WEBHOOK"
    ]

notificationCount (integer)

Definiert die Anzahl der Benachrichtigungen, die während der letzten zwei Wochen für den Alert gesendet wurden.

reNotify (boolean)

Definiert, ob Sie Benachrichtigungen abrufen möchten, bis die Alertbedingung bestätigt und behoben ist.

Standardmäßig sind Nachverfolgungsbenachrichtigungen nicht aktiviert und das Feld ist auf false gesetzt.

reNotifyMinutes (integer)

Definiert, wie oft Benachrichtigungen über einen nicht aufgelösten Alert empfangen werden sollen.

Sie geben die Anzahl der Minuten an, bis eine Erinnerung gesendet wird.

severity (integer)

Definiert die Prioritätsstufe für den Syslog-codierten Alert.

In der folgenden Tabelle sind die Werte aufgelistet, die festgelegt werden können:

Schweregrad-Werte
Schweregrad Info
0 emergency
1 alert
2 critical
3 error
4 warning
5 notice
6 informational
7 debug

severityLabel (string)

Definiert die Kritikalität eines Alerts. Gültige Werte sind HIGH, MEDIUM, LOW und INFO. Ein kleinerer Wert bedeutet eine höhere Prioritätsstufe.

In der folgenden Tabelle wird der Wertigkeitsstatus angegeben, der abhängig von dem Parameterwert für die Priorität festgelegt werden muss:

Werte für den Schweregrad
Schweregrad Wertigkeitsstatus
0 HIGH
1 HIGH
2 MEDIUM
3 MEDIUM
4 LOW
5 LOW
6 INFO
7 INFO

segmentBy (array of strings)

Definiert zusätzliche Segmentierungskriterien.

Zum Beispiel können Sie einen CPU-Alert nach ['host.mac', 'proc.name'] segmentieren, sodass der Alert jeden Prozess in jedem System melden kann, für den Sie Daten in der Überwachungsinstanz empfangen.

segmentCondition (string)

Definiert, wann der Alert für die einzelnen überwachten Entitäten ausgelöst wird, die im Parameter segmentBy angegeben sind. Dieser Parameter ist nur für MANUAL-Alerts erforderlich.

Folgende Werte sind gültig:

  • ANY: Der Alert wird ausgelöst, wenn mindestens eine der überwachten Entitäten die Bedingung erfüllt.
  • ALL: Der Alert wird ausgelöst, wenn alle überwachten Entitäten die Bedingung erfüllen.

teamId (string)

Definiert die GUID des Teams, das Eigner des Alerts ist.

type (Zeichenfolge)

Definiert den Typ des Alerts. Gültige Werte sind MANUAL, BASELINE und HOST_COMPARISON.

Setzen Sie diese Einstellung auf MANUAL für Alerts, die Sie steuern möchten, wenn eine Benachrichtigung gesendet wird. Sie müssen den Schwellenwert definieren, der bestimmt, wann der Alert ausgelöst wird.

Legen Sie für Alerts, die benachrichtigt werden sollen, wenn unerwartete Metrikwerte erkannt werden, die Einstellung BASELINE fest. Neue Metrikdaten werden mit den Metrikwerten verglichen, die im Zeitverlauf erfasst werden.

Geben Sie HOST_COMPARISON für Alerts an, die benachrichtigt werden sollen, wenn 1 Host in einer Gruppe Metrikwerte meldet, die sich von denen der anderen Hosts in der Gruppe unterscheiden.

timespan (integer)

Mindestzeitintervall in Mikrosekunden, für das die Alertbedingung erfüllt sein muss, bevor der Alert ausgelöst wird.

Der Mindestwert beträgt 60.000.000 Mikrosekunden, also eine Minute.

Der Wert für diesen Parameter muss ein Vielfaches von 60.000.000 Mikrosekunden sein.

version (integer)

Version eines Alerts.

Die Version ändert sich jedes Mal, wenn Sie einen Alert aktualisieren.

Die Version wird für optimistisches Sperren verwendet.

Abfrageparameter

alertId (integer)

ID eines Alerts.

from (long)

Definiert die Startzeitmarke (in Mikrosekunden), die verwendet wird, wenn Sie Informationen zu definierten Alerts anfordern.

to (long)

Definiert die Endzeitmarke (in Mikrosekunden), die verwendet wird, wenn Sie Informationen zu definierten Alerts anfordern.