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
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
oruaa
, whereapikey
identifies that the token is an apikeyiam
identifies that the token specified is an IAM generated tokenuaa
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 spaceThis 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
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
oruaa
, whereapikey
identifies that the token is an apikeyiam
identifies that the token specified is an IAM generated tokenuaa
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
Metric name.
Example:
myapp.login.attempts
Value of the metric.
Example:
21.09
UNIX timestamp i.e seconds since the UNIX epoch.
Example:
1496060972
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
oruaa
, whereapikey
identifies that the token is an apikeyiam
identifies that the token specified is an IAM generated tokenuaa
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 spaceThis 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
{ "metrics": [ { "path": "myapp.login.attempts", "name": "attempts", "is_leaf": 1 }, { "path": "myapp.login.attempts", "name": "attempts", "is_leaf": 1 } ] }
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
oruaa
, whereapikey
identifies that the token is an apikeyiam
identifies that the token specified is an IAM generated tokenuaa
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 spaceThis 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 hierarchymetric-service.*
If the pattern resolves to a node, then all metrics under the hierachy are deleted.