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.

The following operations are described in API Explorerand in the Example at the end of this topic.
  • 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

Procedure

  1. Complete step 1 to step 9 in the Exploring the APIs topic.
    Step 10 and step 11 provide additional details.
  2. Click USE and select a key, for example, Key1.
    Note: Click Hide to show your client-Id and client secret. Make a note of them because, if you are making API calls with external tools outside of API Explorer, they are needed. Then, click Show to hide them.
  3. Populate all required headers, denoted with an asterisk.
    X-IBM-Service-Location
    * header is the geographic location of your server such as na for North America
    Authorization
    * header is your base64-encoded string of the IBMid and password. When you encode the IBMid and password in the based64-encoder tool, the format must be IBMid:password. For example Basic YXBtYWRtaW46YXBtcGFzcw==.
  4. Scroll to locate and click Test.

Example

This command returns all the thresholds that are registered with the server:
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
Remember: The body of the POST request must contain a JSON object that defines the threshold as shown by the -d parameter. Example: 

curl -X POST\
 https://api.ibm.com/perfmgmt/run/1.0/thresholdmgmt/threshold_types/itm_private_situation/thresholds  \
  -H 'authorization: Basic REPLACE_BASE64_ENCODED_STRING' \
  -H 'content-type: application/json' \
  -H 'x-ibm-client-id: REPLACE_KEY_VALUE' \
  -H 'x-ibm-client-secret: REPLACE_KEY_VALUE' \ 
  -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"
        }
      ]
    }
  }
}'