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

Retrieve metrics from a space

Use this endpoint to retrieve metrics from a space. You must specify the path of the metric from the root of the metrics tree to the metric, separating each step by ., in the Target parameter. You can optionally apply functions to the metric. A maximum of 5 targets can be specified per request.

GET /v1/metrics
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

  • Path that identifies one or more metrics, optionally with functions applied to them. Graphite 0.9.15 functions are supported. A maximum of five targets can be specified on the URL. Paths also support the following wildcards, which allows you to identify more than one metric in a single path: asterisk, characters in square brackets, value lists

  • The relative or absolute time period to begin at. Defaults to 24h ago.

    Default: -24h

  • The relative or absolute time period to end at. Defaults to current time now.

    Default: now

Response

Status Code

  • Success. JSON example

     [
       {
         "target": "myapp.login.attempts",
         "datapoints": [
          [1.0, 1311836008],
          [2.0, 1311836068],
          [3.0, 1311836128],
          [5.0, 1311836188],
          [6.0, 1311836248]
         ]
       }
    ]
    
  • Bad request. An required header or parameter is missing

  • Subject is not authorized

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Send metrics to a space

Use this endpoint to send metrics into a space. If the timestamp is not provided, then the time of ingestion will be taken as the timestamp.

POST /v1/metrics
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.

List of metrics and their associated values

Response

Status Code

  • Success

  • Bad request. An required header or parameter is missing

  • Subject is not authorized

  • Unexpected service error

No Sample Response

This method does not specify any sample responses.

Retrieve a list of metrics from a space

Use this endpoint to list the metrics that are being collected in a space.

GET /v1/metrics/list
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 metric query path that is used to search.

    Default value is * that specifies to start at the root level for the space domain.

Response

Status Code

  • Success

  • Bad request. An required header or parameter is missing

  • Subject is not authorized

  • Unexpected service error

Example responses

Delete metrics

Use this endpoint to delete metrics. Finds metrics under a given path in the space based on the query pattern, and deletes them. Once deleted, the metrics cannot be recovered.

DELETE /v1/metrics/list
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 metric query path to search. For example, query=metric-service.* will list all nodes and leafs that exist under the hierarchy metric-service.*

    If the pattern resolves to a node, then all metrics under the hierachy are deleted.

Response

Status Code

  • Success

  • Bad request. An required header or parameter is missing

  • Subject is not authorized

  • No metrics matching the provided query pattern was found

  • Unexpected service error

Example responses