Situation Clustering Dimensions APIs
This section describes the situation clustering dimension APIs.
The Situation Clustering APIs allow the tenant administrator to configure the situations clustering, and root cause analysis functionality. These configurations take precedence over the default configuration values when the configurations are specified by the user.
This section provides the following information:
Supported Parameters
The following parameters are supported for situation clustering APIs.
Key | Default Value | Min/Max Value | Data Type | Description |
|---|---|---|---|---|
historicalweight | 0.5 | 0.0/1.0 | Define the Weightage of historical data in the template similarity calculation. | |
serviceweight | 0.5 | 0.0/1.0 | Define the Weightage of services in the template similarity calculation. | |
ciSignificance | 1.0 | 0.0/1.0 | Define the Weightage of CIs in clustering calculation for APM alarms. | |
temporalSignificance | 1.0 | 0.0/1.0 | Define the Weightage of temporal in the clustering calculation. | |
textSignificance | 1.0 | 0.0/1.0 | Define the Weightage of text in clustering calculation. | |
enableServiceClustering | TRUE | Signifies whether service similarity is considered for clustering or not. | ||
is_consider_absolute_service | FALSE | If true, service similarity is considered without service the weightage. | ||
percentile | 0.95 | 0.0/1.0 | Removes RCA candidates with low score edges. | |
damping_factor | 1 | 1/- | ||
rootcause_count | 3 | 1/- | Maximum number of root causes. | |
skip_hist_priors | FALSE | Signifies whether historical data is considered for RCA or not. | ||
score_threshold | 0.5 | 0.0/1.0 | Score Limit to consider a template as an RCA candidate. | |
noise_threshold | 0.8 | 0.0/1.0 | Entropy value to identify the noise. | |
skip_alarm_types | anamoly,informative,predictive | list | The specified type does not participate in clustering. | |
enable_historical_flow | TRUE | Enables historical flow for similarity calculation. | ||
excludeNonServiceImpactedTemplates | FALSE | Excludes the non-services impacted templates during clustering. | ||
alarm_updates_consider_period | 1000 | 1/1825 | Specifies the age of the alarm (in terms of the number of days) to be considered for situation clustering. If the alarm's age is greater than configured age, they are not considered for situation clustering. | |
enable_single_alarm_association | False | Enables Single Alarm association with a situation when the value is set to 'True'. DX Operational Intelligence creates one situation when a new alarm is raised. After the Situation is stable, the application does not create situations when there are updates to the alarm. | ||
additional_cluster_group_by | list | Enables you to add custom clustering criteria to determine the alarm similarity for clustering. For more information, see the section on this page. | ||
custom_naming_operations_ config | Enables you to add custom attribute values for operations to define custom situation name. For more information, see the section on this page. |
Configure Attributes API
This API allows you to configure the attributes for situation clustering.
API Parameters
- You can select the URI based on the deployment and region of your tenant:
- DX SaaS - USA:https://doi.dxi-na1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- DX SaaS - EU:https://doi.dxi-eu1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- Method:POST
- HTTP Headers:
- Content-Type:application/JSON
- Authorization:bearer tokenFor more information on tokens, see the Token Management section.
- Syntax:{ "tenantId": "DF1D62B7-DB3D-4100-8738-9409A02845A0", "configAttrList": [ { "key": "serviceWeight", "value": 0.7, "type": "double" }, { "key": "is_consider_absolute_service", "value": false, "type": "boolean" }, { "key": "temporalSignificance", "value": 0.0, "type": "double" } { "key": "additional_cluster_group_by", "value": [ { "type": "MATCH_BY_PERCENTAGE", "fields": [ "product","severity" ] } ], "type": "list" ] }
- Response:200 OK{ "status": "Success" }
Usage Example - Configure Attributes API
Resource URL:
https://doi.dxi-na1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributesPayload:
{ "tenantId": "DF1D62B7-DB3D-4100-8738-9409A02845A0", "configAttrList": [ { "key": "historicalWeight", "value": 0.0, "type": "double" }, { "key": "serviceWeight", "value": 0.7, "type": "double" }, { "key": "ciSignificance", "value": 1.0, "type": "double" }, { "key": "temporalSignificance", "value": 0.0, "type": "double" }, { "key": "textSignificance", "value": 1.0, "type": "double" }, { "key": "enabledServiceClustering", "value": true, "type": "boolean" }, { "key": "is_consider_absolute_service", "value": false, "type": "boolean" }, { "key": "percentile", "value": 0.95, "type": "double" }, { "key": "damping_factor", "value": 0.85, "type": "double" }, { "key": "rootcause_count", "value": 3, "type": "double" }, { "key": "skip_hist_priors", "value": false, "type": "boolean" }, { "key": "score_threshold", "value": 0.5, "type": "double" }, { "key": "noise_threshold", "value": 0.8, "type": "double" }, { "key": "skip_alarm_types", "value": [ "anomaly", "informative", "predictive" ], "type": "list" }, { "key": "enable_historical_flow", "value": true, "type": "boolean" }, { "key": "excludeNonServiceImpactedTemplates", "value": false, "type": "boolean" }, { "key": "alarm_updates_consider_period", "value": 1000, "type": "integer" }, { "key": "enable_single_alarm_association", "value": true, "type": "boolean" } { "key": "additional_cluster_group_by", "value": [ { "type": "MATCH_BY_PERCENTAGE", "fields": [ "product","severity" ] } ], "type": "list" ] }
Response:
{ "status": "Success" }
Update Existing Values API
This API allows you to update the existing values of the situation clustering.
API Parameters
- You can select the URI based on the deployment and region of your tenant:
- DX SaaS - USA:https://doi.dxi-na1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- DX SaaS - EU:https://doi.dxi-eu1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- Method:PUT
- HTTP Headers:
- Content-Type:application/JSON
- Authorization:bearer tokenFor more information on tokens, see Token Management section.
- Body:{ "tenantId": "<tenantid>", "configAttrList": [ { "key": "<keyvalue>", "value": <defaultvalue/user-specified value>, "type": "<type of the key>" }, . . . { "key": "temporalSignificance", "value": 0.0, "type": "double" }, ] }
- Response:200 OK{"Status":"Success"}
Usage Example - Update Existing Values
Resource URL:
https://doi.dxi-na1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributesBody:
{ "tenantId": "DF1D62B7-DB3D-4100-8738-9409A02845A0", "configAttrList": [ { "key": "serviceWeight", "value": 0.7, "type": "double" }, { "key": "is_consider_absolute_service", "value": false, "type": "boolean" }, { "key": "temporalSignificance", "value": 0.0, "type": "double" } { "key": "additional_cluster_group_by", "value": [ { "type": "MATCH_BY_PERCENTAGE", "fields": [ "product","severity" ] } ], "type": "list" ] }
Response:
{"Status":"Success"}
Error Response:
{ "Error":"Error in attribute with key: enable_historical_flowz, type: boolean, value: true", "Reason":"Invalid key - enable_historical_flowz" }
Custom Clustering Criteria API
This API enables you to add custom clustering criteria.
- You can cluster the alarms by entity, message, and service out-of-the-box. You cannot delete the default criteria.
- You can add only a maximum of five additional clustering criteria.
- A custom clustering criteria can be deleted only if it is not associated with any situation definition.
API Parameters
- You can select the URI based on the deployment and region of your tenant:
- DX SaaS - USA:https://doi.dxi-na1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- DX SaaS - EU:https://doi.dxi-eu1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- Method:PUT
- HTTP Headers:
- Content-Type:application/JSON
- Authorization:bearer tokenFor more information on tokens, see Token Management section.
- Response:200 OK{"Status":"Success"}
Sample Body - Add Custom Clustering Criteria
The following sample body illustrates the payload to add AlarmType as the custom criteria:
Ensure to send the complete payload in the PUT request.
{ "tenantId": "BB40FB73-3AEC-4B75-B96C-91DB89SW2", "configAttrList": [ { "key": "additional_cluster_group_by", "value": [ { "type": "MATCH_BY_PERCENTAGE", "fields": [ "product", "alarmType", "severity" ] } ], "type": "list" } ] }
The following image illustrates the custom clustering criteria that was added using this API:

Sample Body - Delete Custom Clustering Criteria
The following sample body illustrates the payload to delete the custom criteria (AlarmType) that was added earlier:
Ensure to send the complete payload in the PUT request.
{ "tenantId": "BB40FB73-3AEC-4B75-B96C-91DB89SW2", "configAttrList": [ { "key": "additional_cluster_group_by", "value": [ { "type": "MATCH_BY_PERCENTAGE", "fields": [ "product", "severity", ] } ], "type": "list" } ] }
Add or Remove Supported Fields for Custom Situation Name Operations API
This API enables you to add or remove supported fields for custom situation name operations.
API Parameters
- You can select the URI based on the deployment and region of your tenant:
- DX SaaS - USA:https://doi.dxi-na1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- DX SaaS - EU:https://doi.dxi-eu1.saas.broadcom.com/oi/v2/api/clusteralarms/tenantConfigAttributes
- Method:PUT
- HTTP Headers:
- Content-Type:application/JSON
- Authorization:bearer tokenFor more information on tokens, see Token Management section.
- Response:200 OK{"Status":"Success"}
Sample Body - Add Supported Fields
The following sample body illustrates the payload to add
message
as a supported field for the listof
operation:
- The custom attribute must be part of the Operations definition, Clustering criteria fields, and Compressed alarm fields.
- Ensure to send the complete payload in the PUT request.
"tenantId": "BB40FB73-3AEC-4B75-B96C-91DB89SW2", "configAttrList": [ { "key": "custom_naming_operations_config", "value": [ { "name": "count", "supportedFields": [ "severity", "product", "services_impacted", "host", "groups", "message" ] }, { "name": "policyname", "supportedFields": [] }, { "name": "ngram", "supportedFields": [ "message" ] }, { "name": "listof", "supportedFields": [ "severity", "product", "services_impacted", "host" "message" ] }, { "name": "mostimpacted", "supportedFields": [ "severity", "product", "services_impacted", "host", "groups", "message" ] } ], "type": "list" } ] }'
Sample Body - Delete Supported Fields
The following sample body illustrates the payload to delete
message
as the supported field for the listof operation:
Ensure to send the complete payload in the PUT request.
"tenantId": "BB40FB73-3AEC-4B75-B96C-91DB89SW2", "configAttrList": [ { "key": "custom_naming_operations_config", "value": [ { "name": "count", "supportedFields": [ "severity", "product", "services_impacted", "host", "groups", "message" ] }, { "name": "policyname", "supportedFields": [] }, { "name": "ngram", "supportedFields": [ "message" ] }, { "name": "listof", "supportedFields": [ "severity", "product", "services_impacted", "host" ] }, { "name": "mostimpacted", "supportedFields": [ "severity", "product", "services_impacted", "host", "groups", "message" ] } ], "type": "list" } ] }'