Gestión de alertas utilizando la API de alertas

Puede gestionar alertas en una instancia IBM Cloud Monitoring mediante la Monitoring API API.

Para aprender a utilizar cURL, consulte mandato cURL.

Obtener detalles sobre una alerta de usuario

Puede utilizar el siguiente mandato cURL para obtener información sobre una alerta:

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"

Donde

<REST_API_ENDPOINT> indica el punto final al que se dirige la llamada a la API REST. Para obtener más información, consulte MonitoringPuntos finales de API REST. Por ejemplo, el punto final público de una instancia que está disponible en us-south es el siguiente: https://us-south.monitoring.cloud.ibm.com/api
Puede pasar varias cabeceras utilizando -H.

Authorization e IBMInstanceID son cabeceras necesarias para la autenticación.

TeamID es opcional. Al especificar esta cabecera, se limita la solicitud a los datos y los recursos disponibles para el equipo especificado.

Para obtener una AUTH_TOKEN y el GUID consulte, Cabeceras para señales IAM.
<ALERT_ID> define el ID de la alerta que quieres modificar.

Por ejemplo, el cuerpo de respuesta para una alerta es como se indica a continuación:

{
  "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
  }
}

Crear una alerta

Puede utilizar el siguiente mandato cURL para crear una alerta:

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

Donde

<REST_API_ENDPOINT> indica el punto final al que se dirige la llamada a la API REST. Para obtener más información, consulte MonitoringPuntos finales de API REST. Por ejemplo, el punto final público de una instancia que está disponible en us-south es el siguiente: https://us-south.monitoring.cloud.ibm.com/api
Puede pasar varias cabeceras utilizando -H.

Authorization e IBMInstanceID son cabeceras necesarias para la autenticación.

TeamID es opcional. Al especificar esta cabecera, se limita la solicitud a los datos y los recursos disponibles para el equipo especificado.

Para obtener una AUTH_TOKEN y el GUID consulte, Cabeceras para señales IAM.
Puede pasar datos para crear la alerta en el archivo alert.json utilizando -d.

Cuando cree una alerta, incluya los siguientes parámetros: type, name, severity, timespan, condition, segmentby, segmentConditionn, filter, notificationChannelIds, enabled

Para obtener más información, consulte Esquema de alertas.

El ejemplo siguiente muestra los parámetros del cuerpo de solicitud que puede establecer para crear una alerta:

{
  "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"
  }
}

Actualizar una alerta

Para actualizar una alerta existente, necesita el ID de la alerta.

Puede utilizar el siguiente mandato cURL para actualizar una alerta:

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

Donde

<REST_API_ENDPOINT> indica el punto final al que se dirige la llamada a la API REST. Para obtener más información, consulte MonitoringPuntos finales de API REST. Por ejemplo, el punto final público de una instancia que está disponible en us-south es el siguiente: https://us-south.monitoring.cloud.ibm.com/api
Puede pasar varias cabeceras utilizando -H.

Authorization e IBMInstanceID son cabeceras necesarias para la autenticación.

TeamID es opcional. Al especificar esta cabecera, se limita la solicitud a los datos y los recursos disponibles para el equipo especificado.

Para obtener una AUTH_TOKEN y el GUID consulte, Cabeceras para señales IAM.
<ALERT_ID> define el ID de la alerta que quieres modificar.
Puede pasar datos para crear la alerta en el archivo alert.json utilizando -d.

Para obtener más información, consulte Esquema de alertas.

El ejemplo siguiente muestra los parámetros del cuerpo de solicitud que puede establecer para actualizar una alerta:

{
  "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
      ]
    }
}

Suprimir una alerta

Para suprimir una alerta existente, necesita el ID de la alerta.

Puede utilizar el siguiente mandato cURL para suprimir una alerta:

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"

Donde

<REST_API_ENDPOINT> indica el punto final al que se dirige la llamada a la API REST. Para obtener más información, consulte MonitoringPuntos finales de API REST. Por ejemplo, el punto final público de una instancia que está disponible en us-south es el siguiente: https://us-south.monitoring.cloud.ibm.com/api
Puede pasar varias cabeceras utilizando -H.

Authorization e IBMInstanceID son cabeceras necesarias para la autenticación.

TeamID es opcional. Al especificar esta cabecera, se limita la solicitud a los datos y los recursos disponibles para el equipo especificado.

Para obtener una AUTH_TOKEN y el GUID consulte, Cabeceras para señales IAM.
<ALERT_ID> define el ID de la alerta que quieres borrar.

Obtener todas las alertas de usuario

Puede utilizar el siguiente mandato cURL para obtener información sobre todas las alertas:

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

Donde

<REST_API_ENDPOINT> indica el punto final al que se dirige la llamada a la API REST. Para obtener más información, consulte MonitoringPuntos finales de API REST. Por ejemplo, el punto final público de una instancia que está disponible en us-south es el siguiente: https://us-south.monitoring.cloud.ibm.com/api
Puede pasar varias cabeceras utilizando -H.

Authorization e IBMInstanceID son cabeceras necesarias para la autenticación. Para obtener una AUTH_TOKEN y el GUID consulte, Cabeceras para señales IAM.
to y from son parámetros de consulta que debe definir para configurar el periodo de tiempo durante el que desea información sobre las alertas.

Para obtener más información sobre el formato de respuesta, consulte Esquema de alertas.

Esquema de alertas: cuerpo de solicitud

{
  "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": ""
      }
    }
  ]
}

Esquema de alertas: cuerpo de respuesta

{
  "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
      }
    }
  ]
}

Códigos de respuesta de error

En la tabla siguiente se muestran códigos de respuesta de error comunes:

RC
RC	Descripción
`400`	La configuración de la alerta no es válida.
`401`	Acceso no autorizado.
`404`	No se reconoce el ID de alerta.
`409`	Hay una discrepancia de versiones.
`422`	El nombre de la alerta no es válido. El nombre ya se utiliza.

Parámetros del cuerpo

id (entero)

ID de una alerta.

condition (serie)

Define el umbral configurado para la alerta. Este parámetro sólo es necesario para las alertas de tipo MANUAL.

Por ejemplo, puede definir una consición de la siguiente manera: avg(timeAvg(uptime)) <= 0

createdOn (entero)

Define la hora de creación de una alerta en milisegundos.

Este parámetro devuelve la indicación de fecha y hora de Unix en que se ha creado la alerta.

description (serie)

Este parámetro describe la alerta.

La descripción está disponible cuando se visualiza una alerta en la sección Alertas de la interfaz de usuario web de supervisión y se incluye en los correos electrónicos de notificación.

enabled (booleano)

Define el estado de una alerta.

De forma predeterminada, este parámetro se establece en true y la alerta está habilitada cuando se crea.

filter (serie)

Define el ámbito de la alerta configurando segmentos.

Cuando este campo está vacío, se incluyen todos los orígenes de métricas. El ámbito se establece en Todo.

Por ejemplo, puede definir filtros como los siguientes:

kubernetes.namespace.name='production'

container.image='nginx'*.

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

name (serie)

Nombre de la alerta. Debe ser exclusivo.

El nombre se utiliza para identificar la alerta en la sección Alertas de la interfaz de usuario de supervisión, y se incluye en los correos electrónicos de notificación.

modifiedOn (entero)

Define cuándo se ha modificado por última vez una alerta en milisegundos.

Este parámetro devuelve la indicación de fecha y hora de Unix en que se ha modificado por última vez la alerta.

notificationChannelIds (matriz)

Lista los canales de notificación que están configurados para notificar cuando se desencadena una alerta.

Las opciones válidas son EMAIL, PAGER_DUTY, WEBHOOK, VICTOROPS, y SLACK.

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

notificationCount (entero)

Define el número de notificaciones que se han enviado para la alerta en las últimas 2 semanas.

reNotify (booleano)

Define si desea obtener notificaciones de seguimiento hasta que se reconozca y resuelva la condición de alerta.

De forma predeterminada, las notificaciones de seguimiento no están habilitadas y el campo está establecido en false.

reNotifyMinutes (entero)

Define la frecuencia con la que desea recibir notificaciones en una alerta que no está resuelta.

Especifique el número de minutos a esperar antes de enviar un recordatorio.

severity (entero)

Define la gravedad de alerta codificada por syslog.

En la tabla siguiente se listan los valores que se pueden establecer:

Valores de gravedad
Gravedad	Información
`0`	`emergency`
`1`	`alert`
`2`	`critical`
`3`	`error`
`4`	`warning`
`5`	`notice`
`6`	`informational`
`7`	`debug`

severityLabel (serie)

Define la gravedad de una alerta. Los valores válidos son HIGH, MEDIUM, LOW e INFO. Un valor menor indica una gravedad más alta.

En la siguiente tabla se muestra el estado de gravedad que debe establecerse según el valor del parámetro de gravedad:

Valores del nivel de gravedad
Gravedad	Estado de gravedad
`0`	`HIGH`
`1`	`HIGH`
`2`	`MEDIUM`
`3`	`MEDIUM`
`4`	`LOW`
`5`	`LOW`
`6`	`INFO`
`7`	`INFO`

segmentBy (matriz de series)

Define criterios de segmentación adicionales.

Por ejemplo, puede segmentar una alerta de CPU por ['host.mac', 'proc.name'] de forma que la alerta pueda informar sobre cualquier proceso en cualquier máquina de la que obtenga datos en la instancia de supervisión.

segmentCondition (serie)

Define cuándo se desencadena la alerta para cada entidad supervisada especificada en el parámetro segmentBy. Este parámetro sólo es necesario para las alertas de tipo MANUAL.

Los valores válidos son los siguientes:

ANY: La alerta se desencadena cuando al menos una de las entidades supervisadas satisface la condición.
ALL: La alerta se desencadena cuando todas las entidades supervisadas cumplen la condición.

teamId (serie)

Define el GUID del equipo propietario de la alerta.

type (serie)

Define el tipo de alerta. Los valores válidos son MANUAL, BASELINE y HOST_COMPARISON.

Establezca MANUAL para las alertas en las que desea controlar cuando se envía una notificación. Debe definir el umbral que determina cuándo se desencadena la alerta.

Establezca BASELINE para las alertas que desea que notifiquen cuando se detecten valores de métricas inesperados. Los nuevos datos de métricas se comparan con los valores de métricas que se han recopilado a lo largo del tiempo.

Establezca HOST_COMPARISON para las alertas que desea que notifiquen cuando 1 host de un grupo informa de valores de métricas diferentes que los otros hosts del grupo.

timespan (entero)

Intervalo de tiempo mínimo, en microsegundos, que se debe cumplir la condición de alerta para que de desencadene la alerta.

El valor mínimo es 60000000 microsegundos, es decir, 1 minuto.

El valor de este parámetro debe ser un múltiplo de 60000000 microsegundos.

version (entero)

Version de una alerta.

La versión cambia cada vez que se actualiza una alerta.

La versión se utiliza para el bloqueo optimista.

Parámetros de consulta

alertId (entero)

ID de una alerta.

from (largo)

Define la indicación de fecha y hora de inicio, en microsegundos, que se utiliza cuando se solicita información sobre las alertas definidas.

to (largo)

Define la indicación de fecha y hora de finalización, en microsegundos, que se utiliza cuando se solicita información sobre las alertas definidas.