aggregated + operational values documentation

Change-Id: I3904be4f50f5ca07c3baad394db94c37916a6bc9

doc/source/alarm-severity-config.rst

@@ -10,11 +10,15 @@ the cloud, and stores and combines this information into a unified system
 model. An important property of an alarm is its **severity**. This severity can
 be used both in the Vitrage templates to trigger actions, and in the Horizon UI
 for color-coding purposes. Therefore, it is important that within the Vitrage
-data model, severity names are normalized.
+data model, severity names are aggregated and normalized.
 
 Since each data-source might represent severity differently, for each
-data-source we can supply it's own mapping to the normalized severity supported
+data-source we can supply it's own mapping to the aggregated severity supported
-in Vitrage. This page explains how to handle this mapping for a given
+in Vitrage. This way we can know which severity is more important.
+In addition we also normalize the severities for the horizon UI (called
+operational_severity) in order for the UI to know what color to show in
+Horizon.
+This page explains how to handle this mapping for a given
 data-source.
 
 
@@ -37,16 +41,16 @@ Configure Alarm Severity Mapping
 --------------------------------
 
 The alarm severity configuration files configure how the severity of each
-alarm is normalized. There are several guidelines for creating a config file:
+alarm is aggregated and normalized. There are several guidelines for creating
+a config file:
 
-- Normalized alarm values which can be mapped to can be found in
+- Operational severity is a normalized severity values can be mapped to
-  normalized_alarm_severity.py (OperationalAlarmSeverity class).
+  specific defined values which can be found in operational_alarm_severity.py
-- Each normalized severity also comes with a priority, so
+  (OperationalAlarmSeverity class).
-  that if an alarm is given different severities from different sources (e.g.,
+- Aggregated severity comes with a priority, so that if an alarm is given
-  a host alarm raised both by nagios and Vitrage), the severity with the
+  different severities from different sources (e.g., a host alarm raised both
-  highest priority will be used as the **aggregated severity**.
+  by nagios and Vitrage), the severity with the highest priority will be used
-- The *UNKNOWN* severity will be used for severities with no corresponding
+  as the **aggregated severity**.
-  normalized severity. This severity *must* appear in the config file.
 - The config file is in YAML format.
 - The config filename must be <datasource name>.yaml, for the relevant
   datasource.
@@ -71,17 +75,17 @@ Format
 
     category: ALARM
     values:
-      - normalized value:
+      - aggregated values:
-          name: <normalized alarm severity>
           priority: <Alarm severity priority - an integer>
           original values:
             - name: <Original alarm severity name>
-            - name: ... # can list several severities for one normalized
+              operational_value: <normalized alarm severity - from
-      - normalized value:
+                                  OperationalAlarmSeverity class>
-          name: ... # can list several normalized severities
+            - name: ... # can list several severities for one aggregation
+      - aggregated values:
+          priority: ... # can list several aggregated severities
           ...
 
-
   ...
 
 
@@ -89,37 +93,35 @@ Example
 +++++++
 
 The following file will map alarm severities.
-Original severities 'CRITICAL' and 'DOWN' will be mapped to normalized value
+For aggregated severity with priority 40 we have 2 severities and each one of
-'CRITICAL'. Normalized value 'SEVERE' has no original severity.
+them is mapped to operational severity CRITICAL.
-Original value 'WARNING' is mapped to normalized value 'WARNING', etc.
+For aggregated severity with priority 30 we have 1 severity called WARNING and
-
+it is mapped to operational severity WARNING, etc...
 ::
 
     category: ALARM
     values:
-      - normalized value:
+      - aggregated values:
-          name: CRITICAL
-          priority: 50
-          original values:
-            - name: CRITICAL
-            - name: DOWN
-      - normalized value:
-          name: SEVERE
           priority: 40
           original values:
-      - normalized value:
+            - name: CRITICAL
-          name: WARNING
+              operational_value: CRITICAL
+            - name: DOWN
+              operational_value: CRITICAL
+      - aggregated values:
           priority: 30
           original values:
             - name: WARNING
-      - normalized value:
+              operational_value: WARNING
-          name: UNKNOWN
+      - aggregated values:
           priority: 20
           original values:
             - name: UNKNOWN
-      - normalized value:
+              operational_value: N/A
-          name: OK
+      - aggregated values:
           priority: 10
           original values:
             - name: OK
+              operational_value: OK
             - name: UP
+              operational_value: OK

doc/source/resource-state-config.rst

@@ -10,11 +10,14 @@ the cloud, and stores and combines this information into a unified system
 model. An important property of a resource is its **state**. This state can
 be used both in the Vitrage templates to trigger actions, and in the Horizon UI
 for color-coding purposes. Therefore, it is important that within the Vitrage
-data model, state names are normalized.
+data model, state names are aggregated and normalized.
 
 Since each data-source might represent state differently, for each
-data-source we can supply it's own mapping to the normalized state supported
+data-source we can supply it's own mapping to the aggregated state supported
-in Vitrage. This page explains how to handle this mapping for a given
+in Vitrage. This way we can know which state is more important.
+In addition we also normalize the states for the horizon UI (called
+operational_state) in order for the UI to know what color to show in Horizon.
+This page explains how to handle this mapping for a given
 data-source.
 
 
@@ -71,14 +74,15 @@ Format
 
     category: RESOURCE
     values:
-      - normalized value:
+      - aggregated values:
-          name: <normalized resource state>
+          priority: <Resource state priority - an integer>
-          priority: <resource state priority - an integer>
           original values:
             - name: <Original resource state name>
-            - name: ... # can list several states for one normalized
+              operational_value: <normalized resource state - from
-      - normalized value:
+                                  OperationalResourceState class>
-          name: ... # can list several normalized states
+            - name: ... # can list several states for one aggregation
+      - aggregated values:
+          priority: ... # can list several aggregated states
           ...
 
 
@@ -88,27 +92,51 @@ Format
 Example
 +++++++
 
-The following is mapping resource values.
+The following file will map resource states.
-Original values 'DELETED' and 'TERMINATED' will be mapped to normalized value 'TERMINATED'.
+For aggregated state with priority 40 we have 4 states and each one of them is
-Original values 'ACTIVE' and 'RUNNING' to normalized value 'RUNNING'.
+mapped to operational severity ERROR.
+For aggregated state with priority 30 we have 6 states and each one of them is
+mapped to operational severity TRANSIENT, etc...
 
 ::
 
   category: RESOURCE
-  values:
+    values:
-    - normalized value:
+      - aggregated values:
-        name: TERMINATED
+          priority: 40
-        priority: 30
+          original values:
-        original values:
+            - name: ERROR
-          - name: DELETED
+              operational_value: ERROR
-          - name: TERMINATED
+            - name: ERROR_DELETING
-    - normalized value:
+              operational_value: ERROR
-        name: RUNNING
+            - name: ERROR_RESTORING
-        priority: 20
+              operational_value: ERROR
-        original values:
+            - name: ERROR_EXTENDING
-          - name: ACTIVE
+              operational_value: ERROR
-          - name: RUNNING
+      - aggregated values:
-    - normalized value:
+          priority: 30
-        name: UNRECOGNIZED
+          original values:
-        priority: 10
+            - name: CREATING
-        original values:
+              operational_value: TRANSIENT
+            - name: ATTACHING
+              operational_value: TRANSIENT
+            - name: DELETING
+              operational_value: TRANSIENT
+            - name: RESTORING-BACKUP
+              operational_value: TRANSIENT
+            - name: BACKING-UP
+              operational_value: TRANSIENT
+            - name: DETACHING
+              operational_value: TRANSIENT
+      - aggregated values:
+          priority: 20
+          original values:
+            - name: SUBOPTIMAL
+              operational_value: SUBOPTIMAL
+      - aggregated values:
+          priority: 10
+          original values:
+            - name: AVAILABLE
+              operational_value: OK
+            - name: IN-USE
+              operational_value: OK