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

Add a new dashboard

POST /v1/metrics/dashboard
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Dashboard object

Example:
Response

Status Code

  • New dashboard created

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

  • Dashboard already exists

No Sample Response

This method does not specify any sample responses.

Update an existing dashboard.

PUT /v1/metrics/dashboard
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Dashboard object

Example:
Response

Status Code

  • Dashboard updated

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

  • Dashboard with a newer version already exists

No Sample Response

This method does not specify any sample responses.

Retrieve a dashboard

GET /v1/metrics/dashboard/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using 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 of dashboard to be deleted

Response

Status Code

  • Dashboard with specified name returned

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

  • Dashboard not found

Example responses

Delete a dashboard

DELETE /v1/metrics/dashboard/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using 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 of the dashboard to be deleted

Response

Status Code

  • Dashboard deleted

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

  • Dashboard not found

No Sample Response

This method does not specify any sample responses.

List the available dashboards

GET /v1/metrics/dashboards
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using 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

  • Available dashboard returned

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

No Sample Response

This method does not specify any sample responses.

Search the available dashboards

GET /v1/metrics/dashboard/search/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using 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 of the dashboard

Query Parameters

  • name of dashboard being searched

  • Tag of dashboard being searched

  • Flag indicating if only starred Dashboards should be returned

Response

Status Code

  • Available dashboard returned

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

No Sample Response

This method does not specify any sample responses.

Migrate the specified dashboard from Grafana 1.9 to Grafana 4

POST /v1/metrics/dashboard/migrate/{name}
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using 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 of the dashboard to be migrated

Query Parameters

  • version of Grafana the dashboard is being migrated from. Only "grafana1" is supported for now

  • version of Grafana the dashboard is being migrated to. Only "grafana4" is supported for now

  • Flag indicating if the API should replace the existing dashboard, if found. Default is set to "false"

Response

Status Code

  • Migrate result returned

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

  • A Grafana 1 dashboard with the name specified does not exist

Example responses

Migrate all dashboards from Grafana 1.9 to Grafana 4

POST /v1/metrics/dashboards/migrate
Request

Custom Headers

  • The UAA token or IAM token. The token or apikey must be prefixed with one of the following 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

  • The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Query Parameters

  • version of Grafana the dashboard is being migrated from. Only "grafana1" is supported for now

  • version of Grafana the dashboard is being migrated to. Only "grafana4" is supported for now

  • Flag indicating if the API should replace the existing dashboard, if found. Default is set to "false"

Response

Status Code

  • Migrate results returned

  • Some errors were encountered in migrating all the dashboards. Check the message sections of the response body

  • X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • User is forbidden from performing this request

No Sample Response

This method does not specify any sample responses.