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.

Important: The Concert Operate v1 APIs in this topic are planned for deprecation and replacement by v2 APIs in future releases.

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

Use the admin-user-details secret to set the password:

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

Set the route:

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

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.

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:

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.