Gerenciando alertas usando a API de Alertas

Você pode gerenciar alertas em uma instância IBM Cloud Monitoring usando a API Monitoring API.

Para saber como usar cURL, consulte Comando cURL.

Obter detalhes sobre um alerta do usuário

É possível usar o comando cURL a seguir para obter informações sobre um 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"

em que

  • <REST_API_ENDPOINT> indica o ponto de extremidade visado pela chamada à API REST. Para obter mais informações, consulte MonitoringTerminais da API de REST. Por exemplo, o terminal público para uma instância que está disponível em us-south é o seguinte: https://us-south.monitoring.cloud.ibm.com/api

  • É possível transmitir vários cabeçalhos usando -H.

    Authorization e IBMInstanceID são cabeçalhos que são necessários para autenticação.

    TeamID é opcional. Ao especificar esse cabeçalho, é possível limitar a solicitação aos dados e aos recursos disponíveis para a equipe especificada.

    Para obter um AUTH_TOKEN e o GUID, consulte Cabeçalhos para tokens do IAM.

  • <ALERT_ID> define o ID do alerta que você deseja modificar.

Por exemplo, o corpo de resposta para um alerta é o seguinte:

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

Criar um alerta

É possível usar o comando cURL a seguir para criar um 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

em que

  • <REST_API_ENDPOINT> indica o ponto de extremidade visado pela chamada à API REST. Para obter mais informações, consulte MonitoringTerminais da API de REST. Por exemplo, o terminal público para uma instância que está disponível em us-south é o seguinte: https://us-south.monitoring.cloud.ibm.com/api

  • É possível transmitir vários cabeçalhos usando -H.

    Authorization e IBMInstanceID são cabeçalhos que são necessários para autenticação.

    TeamID é opcional. Ao especificar esse cabeçalho, é possível limitar a solicitação aos dados e aos recursos disponíveis para a equipe especificada.

    Para obter um AUTH_TOKEN e o GUID, consulte Cabeçalhos para tokens do IAM.

  • É possível transmitir dados para criar o alerta no arquivo alert.json usando -d.

    Ao criar um alerta, inclua os parâmetros a seguir: type, name, severity, timespan, condition, segmentby, segmentConditionn, filter, notificationChannelIds, enabled

    Para obter mais informações, consulte Esquema de alerta.

A amostra a seguir mostra os parâmetros do corpo da solicitação que podem ser configurados para criar um 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"
  }
}

Atualizar um alerta

Para atualizar um alerta existente, é necessário o ID desse alerta.

É possível usar o comando cURL a seguir para atualizar um 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

em que

  • <REST_API_ENDPOINT> indica o ponto de extremidade visado pela chamada à API REST. Para obter mais informações, consulte MonitoringTerminais da API de REST. Por exemplo, o terminal público para uma instância que está disponível em us-south é o seguinte: https://us-south.monitoring.cloud.ibm.com/api

  • É possível transmitir vários cabeçalhos usando -H.

    Authorization e IBMInstanceID são cabeçalhos que são necessários para autenticação.

    TeamID é opcional. Ao especificar esse cabeçalho, é possível limitar a solicitação aos dados e aos recursos disponíveis para a equipe especificada.

    Para obter um AUTH_TOKEN e o GUID, consulte Cabeçalhos para tokens do IAM.

  • <ALERT_ID> define o ID do alerta que você deseja modificar.

  • É possível transmitir dados para criar o alerta no arquivo alert.json usando -d.

    Para obter mais informações, consulte Esquema de alerta.

A amostra a seguir mostra os parâmetros do corpo da solicitação que podem ser configurados para atualizar um 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
      ]
    }
}

Excluir um alerta

Para excluir um alerta existente, é necessário o ID desse alerta.

É possível usar o comando cURL a seguir para excluir um 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"

em que

  • <REST_API_ENDPOINT> indica o ponto de extremidade visado pela chamada à API REST. Para obter mais informações, consulte MonitoringTerminais da API de REST. Por exemplo, o terminal público para uma instância que está disponível em us-south é o seguinte: https://us-south.monitoring.cloud.ibm.com/api

  • É possível transmitir vários cabeçalhos usando -H.

    Authorization e IBMInstanceID são cabeçalhos que são necessários para autenticação.

    TeamID é opcional. Ao especificar esse cabeçalho, é possível limitar a solicitação aos dados e aos recursos disponíveis para a equipe especificada.

    Para obter um AUTH_TOKEN e o GUID, consulte Cabeçalhos para tokens do IAM.

  • <ALERT_ID> define o ID do alerta que você deseja excluir.

Obter todos os alertas do usuário

É possível usar o comando cURL a seguir para obter informações sobre todos os alertas:

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

em que

  • <REST_API_ENDPOINT> indica o ponto de extremidade visado pela chamada à API REST. Para obter mais informações, consulte MonitoringTerminais da API de REST. Por exemplo, o terminal público para uma instância que está disponível em us-south é o seguinte: https://us-south.monitoring.cloud.ibm.com/api

  • É possível transmitir vários cabeçalhos usando -H.

    Authorization e IBMInstanceID são cabeçalhos que são necessários para autenticação. Para obter um AUTH_TOKEN e o GUID, consulte Cabeçalhos para tokens do IAM.

  • to e from são parâmetros de consulta que devem ser definidos para configurar o período de tempo para o qual você deseja informações sobre os alertas.

Para obter mais informações sobre o formato de resposta, consulte Esquema de alerta.

Esquema de alertas: corpo da solicitação

{
  "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: corpo de resposta

{
  "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 resposta de erro

A tabela a seguir mostra códigos de resposta de erro comuns:

RC
RC Descrição
400 A configuração de alerta não é válida.
401 Acesso não-autorizado.
404 O ID de alerta não é reconhecido.
409 Há uma incompatibilidade de versão.
422 O nome do alerta não é válido. O nome já é usado.

Parâmetros do corpo

id (número inteiro)

ID de um alerta.

condition (sequência)

Define o limite que está configurado para o alerta. Esse parâmetro é necessário para alertas MANUAL apenas.

Por exemplo, você pode definir uma condição da seguinte forma: avg(timeAvg(uptime)) <= 0

createdOn (número inteiro)

Define o tempo de criação de um alerta em milissegundos.

Esse parâmetro retorna o registro de data e hora do Unix de quando o alerta foi criado.

description (sequência)

Esse parâmetro descreve o alerta.

A descrição está disponível ao visualizar um alerta na seção Alertas da IU de monitoramento e está incluída em e-mails de notificação.

enabled (booleano)

Define o status de um alerta.

Por padrão, esse parâmetro é configurado como true e o alerta é ativado quando ele é criado.

filter (sequência)

Define o escopo do alerta configurando segmentos.

Quando esse campo estiver vazio, todas as origens de métrica serão incluídas. O escopo é configurado como Tudo.

Por exemplo, é possível definir filtros como os seguintes:

kubernetes.namespace.name='production'

container.image='nginx'*.

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

name (sequência)

Nome do alerta. Deve ser exclusivo.

O nome é usado para identificar o alerta na seção Alertas da IU de monitoramento e está incluído em e-mails de notificação.

modifiedOn (número inteiro)

Define quando um alerta foi modificado pela última vez em milissegundos.

Esse parâmetro define o registro de data e hora do Unix de quando o alerta foi modificado pela última vez.

notificationChannelIds (matriz)

Lista os canais de notificação que são configurados para notificar quando um alerta é acionado.

As opções válidas são EMAIL, PAGER_DUTY, WEBHOOK, VICTOROPS e SLACK.

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

notificationCount (número inteiro)

Define o número de notificações que são enviadas para o alerta durante as últimas duas semanas.

reNotify (booleano)

Define se você deseja receber notificações de acompanhamento até que a condição de alerta seja reconhecida e resolvida.

Por padrão, as notificações de acompanhamento não são ativadas e o campo é configurado como false.

reNotifyMinutes (número inteiro)

Define com que frequência você deseja receber notificações em um alerta que não está resolvido.

Você especifica o número de minutos antes de um lembrete ser enviado.

severity (número inteiro)

Define a severidade do alerta codificado por syslog.

A tabela a seguir lista os valores que podem ser configurados:

Valores de gravidade
Gravidade Informações
0 emergency
1 alert
2 critical
3 error
4 warning
5 notice
6 informational
7 debug

severityLabel (sequência)

Define o grau de severidade de um alerta. Os valores válidos são HIGH, MEDIUM, LOW e INFO. Um valor menor indica uma gravidade maior.

A tabela a seguir mostra o status de severidade que deve ser configurado dependendo do valor do parâmetro de severidade:

Valores de nível de gravidade
Gravidade Status da severidade
0 HIGH
1 HIGH
2 MEDIUM
3 MEDIUM
4 LOW
5 LOW
6 INFO
7 INFO

segmentBy (matriz de sequências)

Define critérios de segmentação adicionais.

Por exemplo, é possível segmentar um alerta de CPU por ['host.mac', 'proc.name'] para que o alerta possa relatar qualquer processo em qualquer máquina para a qual você obtiver dados na instância de monitoramento.

segmentCondition (sequência)

Define quando o alerta é acionado para cada entidade monitorada que é especificada no parâmetro segmentBy. Esse parâmetro é necessário para alertas MANUAL apenas.

Os valores válidos são os seguintes:

  • ANY: o alerta é acionado quando pelo menos uma das entidades monitoradas satisfaz a condição.
  • ALL: o alerta é acionado quando todas as entidades monitoradas satisfazem a condição.

teamId (string)

Define o GUID da equipe que possui o alerta.

tipo (string)

Define o tipo de alerta. Os valores válidos são MANUAL, BASELINE e HOST_COMPARISON.

Configure como MANUAL para alertas que você deseja controlar quando uma notificação é enviada. Deve-se definir o limite que determina quando o alerta é acionado.

Configure como BASELINE para alertas a serem notificados quando valores de métrica inesperados forem detectados. Novos dados de métricas são comparados com os valores métricos que são coletados ao longo do tempo.

Configure como HOST_COMPARISON para alertas que você deseja notificar quando um host em um grupo relata valores de métricas que são diferentes dos outros hosts no grupo.

timespan (número inteiro)

Intervalo de tempo mínimo, em microssegundos, para o qual a condição de alerta deve ser atendida antes que o alerta seja acionado.

O valor mínimo é de 60000000 microssegundos, ou seja, 1 minute.

O valor desse parâmetro deve ser um múltiplo de 60000000 microssegundos.

version (número inteiro)

Versão de um alerta.

A versão muda toda vez que você atualiza um alerta.

A versão é usada para bloqueio otimista.

Parâmetros de consulta

alertId (número inteiro)

ID de um alerta.

from (longo)

Define o registro de data e hora de início, em microssegundos, usado quando você solicita informações sobre alertas definidos.

to (longo)

Define o registro de data e hora final, em microssegundos, usado quando você solicita informações sobre alertas definidos.