Enabling access to the Probable cause customization APIs

The Probable cause API ranks the alerts in an incident. This API uses a classifier that uses Natural Language Processing (NLP) to determine the meaning of an alert and calculates the topology path between alerts to create a ranking for each applicable alert.

The Probable cause customization APIs are exposed by default, but to access them you must generate the token first. The API uses the IBM Cloud Pak Platform UI authentication, so you need a JWT (JSON Web Token) to be authenticated. The token is used to determine whether a user or service ID has access when they use the API.

Probable Cause Customization APIs

  1. Log in to the cluster.

  2. Set ROUTE to cpd route.

    1. If you have an existing installation of Cloud Pak for AIOps on Linux, run the following command:

      ROUTE=$(oc get ingress zen-ingress -n cp4aiops -o jsonpath='{.spec.rules[0].host}')

    2. If you have an existing installation of Cloud Pak for AIOps on OpenShift Container Platform, run the following command:

      ROUTE=$(oc get route cpd -n cp4aiops --no-headers | awk '{print $2}')

  3. Use the admin-user-details secret to set PASS.

    PASS=$(oc get secret admin-user-details -o jsonpath='{.data.initial_admin_password}' -n cp4aiops | base64 -d)

  4. Create the TOKEN.

    TOKEN=$(curl -s -k -X POST https://$ROUTE/icp4d-api/v1/authorize -H 'Content-Type: application/json' -d '{"username": "admin","password": <PASS>}' | jq .token | sed 's/"//g')

    Where PASS is the password obtained in the preceding step.

Example of accessing the APIs

You can now access the APIs, for example:

/customisation/edge_type

Use a GET request /customisation/edge_type to get the list of edges in the system.

curl -k -X GET --header 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/edge_type -H "accept: application/json" -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255"

The label and edge names are the same as those added in the topological resource group. Some edges have different weight due to directorial. Overall, an indegree edge has a higher weight than an outdegree edge.

Note: If the system encounters an unknown edge type, then it uses the average of weight in the edge label group.

The following example shows a response(200) for the GET request:

{
"edge_type_list": [
   {
      "edge": "string",
      "label": "AGGREGATION",
      "outdegree": 0,
      "indegree": 0
   }
]
}

Use a POST request /customisation/edge_type to overwrite the complete list of edge types.

curl -k -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/edge_type -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255" -d '{"edge_type_list":[{ "edge": "newEdgeName", "label": "association", "outdegree": 20,"indegree": 5}]}'

The following example shows a response(200) for the POST request:

{"Result":"Success"}

After the path score is calculated, the summary is classified in one of the following 8 categories.

Table 1. Label and Weight relationship for classification of summary
Label Weight
errorrate 1.4
exception 1.2
information 1
latency 2
saturation 2.2
stateChange 1.8
traffic 2.4
unknown -1

In order to modify the label weight, use the API /customisation/label_weight.

/customisation/label_weight

Use a POST request /customisation/label_weight to add or update label weight. The request body is an array of label weight objects.

curl -k -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${TOKEN}" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/label_weight -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255" -d '{"label_weight_list":[{"label":"association","weight":1.2}]}'

The following example shows a response(200) for the POST request:

{"Result":"Success"}

Note: Before removing a label from the list, remove all of the training examples from the classifier. The classifier looks at the word in the summary and attempts to put the alert in the in the appropriate category.

/customisation/words

Use a GET request /customisation/words to get the list of words in alert summary that is used by probable cause for the specified tenant ID. If the GET request is successfull (200 response), the response includes an array of words for the alert.

curl -k -X GET --header 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/words -H "accept: application/json" -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255"

The following example shows a response(200) for the GET request:

{
   "words":[
      {
         "word":"error",
         "caseSenstive":false,
         "weight":100
      },
      {
         "word":"ECC",
         "caseSenstive":true,
         "weight":10
      }
   ]
}

If both words "error" and "ECC" are found in same alert summary then the weight(score) is added. For example, if error has a weight of 100 and ECC has a weight of 10, then the total word score is 110. The higher the score, the more likely that this alert is a root cause.

Use a POST request /customisation/words to update(replace) the words in the system. The request body is the JSON array of words for probable cause.

curl -k -X POST --header 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/words -H "accept: application/json" -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255" -d '{"words":[{"word":"error","caseSenstive": false, "weight":100}, {"word":"ECC","caseSenstive": true, "weight":10}]}'

The following example shows a response(200) for the POST request:

{"Result":"Success"}

/customisation/severity

Use a GET request customisation/severity to get the list of severities that is used by probable cause for the specified tenant ID. Based on the severity of the alert, the weight is added to the word score. Refer to the following table for more details:

Table 2. Severity and Weight relationship
Severity Weight
1 10
2 20
3 30
4 40
5 50
6 60

If the word score is 110(Error and ECC from previous example) and the severity of the alert is critical(which is 6), then 60 is added to the score, resulting in a word score of 170.

curl -k -X GET --header 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/severity -H "accept: application/json" -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255"

The following example shows a response(200) for the GET request:

{
   "severities":[
      {
         "severity":2,
         "weight":20
      }
   ]
}

Use a POST request /customisation/severity to update(replace) the probable cause to use the array of severities. The request body is JSON array of severities which will overwrite the current array of severities.

The following example shows a response(200) for the POST request:

{"Result":"Success"}

Use a DELETE request /customisation/severity to delete all the severities for the specified tenant ID.

The following example shows a response(200) for the DELETE request:

{"Result":"Success"}

/customisation/scoring/config

Use a GET request customisation/scoring/config to get the scoring configuration parameters for the specified tenant ID. If the API request is successfull(200 response), the response includes a list of the scoring configuration attributes that are turned on or off.

curl -k -X GET --header 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" https://$ROUTE/aiops/api/issue-resolution/mime/v1/customisation/scoring/config -H "accept: application/json" -H "X-TenantID: cfd95b7e-3bc7-4006-a4a8-a73a79c71255"

The following example shows a response(200) for the GET request:

{
"pathCaculationEnabled": true,
"wordEnabled": true,
"severityEnabled": true,
"causeScoreEnabled": true,
"itnmproccessing": true,
"itnmCausesWeight": 110,
"firstBoost" : true,
"firstBoostWeight" : 100,
}

Use a POST request customisation/scoring/config to alter the scoring configuration parameters for the specified tenant ID.

The following example shows a response(200) for the POST request:

{"Result":"Success"}

For more information about probable cause ranking and probable cause determination, see Probable cause ranking

Next steps

For more information about probable cause, see Probable cause in ChatOps.

For more information about the available APIs and related Swagger documentation, see the additional topics under APIs. For example, for more on access tokens, see Accessing APIs.