Using the Threshold Management Service API
Use the Threshold Management Service API to to manage the lifecycle of monitoring thresholds from the command line.
About this task
Complete threshold manager tasks such as creating, viewing, updating, and deleting thresholds. Assign resource groups to these thresholds. View a list of all thresholds and resources assignments. View a list of all thresholds that are assigned to a specific resource group.
You can create scripts for automating such tasks as defining thresholds and assigning these thresholds to resource groups.
- Access tokens
-
Use the OpenID Connect (OIDC) protocol to get an access token from the OIDC server on the Cloud APM server. The access token gives you authorised access to the API for running operations until the token expires after 30 minutes.
- Basic authorisation
-
Use a base64 tool to encode your Cloud APM console user ID and password into a single base64 string. The input string format is userId:password, such as apmadmin:apmpass. The output is a string such as: YXBtYWRtaW46YXBtcGFzcw==
Use base64_encoded_string in the authorisation header of every request as shown in the curl command examples.
Note the Cloud APM console user ID must be added to a role with appropriate permissions.
- Return all thresholds or get a specific threshold. You can filter the request with these attributes: label, which corresponds to the threshold name; _appliesToAgentType, which corresponds to the 2-character product code, and _uiThresholdType, which corresponds to the threshold type that is shown in the Threshold Manager and Resource Group editor pages of the Cloud APM console. You can use _offset or _limit when getting thresholds
- Create a threshold or update the definition of an existing threshold. You must include the X-HTTP-Method-Override header and set to PATCH for update request
- Delete a specified threshold
- Return all resource assignments or a specific resource assignment, which shows the thresholds that are assigned to each resource group. You can filter the request with these attributes: resource._id and threshold._id; and use these supported operators are = (equal) and != (not equal)
- Create a resource assignment, which assigns a single threshold to a single resource group
- Delete a resource assignment, which removes a single threshold from a single resource group
Disabling OIDC authentication, which is required before you can enable single sign-on (SSO) between Cloud APM and other IBM® products such as Tivoli® Common Reporting that require LTPA for single sign-on, does not affect the API. The RESTful API continues to use the Cloud APM internal OIDC server, even if OIDC is disabled for single sign-on between the Cloud APM console and other product user interfaces.
Threshold Management Service API requests should be issued by using https to the port 8091 of the Cloud APM server. If you issue a Threshold Management API http request to the port 8090 of the Cloud APM server, then the request is redirected to https and the port 8091.
Procedure
Example
GET /threshold_types/itm_private_situation/thresholds
This command
returns the information for the threshold with the label (name)
My_threshold
.GET /threshold_types/itm_private_situation/thresholds?_filter=label%3DMy_threshold
This
command returns all the thresholds for agent type LZ
, which is the component code
for the Linux® OS agent.GET /threshold_types/itm_private_situation/thresholds?_filter=_appliesToAgentType%3DLZ
This
command has the same output as the previous command but the agent name as it appears in the Cloud APM console is
given.GET /threshold_types/itm_private_situation/thresholds?_filter=_uiThresholdType%3DLinux OS
This
command returns all the resource groups that threshold 123
is assigned
to:GET /resource_assignments?_filter=threshold._id=123
The
following example uses the curl command to create a new threshold.
POST /1.0/thresholdmgmt/threshold_types/itm_private_situation/thresholds
curl -X POST\
https://apm_server:8091/1.0/thresholdmgmt/threshold_types/itm_private_situation/thresholds \
-H 'authorization: Bearer Your_Access_Token' \
-H 'content-type: application/json' \
-d '{
"label": "Your_Linux_Threshold_Name",
"description": "Your Linux Threshold Definition",
"configuration": {
"type": "json",
"payload": {
"formulaElements": [
{
"function": "*MKTIME",
"metricName": "KLZ_CPU.Timestamp",
"operator": "*EQ",
"threshold": "1455767100000",
"timeDelta": {
"operator": "+",
"delta": "3",
"unit": "Hours"
}
}
],
"period": "011500",
"periods": "3",
"severity": "Fatal",
"matchBy": "KLZCPU.CPUID",
"operator": "*OR",
"actions": [
{
"name": "command",
"command": "ps -ef",
"commandFrequency": "Y",
"commandWhen": "Y",
"commandWhere": "N"
}
]
}
}
}'