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.

In this task you can use either access tokens or basic authorisation in the curl command:
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.

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

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

  1. On the system where the Cloud APM server is installed, open the following file and copy the values of the client.secret.apmui and client.id.apmui variables:
    install_dir/wlp/usr/shared/config/clientSecrets.xml
    The following example shows what the file contains:
    <server>
      <variable name="client.secret.apmui" value="{xor}BiY3KQgIa2gRCms3CxxrMhUYL2YRJSwvCjUnJxYb" />
      <variable name="client.id.apmui" value="rpapmui" />
    </server>
  2. Optional: If you plan to use an access token in your curl command, use an XOR decoder to decode the value of the client.secret.apmui variable to get the actual secret value.
    For example, when you use an XOR decoder to decode BiY3KQgIa2gRCms3CxxrMhUYL2YRJSwvCjUnJxYb, you get the following value: YyhvWW47NU4hTC4mJGp9NzspUjxxID
  3. Optional: If you plan to use an access token in your curl command, complete this step. To get an access token, contact the token endpoint of the Cloud APM OIDC server with the four required items: username, password, client_id, and client_secret, as in the following command:
    curl --tlsv1.2 -v -k -d "grant_type=password&client_id=rpapmui&client_secret=YyhvWW47NU4hTC4mJGp9NzspUjxxID&username=apmadmin&password=apmpass&scope=openid" https://example.mycompany.com:8099/oidc/endpoint/OP/token
    Where:
    • username is the username of the Cloud APM console user
    • password is the password of a Cloud APM console user
    • clientid is the value of the client.id.apmui variable from step 1.
    • client_secret is the value created by the XOR decoder in step 2.
    Output:
    {"access_token":"jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8","token_type":"Bearer","expires_in":1800,"scope":"openid","refresh_token":"VsCWUhPHBRpidD2F1PVyZ2LNGMuQPTN837t3OoqZj71FcBfsGE"}
    Note: If the client_secret, username, or password values contain characters other than digits (0-9), ASCII letters (A-Z, a-z), and a few special characters ( "-" , "." , "_" , "~" ), you must URL encode the other characters. For example, if the decoded client secret is TEVlNjROVT8iPF9r=1dNNW8+SGFgJ0, replace the = character with %3D, replace the + character with %2B, and enter client_secret=TEVlNjROVT8iPF9r%3D1dNNW8%2BSGFgJ0 instead of client_secret=TEVlNjROVT8iPF9rO1dNNW8+SGFgJ0.
  4. Optional: If you plan to use an access token in your curl command, extract the access_token value.
    Looking at the output in the previous example, the value is jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8.
  5. Enter requests to the Threshold Management Service API using either an access token or basic authorization.
    Access token example
    curl --tlsv1.2 -v -k --request GET 
    --url 'https://myAPMServer.mycompany-domain.com:8091/1.0/thresholdmgmt/
    threshold_types/itm_private_situation/thresholds'  
    --header 'authorization: Bearer  jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8' 
    --header 'content-type: application/json'
    Basic authorization example
    curl --tlsv1.2 -v -k --request GET 
    --url 'https://myAPMServer.mycompany-domain.com:8091/1.0/thresholdmgmt/
    threshold_types/itm_private_situation/thresholds'  
    --header 'authorization: Basic YXBtYWRtaW46YXBtcGFzcw==' --header 
    'content-type: application/json'
  6. For more details about API operations, see API documentation in API Explorer. For instructions about accessing API Explorer, see Exploring the APIs.
    Note: Part of the URL and some of the headers shown in the examples are required for Cloud APM only. For example: https://api.ibm.com/perfmgmt/run, x-ibm-service-location, X-IBM-Client-Id, X-IBM-Client-Secret. See step 5 for request examples.

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://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"
        }
      ]
    }
  }
}'