Introduction
IBM Cloud® Monitoring is a cloud-native, and container-intelligence management system that you can include as part of your IBM Cloud architecture. Use it to gain operational visibility into the performance and health of your applications, services, and platforms. It offers administrators, DevOps teams and developers full stack telemetry with advanced features to monitor and troubleshoot, define alerts, and design custom dashboards. For details about using IBM Cloud Monitoring, see the IBM Cloud docs.
You can use the Monitoring API to manage dashboards, alerts, and teams. For more information, see the following documentation:
You can use any of the following methods to manage the Monitoring service:
- Python Client: You can use the Python client to manage the Monitoring service. The client is also known as the sdcclient. For more information, see Using the Python client.
- cURL: You can use cURL, a command line tool, from a terminal to manage the Monitoring service by using URL syntax. For more information, see Using cURL.
Use the following syntax from a terminal to run a cURL command:
curl -X <METHOD> <ENDPOINT>/<API_URL> <-H HEADERS,> [-d DATA]
Where
<METHOD>
indicates the type of REST API call that you want to make.<ENDPOINT>
indicates the endpoint where the monitoring instance is available. For more information, see Monitoring endpoints. For example, the endpoint for an instance that is available in us-south is the following:https://us-south.monitoring.cloud.ibm.com
<API_URL>
For more information about API URLs, see Monitoring REST APIs.HEADERS
add additional information such as information to authenticate with the IBM Cloud Monitoring service.DATA
allows you to pass additional information that might be required.
The code examples on this tab use the client library that is provided for Python.
import os
import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), '..'))
from sdcclient import IbmAuthHelper, SdMonitorClient
# Parse arguments.
def usage():
print('usage: %s <ENDPOINT_URL> <API_KEY> <INSTANCE_GUID>' % sys.argv[0])
print('ENDPOINT_URL: IBM Cloud endpoint URL (e.g. https://us-south.monitoring.cloud.ibm.com')
print('API_KEY: IBM Cloud IAM API key. This key is used to retrieve an IAM access token.')
print('INSTANCE_GUID: GUID of an IBM Cloud Monitoring instance.')
sys.exit(1)
if len(sys.argv) != 4:
usage()
URL = sys.argv[1]
APIKEY = sys.argv[2]
GUID = sys.argv[3]
# Instantiate the client
ibm_headers = IbmAuthHelper.get_headers(URL, APIKEY, GUID)
sdclient = SdMonitorClient(sdc_url=URL, custom_headers=ibm_headers)
Endpoint URL
You can use public and private endpoints. To find out about the available endpoints, see REST API endpoints.
The endpoint for the IBM Cloud Monitoring API is in the format: https://cloud.ibm.com.monitoring.cloud.ibm.com/api
For example, the API endpoint for Dallas is: https://us-south.monitoring.cloud.ibm.com/api
Example request to a Dallas endpoint:
curl -X GET https://us-south.monitoring.cloud.ibm.com/api/alerts/<ALERT_ID> -H "Authorization: $AUTH_TOKEN" -H "IBMInstanceID: $GUID" -H "TeamID: $TEAM_ID" -H "content-type: application/json"
Replace <ALERT_ID>
, AUTH_TOKEN
, GUID
and TEAM_ID
in this example with the values for your particular API call.
Example request to a Dallas endpoint
import os
import sys
sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])), '..'))
from sdcclient import IbmAuthHelper, SdMonitorClient
# Parse arguments.
def usage():
print('usage: %s <ENDPOINT_URL> <API_KEY> <INSTANCE_GUID>' % sys.argv[0])
print('ENDPOINT_URL: IBM Cloud endpoint URL (e.g. https://us-south.monitoring.cloud.ibm.com')
print('API_KEY: IBM Cloud IAM API key. This key is used to retrieve an IAM access token.')
print('INSTANCE_GUID: GUID of an IBM Cloud Monitoring instance.')
sys.exit(1)
if len(sys.argv) != 4:
usage()
URL = sys.argv[1]
APIKEY = sys.argv[2]
GUID = sys.argv[3]
# Instantiate the client
ibm_headers = IbmAuthHelper.get_headers(URL, APIKEY, GUID)
sdclient = SdMonitorClient(sdc_url=URL, custom_headers=ibm_headers)
Authentication
Access to IBM Cloud Monitoring is controlled by using IBM Cloud Identity and Access Management (IAM), which provides a unified approach to managing user identities and access control across your IBM Cloud services and applications.
This API requires IBM Cloud Identity and Access Management (IAM) authentication. You must pass an IAM token in the Authorization header of the request. You can retrieve your IAM access token, which is prefixed with Bearer
, by running the ibmcloud iam oauth-tokens command. You must also set the Account header to the unique ID for your IBM Cloud account. You can retrieve your Account ID by running the ibmcloud account show command.
To call each method, you must be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Managing access for IBM Cloud Monitoring.
In a cURL command, add the following headers to authenticate with the IBM Cloud Monitoring service by using an IAM token:
-H "Authorization: $AUTH_TOKEN"
-H "IBMInstanceID: $GUID"
-H "TeamID: $TEAM_ID"
Where
-
IBMInstanceID
indicates the GUID of the IBM Cloud Monitoring instance that you want to target with the cURL command.To get the GUID of the monitoring instance, run the following command:
ibmcloud resource service-instance <NAME> --output json | jq -r '.[].guid'
-
Authorization
indicates the IAM token that is used to authenticate with the IBM Cloud Monitoring service instance.To get the IAM
AUTH_TOKEN
token, run the following command:ibmcloud iam oauth-tokens | awk '{print $4}'
For more information, see Getting the IAM API token.
-
TeamID
indicates the GUID of a team.To get the GUID, see Getting the ID of a team.
Authentication when using Python
To use IBM Cloud IAM authentication with the Python client, you must specify an endpoint, an API key, and the GUID from your IBM Cloud Monitoring instance.
Complete the following steps from a terminal:
-
Get the GUID of your IBM Cloud Monitoring instance. Run the following command:
ibmcloud resource service-instance <NAME> --output json | jq -r '.[].guid'
-
Get the API key. Run the following command to generate a user API key:
ibmcloud iam api-key-create KEY_NAME
-
Get the endpoint for the region where the monitoring instance is available.
-
Add the following entries to your Python script:
from sdcclient import IbmAuthHelper, SdMonitorClient URL = <ENDPOINT> # For example: URL = 'https://us-south.monitoring.cloud.ibm.com' APIKEY = <IAM_APIKEY> GUID = <GUID> ibm_headers = IbmAuthHelper.get_headers(URL, APIKEY, GUID) sdclient = SdMonitorClient(sdc_url=URL, custom_headers=ibm_headers)
Where
<ENDPOINT>
must be replaced with the endpoint where the monitoring instance is available.<IAM_APIKEY>
must be replaced with a valid IAM API key. Learn more.<GUID>
must be replaced with the GUID of the monitoring instance that you obtain in the previous step.
You can now use the sdclient to perform actions that will be authenticated by using IAM.
If you get the error 400 Client Error: Bad Request for url: https://iam.cloud.ibm.com/identity/token
, check the API key. The value that you are passing is not valid.
Auditing
You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method. For more information about how to track IBM Cloud Monitoring activity, see Auditing the events for IBM Cloud Monitoring.
Error handling
The IBM Cloud Monitoring service uses standard HTTP response codes to indicate whether a method completed successfully.
- A
200
response always indicates success. - A
400
type response indicates a failure. - A
500
type response usually indicates an internal system error.
HTTP Error Code | Description |
---|---|
200 |
Success |
201 |
Success E.g. Dashboard successfully created |
400 |
Bad Request |
401 |
Unauthorized |
403 |
Forbidden |
404 |
Not Found E.g. Dashboard V3 not active |
422 |
Validation error, reason stated in the response body |
500 |
Internal Server Error |
Methods
List dashboards
Use this method to list all V2 and V3 dashboards that are accessible by the user.
GET /api/v3/dashboards
Request
Query Parameters
Allowable values: [
true
]Only auto created dashboards
Default:
false
Only dashboards with the given permission
Only shared dashboards
Default:
false
Return dashboards for the given team id
curl -X GET https://<region>.monitoring.cloud.ibm.com/api/v3/dashboards -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
ok, res = sdclient.get_dashboards()
Transfer ownership
Use this method to transfer the ownership of a set of dashboards to another user.
POST /api/v3/dashboards/transfer
Request
request
The dashboard ids to be transferred
The current dashboard owner user id
Only simulate the transfer, resolving all sharing
The new dashboard owner user id
curl -X POST https://<region>.monitoring.cloud.ibm.com/api/v3/dashboards/transfer -H "Authorization: Bearer <IAM_token>" -H "IBMInstanceID: $GUID" -H "content-type: application/json" -d @dashboard.json
Get dashboard details
Use this method to get information about a dashboard.
GET /api/v3/dashboards/{id}
Request
Path Parameters
id
dashboardWrapper
curl -X PUT https://<region>.monitoring.cloud.ibm.com/api/v3/dashboards/{id} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json' -d @dashboard.json
res = sdclient.update_dashboard(DASHBOARD_ID)
Response
Status Code
Dashboard successfully updated
Created
Unauthorized
The user has no permissions to update the given dashboard
Dashboard not found or V3 is not active for the customer
Dashboard V3 version not matching the current stored version
Validation error, reason stated in the response body
No Sample Response
Set dashboard as favorite
Use this method to set a dashboard as favorite
PATCH /api/v3/dashboards/{id}
Update multiple alerts
Use this method to create or update Prometheus Alert Rules with the given group and alert name in a batch manner. Rules are updated only if found with the same group name with either the same 'alert name' or the same 'annotations.id'. Otherwise a new alert is created
PUT /prometheus/api/v1/rules/batch
Request
Custom Headers
Allowable values: [
application/json
,application/yaml
]
prometheusGroupedRules
curl -X PUT https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/batch -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.update_alert(alert)
Get alert by ID
Use this method to get a given Prometheus Alert Rule by id.
GET /prometheus/api/v1/rules/{alertId}
Request
Path Parameters
alertId
curl -X GET https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{alertId} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.get_alert(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
OK
Unauthorized
Forbidden
No alert rule found for the given id
No Sample Response
Update alert by ID
Use this method to update a Prometheus Alert Rule with the given id.
PUT /prometheus/api/v1/rules/{alertId}
Request
Custom Headers
Allowable values: [
application/json
,application/yaml
]
Path Parameters
alertId
prometheusAlertRule
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
curl -X PUT https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{alertId} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.update_alert(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
Alert Rule updated successfully
Created
Unauthorized
Forbidden
No alert rule found for the given id
No Sample Response
Delete alert by ID
Use this method to delete a Prometheus Alert Rule with the given id.
DELETE /prometheus/api/v1/rules/{alertId}
Request
Path Parameters
alertId
curl -X DELETE https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{alertId} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.delete_alert(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
Alert Rule deleted successfully
No Content
Unauthorized
Forbidden
No alert rule found for the given id
No Sample Response
List alerts in a group
Use this method to get a given Prometheus group with its rules
GET /prometheus/api/v1/rules/{groupName}
Create alert in a group
Use this method to create a Prometheus Alert Rule on the specified group name.
POST /prometheus/api/v1/rules/{groupName}
Request
Custom Headers
Allowable values: [
application/json
,application/yaml
]
Path Parameters
groupName
prometheusAlertRule
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
curl -X POST https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{groupName} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.create_alert(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
OK
Alert Rule created successfully
Unauthorized
Forbidden
Not Found
No Sample Response
Delete alert in a group
Use this method to delete all Prometheus Alert Rule with the given group name.
DELETE /prometheus/api/v1/rules/{groupName}
Get alert by group and name
Use this method to get a given Prometheus Alert Rule by group and alert name.
GET /prometheus/api/v1/rules/{groupName}/{alertName}
Request
Path Parameters
alertName
groupName
curl -X GET https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{groupName}/{alertName} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.get_alerts(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
OK
Unauthorized
Forbidden
No alert rule found for the given group/alert name combination
No Sample Response
Update alert by group and name
Use this method to update a Prometheus Alert Rule with the given group and alert name.
PUT /prometheus/api/v1/rules/{groupName}/{alertName}
Request
Custom Headers
Allowable values: [
application/json
,application/yaml
]
Path Parameters
alertName
groupName
prometheusAlertRule
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
curl -X PUT https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{groupName}/{alertName} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.update_alert(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
Alert Rule updated successfully
Created
Unauthorized
Forbidden
No alert rule found for the given group/alert name
No Sample Response
Delete alert by group and name
Use this method to delete a Prometheus Alert Rule with the given group and alert name.
DELETE /prometheus/api/v1/rules/{groupName}/{alertName}
Request
Path Parameters
alertName
groupName
curl -X DELETE https://<region>.monitoring.cloud.ibm.com/prometheus/api/v1/rules/{groupName}/{alertName} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.delete_alert(alert)
Response
The Alert Rule name
An optional map of 'name:value' annotations to be associated with the rule
The PromQL expression to be evaluated
Time duration expression for the alert (e.g. '5m')
A map of 'name:value' labels to be associated with the rule. 'severity' item must be present
Status Code
Alert Rule deleted successfully
No Content
Unauthorized
Forbidden
No alert rule found for the given group/alert name
No Sample Response
Get the list of teams
Use this method to get the list of teams that are defined in a monitoring instance.
GET /api/team
Request
team
Allowable values: [
ROLE_TEAM_NONE
,ROLE_TEAM_READ
,ROLE_TEAM_SERVICE_MANAGER
,ROLE_TEAM_STANDARD
,ROLE_TEAM_EDIT
,ROLE_TEAM_MANAGER
]Allowable values: [
SYSDIG
,LDAP
]Allowable values: [
SDC
,SDS
]Allowable values: [
host
,container
]
curl -X POST https://<region>.monitoring.cloud.ibm.com/api/team -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.create_team(team_name)
Get infrastructure
Use this method to get information about the infrastructure of a team.
GET /api/team/infrastructure
Request
Path Parameters
teamId
teamUpdates
Allowable values: [
ROLE_TEAM_NONE
,ROLE_TEAM_READ
,ROLE_TEAM_SERVICE_MANAGER
,ROLE_TEAM_STANDARD
,ROLE_TEAM_EDIT
,ROLE_TEAM_MANAGER
]Allowable values: [
SYSDIG
,LDAP
]Allowable values: [
SDC
,SDS
]Allowable values: [
host
,container
]
curl -X PUT https://<region>.monitoring.cloud.ibm.com/api/team/{teamId} -H 'Authorization: Bearer <IAM_token>' -H 'IBMInstanceID: $GUID' -H 'TeamID: $TEAM_ID' -H 'content-type: application/json'
res = sdclient.update_team(teamA)
List users in a team
Use this method to get the list of users that belong to a team.
GET /api/team/{teamId}/users