Configuring probable cause

Edit online

The probable cause capability identifies the alert with the greatest probability of being the cause of the alert group, by using a combination of text classification and analysis of the topological information within the alerts. Within the Alert Viewer, probable cause ratings are presented for each alert in an alert group. You can configure how the system classifies alerts and performs probable cause scoring.

ObjectServer probable cause columns

Note: Make sure that topology management is enabled to use the probable cause capability. The topology management capability is enabled by default, for more information, see Cloud operator properties.

Hybrid deployments: The ObjectServer probable cause columns are not displayed by default for a hybrid deployment.
Tip: To display the Probable cause column in the Alert Viewer for hybrid deployments, edit the Example_IBM_CloudAnalytics view by adding the CEAEventScore field.

Cloud deployments: The ObjectServer probable cause columns are included by default in the Example_IBM_CloudAnalytics view in the Alert Viewer for a cloud deployment. The columns are as follows:

Table 1. ObjectServer probable cause columns
Column	Description
`CEAEventScore`	Contains the calculated score for an alert that indicates its probability of being the causal alert within an alert grouping.
`CEAEventClassification`	Contains the classification of the alert that is used as part of the scoring. Classification can take one of the following values: `Exception Information ErrorRate Latency Saturation StateChange Traffic Unknown`

Properties of probable cause

By default, the highest CEAEventScore is assigned to the name of the whole group. To disable this feature, you must disable the CEAUseSummaryMimeChild property in the master.cea_properties table in the Object Server by using the command:

> update master.properties set IntValue = 0 where Name = 'CEAUseSummaryMimeChild'; 
> go

You have now disabled the property.

Adding classification labels

You can add your own and customized classification labels, as long as they do not conflict with the existing built-in labels. To add a classification label, proceed as follows:

Submit the data with the new label by using the API endpoint api/mime/classificaiton/training_data. The header must include the X-TenantID parameter with the tenant ID value to use. The body must be formatted as JSON array of JSON objects. Each object must contain the "Label" and "Text" parameters, for example:
```
[{"Label":"Network","Text":"some classification about the network"}, 
{"Label":"Database","Text":"some classification text about the database"}]
```
Note: The label value is case-sensitive so the API gives an error if some ambiguity about the labels are present. You can ignore the ambiguity check by setting the header parameter ignore-labels-validation to true.

Note: Label values don't allow spaces, for example Network Error must be NetworkError.
Add the label weight to use with the topology correlation and probable cause. The weight can be added by using the topology management probable cause API end point, api/mime/addLabelWeight. The header must include the X-TenantID parameter with the tenant ID value to use. The body must be JSON array of JSON objects as follows:
```
[{"label": "Network","weight": 3.68}]
```
It is recommended to use a decimal value for the weight and that this value doesn't exist for other labels to avoid any calculation errors or ambiguity.
Request retraining of the machine learning model to use the new label in classification and probable cause. Retraining can be requested by using the API endpoint api/mime/classification/trainmodel. You can also instruct the trainer to train on your data only and skip the built-in classification data and labels. To do that, send the following parameter {"skip_default":"true"} as JSON object in the post request body. The model uses your custom data and completely ignores the built-in text and labels.
Note: The APIs can also be accessed through the swagger APIs. For loading data, labels, and requesting model training that you can use api/mime/classification/. For weights, you can use api/mime/swagger.

Configuring columns used to classify the alert

By default, classification of the alert is performed using the text in the Summary column text. You can specify an alternative ObjectServer column, or a custom ObjectServer column to use for classification.

Do this by using the swagger probable cause customization API POST operation, api/mime/LabelColumn. This POST request allows you to overwrite the default column and add extra fields. The tenant ID, X-TenantID, is necessary in the header parameter. The POST body must be an array of JSON objects where each object includes a "column" parameter along with the column name to use. The column names are case-sensitive and must exactly match the ObjectServer event columns.

Warning: If the column name specification in the POST body does not exactly match the column name in the ObjectServer, the column is ignored. If none of the columns match then the default column is used for classification.

Examples to add the custom columns are as follows:

Specify an alternative ObjectServer column

In the following example, AlertGroup is specified as the classification column and is used for the classification of any incoming new alerts.

[
{
"column": "AlertGroup"
}
]

Specify multiple ObjectServer columns

In the following example, three existing ObjectServer columns are concatenated and the resulting concatenation is used for classification.

[
{
"column": "AlertGroup"
},
{
"column": "Summary"
},
{
"column": "EventId"
}
]

Specify a custom ObjectServer column

In the following example, a custom ObjectServer column, my-custom-column, is used as the classification column. As with any other ObjectServer columns, custom column name specification in the POST body must exactly match the column name in the ObjectServer.

[
{
"column": "my-custom-column"
}
]

Note: In the case of a custom column, if this custom column was deleted from the ObjectServer, then classification reverts to using the default classification column, Summary.

Retrieving columns used for classification

You can retrieve the classification columns used for the tenant ID using the get method in the same API. The result is:

[
{
"column": "AlertGroup"
},
{
"column": "Summary"
},
{
"column": "EventID"
}
]