IBM Cloud API Docs

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.
  • A Dashboards API that you can use to create, read, update, delete, search, and migrate Grafana 4 dashboards.

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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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.

Request Body

Required*
AlertRule

The definition for this rule

Examples:
View

Response

Status Code

  • 200

    New rule was created successfully

  • 400

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

  • 403

    User is forbidden from performing this request

  • 404

    The rule was not found

  • 409

    A rule with the same name already exists

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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.

Request Body

Required*
AlertRuleUpdate

The definition for this rule

Examples:
View

Response

Status Code

  • 200

    New rule was created successfully

  • 400

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

  • 403

    User is forbidden from performing this request

  • 404

    The rule was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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
    Required*
    string

    The name of the alert rule to be retrieved

Response

Response Body

AlertRule

Status Code

  • 200

    Contents of the alert rule for the named alert

  • 404

    The rule was not found

  • default

    Unexpected service error

Example responses
  • {
  "expression": "expression",
  "comparison": "above",
  "name": "name",
  "allow_no_data": true,
  "description": "description",
  "from": "from",
  "until": "until",
  "dashboard_url": "dashboard_url",
  "enabled": true,
  "notifications": [
    "notifications",
    "notifications"
  ],
  "comparison_scope": "last",
  "frequency": "frequency"
}

Remove an alert rule

Remove the named alert rule

DELETE /alert/rule/{name}

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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
    Required*
    string

    The name of the alert rule to be deleted

Response

Status Code

  • 200

    Success

  • 404

    The rule was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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

Response Body

AlertRule[]

Status Code

  • 200

    Contents of the alert rule for the named alert.

  • 404

    The rule was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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.

Request Body

Required*
AlertNotification

The definition for this notification.

Examples:
View

Response

Status Code

  • 200

    New alert notification was created successfully

  • 400

    Bad request. Invalid notification definition.

  • 403

    User is forbidden from performing this request

  • 404

    The notification was not found

  • 409

    A notification with the same name already exists

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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.

Request Body

Required*
AlertNotificationUpdate

The definition for this notification.

Examples:
View

Response

Status Code

  • 200

    New alert notification was created successfully

  • 400

    Bad request. Invalid notification definition.

  • 403

    User is forbidden from performing this request

  • 404

    The notification was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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
    Required*
    string

    The name of the alert notification to be retrieved

Response

Response Body

AlertNotification

Status Code

  • 200

    Contents of the alert notification

  • 404

    The notification was not found

  • default

    Unexpected service error

Example responses
  • {
  "name": "emailBob",
  "description": "email Bob when there's a problem",
  "type": "Email",
  "detail": "bob@ibm.com"
}

Remove an alert notification

Remove the named alert notification

DELETE /alert/notification/{name}

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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
    Required*
    string

    The name of the alert notification to be deleted

Response

Status Code

  • 200

    Success

  • 404

    The notification was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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

Response Body

AlertNotification[]

Status Code

  • 200

    Contents of the alert rule for the named alert

  • 404

    The notification was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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
    Required*
    string

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

Response

Status Code

  • 200

    Alert was successfully sent

  • 400

    Bad request. Invalid notification definition.

  • 403

    User is forbidden from performing this request

  • 404

    The notification was not found

  • default

    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

  • X-Auth-User-Token
    Required*
    string

    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

  • X-Auth-Scope-Id
    string

    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

  • rule
    string

    The rule name by which to filter the history results

Response

Response Body

AlertHistory[]

Status Code

  • 200

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

  • 404

    The history for the given rule/notification was not found

  • default

    Unexpected service error

No Sample Response

This method does not specify any sample responses.