vitrage-specs/specs/pike/implemented/entity-equivalence.rst

Define and handle equivalence among entities

https://blueprints.launchpad.net/vitrage/+spec/entity-equivalence

Define equivalence among entities to allow mapping two or more entities to same object and handle it properly in scenario evaluator. It is inspired by Idan Hefetz's proposal about ZTE use case of alarm deduction, but designed in a generic way to allow extending to RESOURCE equivalence in future.

Problem description

Introducing entity equivalence will enhance the extensibility of Vitrage, making it suitable for more use cases, such as

• early deduction of alarm before it is reported and deal with the real alarm followed
• aggregation of equivalent alarms from multiple monitors
• aggregation of resource information from multiple data sources.

Proposed change

Add a new file (or a set of files) that define equivalence between entities

metadata:
 name: entity equivalence example
equivalences:
 - equivalence:
    - entity:
       category: ALARM
       type: nagios
       name: host_problem
    - entity:
       category: ALARM
       type: zabbix
       name: host_problem
    - entity:
       category: ALARM
       type: vitrage
       name: host_problem
  - equivalence:
    ...

These definitions will take effect globally, i.e. for every other template

The evaluator will duplicate every scenario for every equivalent alarm automatically. For example, in case of the condition:

condition: nagios_host_problem_on_host and host_contains_vm

Two conditions will be created internally:

condition: nagios_host_problem_on_host and host_contains_vm
condition: zabbix_host_problem_on_host and host_contains_vm
condition: vitrage_host_problem_on_host and host_contains_vm

The idea is that the user will write a single condition, and all equivalent conditions will be created and evaluated automatically.

Equivalences should be defined explicitly. Including one entity in two or more equivalence definition will result in implicit chaining, thus is considered invalid. For example, if a eq b and b eq c are defined separately, it will logically result in an implicit a eq c. This will introduce unnecessary complexity in creating templates and should be restricted in validator.

Alternatives

Separate file vs embedded definition

Instead of creating a separate file, we may embed the equivalence definitions in templates by adding a new section equivalences. Entities that are equivalent to each other are grouped in arrays of their template_id

metadata:
 name: entity equivalence example
definitions:
 entities:
  - entity:
     category: ALARM
     type: nagios
     name: host_problem
     template_id: nagios_host_problem
  - entity:
     category: ALARM
     type: zabbix
     name: host_problem
     template_id: zabbix_host_problem
  - entity:
     category: ALARM
     type: vitrage
     name: host_problem
     template_id: vitrage_host_problem
  ...
 relationships:
  ...
 equivalences:
  - [nagios_host_problem, zabbix_host_problem, vitrage_host_problem]
scenarios:
  ...

In this way, there will be fewer duplication of entity definitions.

However, given the fact that once an equivalent edge is added between two alarms, then it logically means that they are equivalent in all other templates as well. Even if they are not specified this way in the other templates. Then template will be less clear without the equivalence information embedded in it.

The duplication of entity definition might be resolved by implementing an import feature in other blueprint.

Adding equivalent edge vs not

equivalent edges could be created between every two equivalent alarms. Since all related scenarios have been duplicated, This does not bring extra value in the evaluator.

The equivalent edge could be useful for future evolution such as alarm aggregation, UI optimization, alarm deduction. It may be implemented in those blueprints.

Data model impact

None

REST API impact

None

Versioning impact

None

Other end user impact

None

Deployer impact

None

Developer impact

None

Horizon impact

There are currently three views in vitrage-dashboard

Topology view

No impact

RCA view

More alarms and more causes edges

(yujunz) include example graph

Entity graph

• separate vertices for equivalent alarms (nagios, zabbix, vitrage)
• more edges (equivalent and on)

Summary

The impacts on RCA view and Entity graph will only be relevant to cases where both equivalence and vitrage-dashboard are used. We will handle it in future blueprints.

Implementation

Assignee(s)

Primary assignee:

yujunz

Other contributors:

None

Work Items

• validate and parse equivalence definition in templates
• duplicate scenarios in the scenario repository
• no changes in sub-graph matching or the evaluator

The following items are not in scope

• aggregation of equivalent alarms
• add-equivalent action
• support alarm equivalence in UI
• implement causal tree model for alarm deduction enhancement
• resource equivalence

Dependencies

None

Testing

The implementation will be covered by additional unit test

Documentation Impact

• documentation on how to define equivalence and when to use it
• declare limitation on resource equivalence
• list known issues when use equivalence with vitrage-dashboard

References