Event enrichment with topology information
The topology information in an event helps display service models in BMC Helix AIOps. The topology information is added to an event after the refinement phase.
Event slot facet configuration
Event slots are event attributes and they store event values. Facets control the values that the slot can have or control aspects of the event’s processing. By default, certain event slots of the out-of-the-box event classes are defined with the topology_lookup facet. This facet indicates that the slot value holds the equivalent slot name that is used to look up topology information in BMC Discovery. While creating slots for a custom class, you need to specify this facet for only those slots that are meant to be used for looking up topology information. If you don't define a lookup slot in a child event class, the lookup slot (source_hostname) of the event base class is used as a fallback slot to look up topology information.
Event class | Topology lookup slot |
---|---|
EVENT | source_hostname |
ALARM | _ci_id, external_id |
PATROL_EV | source_hostname |
ANOMALY | source_hostname |
Any custom class | Any slot that is marked with the topology_lookup facet. |
In addition to defining the topology_lookup facet for an event slot, you can define the topology_lookup_mandatory and topology_lookup_optional facets at the class level to filter out slots in the class hierarchy for which you want to look up topology information.
Slot mapping
Refer to the following table to understand the mapping between the topology lookup slots in BMC Helix Operations Management and the equivalent lookup slots in BMC Discovery.
Topology lookup slot in BMC Helix Operations Management | Equivalent lookup slot in BMC Discovery |
---|---|
source_hostname | name, short_name |
_ci_id | external_ids |
external_id | external_id |
object | external_ids |
custom_slot_1 | custom_slot_1_field_in_smartgraph |
How events are enriched with topology information
All event slots that are defined with the topology_lookup facet hold the equivalent slot name in BMC Discovery that is used to look up topology information.
Based on the slot mapping, the system creates a query by using the OR or AND operator to lookup topology information from the smart graph in BMC Discovery.
The system uses the smart graph service API to create the smart graph query. 10 seconds is the default socket timeout for the smart graph service API. The API executes the following retry mechanism in case of a timeout:
- The next API call after a timeout has a socket timeout that lasts for 15 seconds.
- If the API call attempt fails, the system sets the service status to Halted and activates an exponential backoff delay in minutes.
For example, the exponential backoff delay in minutes is stored as follows:
( {0,1,2,3,5,8,13} ) - For each API call, the system checks the status and the suspended time. Suspended time is the duration for which the system does not execute the smart graph service API call.
If the suspended time is less than the current time, the system triggers the smart graph service API call. - If the API call fails, the delay increases according to the exponential backoff array. If the API call executes successfully, the service status is set to Active and the suspended time is set to zero.
Refer to the examples in the following table to help understand the smart graph query structure:
Event class | Class definition | Incoming event details | Smart graph query | Topology details enriched in the event |
---|---|---|---|---|
EVENT | In this case, source_hostname is the lookup slot in BMC Helix Operations Management and name and short_name are the lookup slots in BMC Discovery. | |||
My_Custom_Class | In this case, custom_slot_1 and source_hostname is the lookup slot in BMC Helix Operations Management and custom_slot_1_field_in_smartgraph is the lookup slot in BMC Discovery. |
Event slot facet combinations
You can specify various combinations to indicate the mandatory and optional topology lookup slots that you want to look up from BMC Discovery.
The slots defined with the topology_lookup_mandatory facet are queried by using the AND operator and the slots defined with the topology_lookup_optional facet are queried by using the OR operator in the smart graph query. If you specify both the facets for slots, they are queried by using the AND operator.
The topology_lookup_mandatory and topology_lookup_optional facets are defined at the class level and apply only to events that are ingested for the class and not for the child or parent class events. You cannot specify the same slots in both the facets.
If you have not defined the facet at the class level, the smart graph query uses the OR operator with all the topology slots from the event class hierarchy.
The following facet combinations are supported:
Specific slots from the topology_lookup_mandatory facet in an event class.
"allFacet": [
{
"name": "topology_lookup_mandatory",
"value": "source_hostname,namespace"
},
{
"name": "topology_lookup_optional",
"value": "none"
}
]Specific slots from the topology_lookup_optional facet in an event class instead of all slots from the class hierarchy.
"allFacet": [
{
"name": "topology_lookup_optional",
"value": "source_hostname,namespace"
}
]Specific slots from the topology_lookup_mandatory facet and the topology_lookup_optional facet in an event class.
"allFacet": [
{
"name": "topology_lookup_mandatory",
"value": "namespace"
},
{
"name": "topology_lookup_optional",
"value": "source_hostname,custom_slot"
}
]Specific slots from the topology_lookup_mandatory facet and remaining slots from the event class hierarchy.
"allFacet": [
{
"name": "topology_lookup_mandatory",
"value": "namespace"
}
]The topology enrichment for an event class is skipped if the topology_lookup_optional facet is defined as "none".
"allFacet": [
{
"name": "topology_lookup_optional",
"value": "none"
}
]
The following table lists the topology lookup slots for an event class:
Event class | Lookup slot | Field name in the smart graph that is used in the lookup query |
---|---|---|
EVENT | source_hostname | name, short_name |
Custom_Class (child of EVENT) | namespace | namespace |
Custom_Class_Child (child of Custom_Class) | custom_slot | custom_slot |
Refer to the examples in the following table to help understand the smart graph query structure:
Facet combination | Smart graph query |
---|---|
NA | This smart graph query for Custom_Class is the default. |
Mandatory facet for Custom_Class "allFacet": [ { "name": "topology_lookup_mandatory", "value": "source_hostname,namespace" }, { "name": "topology_lookup_optional", "value": "none" } ] | |
Mandatory and optional facets for the Custom_Class_Child "allFacet": [ { "name": "topology_lookup_mandatory", "value": "namespace" },{ "name": "topology_lookup_optional", "value": "source_hostname,custom_slot" } ] | |
Optional facet for the Custom_Class "allFacet": [ { "name": "topology_lookup_optional", "value": "namespace,source_hostname" } ] | |
Mandatory facet for the Custom_Class_Child "allFacet": [ { "name": "topology_lookup_mandatory", "value": "namespace,custom_slot" }, { "name": "topology_lookup_optional", "value": "none" } ] |
Best match algorithm
The system executes a best match algorithm to enrich the best matching entity details from BMC Discoveryin an event based on the lookup slots. This information associates nodes and their services to the event. This algorithm is not executed on the smart graph response that is received for an event class in which you have defined the class level topology facet. The best match is determined by the following process:
Topology lookup according to the node kind
By default, you can look up topology information from BMC Discovery for the following node kinds:
- BusinessService
- TechnicalService
- BusinessApplicationInstance
However, if you don't want to enrich topology information for multiple and unwanted node kinds in an event but you do for specific node kinds, specify the node kind in the cdmclass attribute of the event.
To enrich the cdmclass attribute of the event, see Event-enrichment-for-adding-context.
In BMC Discovery, there are different sections, such as inferred, integration, ddd, monitor, operation, abstract, and so on, for the node kinds. The node kinds represent entities in the IT environment. The node kinds are available in the inferred section because their existence is inferred from one or more data sources. Hence, the topology lookup based on the node kind is supported only for the inferred section.
Example: Handling node and service association for Kubernetes
For associating events with the Kubernetes deployment and pod details, the deployment ID for Kubernetes is enriched in the node ID of the alarm event generated for Kubernetes.
Refer to the following table to understand the mapping for retrieving the deployment ID and setting it as the node ID:
Monitor type for which an alarm is generated (object_class slot’s value from alarm) | Slot from the alarm event whose value is used for the smart graph lookup | Slot name in the smart graph that is queried with the value from the event |
K8S_DEPLOYMENT | object | external_ids |
K8S_NAMESPACE | object | external_ids |
K8S_CLUSTER | object | external_ids |
K8S_POD | object | external_ids |
K8S_POD_CPU | external_id | external_ids |
K8S_POD_MEMORY | external_id | external_ids |
K8S_POD_EPHSTORAGE | external_id | external_ids |
K8S_POD_NETWORK | external_id | external_ids |
K8S_POD_VOLUME_CNTR | external_id | external_ids |
K8S_POD_VOLUME | external_id | external_ids |
The following table shows the smart graph query and the query response:
Incoming alarm event | Smart graph query | Smart graph response |
---|---|---|
Similar to the preceding response. |
Node id enrichment:
- For a normal host or VM node, the id value is considered as the node_id.
- For Kubernetes, the deployment value is enriched as the node id.
- Also, for Kubernetes, if the deployment is empty and not returned, the id value is considered as the node_id.
Service id enrichment:
- All the service list from the response (aggServices, mdServices, swServices, and tsomService) are combined and a unique service ids list is enriched in the event.