Introduction

The IBM® Cloud Monitoring service helps you gain insight into how your apps are performing and consuming resources. You can use the Monitoring service to expand your collection and retention capabilities when working with metrics in the IBM Cloud, and to be able to define rules and alerts that notify you of conditions that require attention.

The Monitoring service provides the following REST APIs:

  • A Metrics API that you can use to send and retrieve data from a space domain.
  • An Alerts API that you can use to configure alerts on metrics.

For details about using the Monitoring service, see the IBM Cloud docs.

Error handling

The Monitoring service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Status code Description Description
200 OK Everything worked as expected.
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed.
404 Not Found The requested resource doesn't exist.
500 Server Error Something went wrong.

Methods

Create an alert rule

Create an alert rule.

A rule describes the metric query to be monitored, the threshold value, and the action to take when the threshold is crossed.

The alert system checks every 5 minutes the rules that are enabled in the space.

By default, a rule is enabled when you create it. However, you can define the rule, and disable it, by configuring the field enable to false.

Also, by default, a rule is created with the field allow_no_datapoints set to true. When no datapoints are available, notifications are not sent unless the rule condition is triggered. If you want to receive a notification to inform that no data was found for rule X, you must set the field allow_no_data to false.

POST /alert/rule
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

The definition for this rule

Example:
Response

Status Code

  • New rule was created successfully

  • Bad request. Invalid rule definition, or notification name doesn't exist

  • User is forbidden from performing this request

  • The rule was not found

  • A rule with the same name already exists

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Update an alert rule

Update some or all of the fields of an alert rule

PUT /alert/rule
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

The definition for this rule

Example:
Response

Status Code

  • New rule was created successfully

  • Bad request. Invalid rule definition, or notification name doesn't exist

  • User is forbidden from performing this request

  • The rule was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Get the details for an alert rule

GET /alert/rule/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • The name of the alert rule to be retrieved

Response

Status Code

  • Contents of the alert rule for the named alert

  • The rule was not found

  • Unexpected service error

Example responses

Remove an alert rule

Remove the named alert rule

DELETE /alert/rule/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • The name of the alert rule to be deleted

Response

Status Code

  • Success

  • The rule was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Retrieve all of the defined rules

This API will return an array of json object that each contain the rule definitions for the current scope and project-id passed in the headers.

GET /alert/rules
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Response

Status Code

  • Contents of the alert rule for the named alert.

  • The rule was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Create an alert notification

Create an alert notification that defines the operation to be executed when an alert rule is raised

POST /alert/notification
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

The definition for this notification.

Example:
Response

Status Code

  • New alert notification was created successfully

  • Bad request. Invalid notification definition.

  • User is forbidden from performing this request

  • The notification was not found

  • A notification with the same name already exists

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Update an alert notification

Update some or all fields in an alert notification

PUT /alert/notification
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

The definition for this notification.

Example:
Response

Status Code

  • New alert notification was created successfully

  • Bad request. Invalid notification definition.

  • User is forbidden from performing this request

  • The notification was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Get the details for an alert notification

GET /alert/notification/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • The name of the alert notification to be retrieved

Response

Status Code

  • Contents of the alert notification

  • The notification was not found

  • Unexpected service error

Example responses

Remove an alert notification

Remove the named alert notification

DELETE /alert/notification/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • The name of the alert notification to be deleted

Response

Status Code

  • Success

  • The notification was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Retrieve all of the defined alert notifications

This API will return an array of json object containing the alert notification definitions for the current scope and project-id passed in the headers.

GET /alert/notifications
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Response

Status Code

  • Contents of the alert rule for the named alert

  • The notification was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Test an alert notification

Triggers a test alert for validating the notification is properly setup

POST /alert/notification/test/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • Name for this alert notification - must be unique for the this scope id

Response

Status Code

  • Alert was successfully sent

  • Bad request. Invalid notification definition.

  • User is forbidden from performing this request

  • The notification was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Get the alert history for this account, org or space

GET /alert/history
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following values: apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • Cloud Foundry space GUID

    The GUID must be prefixed with s- to identify a space

    This header is required if using UAA token authentication.

    If you use IAM authentication, then this header is optional, in which case the account bound to the token will be used as the domain.

Query Parameters

  • The rule name by which to filter the history results

Response

Status Code

  • Array of the most recent alery history for this account, space or organization

  • The history for the given rule/notification was not found

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.