Add a simplified way to have counter-part messages

From the YAML profiles, which can be easily extended and loaded into the
user environment, we should be able to signalise groups or pairs of
notifications, referring to the same entity (i.e., interface, neighbour,
alarm, etc.). This would have a direct applicability into the Prometheus
metrics, as it'd add a new `_state` metric by default, but also would be
useful in the other publishers which will be adding the new ``state``
field when provided. The new ``state`` field is a numeric value, with
a specific meaning, mapping out to a value that provides a meaningful
information for the end user (e.g., interface up = 1, interface down = 0;
alarm set = 1, alarm cleared = 0, and so on.) - but not limited to
binary values only, there can be as many states as desired.

Author: mirceaulinic

docs/developers/device_profiles.rst

@@ -213,6 +213,41 @@ should be placed. There are two options, ``variables`` and ``static``.
 ``variables`` should be used when the value being set is taken from the message,
 and ``static`` should be used when the value is manually set.
 
+``state``
+---------
+
+``state`` is an optional config bit which may be useful when defining messages 
+that have a counter-part. For example: ``MAJOR_ALARM_SET`` 
+/ ``MAJOR_ALARM_CLEARED``. The idea behind this is to have pairs or groups of 
+notifications that have a specific significance mapping out to a desired value
+(e.g., the state value for ``MAJOR_ALARM_SET`` can be 1, while the state value
+for ``MAJOR_ALARM_CLEARED`` can be 0). The value can be any number, not only 
+binary, when the group is larger than two notifications.
+
+It is equally important to not that when using the :ref:`publisher-prometheus` 
+Publisher, when using this field, an additional metric is being exposed, 
+providing the state value, besides the usual counter.
+
+The metric name is derived from the base name of the notification, by stripping 
+the last part (after underscore) and replacing it with ``_state``. For 
+instance, continuing the example above, ``MAJOR_ALARM_SET`` and 
+``MAJOR_ALARM_CLEARED`` would both set the same Gauge metric 
+``napalm_logs_major_alarm_state``. If the notification groups don't have 
+a common base name for whatever reason, you can define individual state tags 
+using the ``state_tag`` option (see below).
+
+``state_tag``
+-------------
+
+This option provides a custom name for the state metric on groups of 
+notifications. By default, this is not necessary, as it's assumed a group has
+the same base name, but it may not always be the case.
+
+Based on the example above, ``MAJOR_ALARM_SET`` and ``MAJOR_ALARM_CLEARED`` 
+would, by default, set the ``napalm_logs_major_alarm_state`` Gauge metric, 
+however, by providing the value ``state_tag: system_alarm_state`` (for both), the 
+metric becomes: ``napalm_logs_system_alarm_state``.
+
 Pure Python profiles
 ++++++++++++++++++++
 

napalm_logs/config/eos/MAINTENANCE_MODE.yml

@@ -0,0 +1,23 @@
+messages:
+
+  - error: MAINTENANCE_MODE_STARTED
+    tag: MMODE-5-MAINT_UNIT_STATE_CHANGE
+    state: 1
+    values: {}
+    line: ': Maintenance unit state changed for unit MAINT-UNIT. Old State maintenanceModeEnter, New State underMaintenance'
+    model: ietf-notification-messages
+    mapping:
+      variables: {}
+      static:
+        notification-messages//notification-message//message-text: "maintenance started"
+
+  - error: MAINTENANCE_MODE_ENDED
+    tag: MMODE-5-MAINT_UNIT_STATE_CHANGE
+    state: 0
+    values: {}
+    line: ': Maintenance unit state changed for unit MAINT-UNIT. Old State maintenanceModeExit, New State active'
+    model: ietf-notification-messages
+    mapping:
+      variables: {}
+      static:
+        notification-messages//notification-message//message-text: "maintenance ended"

napalm_logs/device.py

@@ -136,6 +136,8 @@ def _compile_messages(self):
                     'replace': replace,
                     'model': model,
                     'mapping': mapping,
+                    'state': message_dict.get('state'),
+                    'state_tag': message_dict.get('state_tag'),
                 }
             )
         log.debug('Compiled messages:')
@@ -175,6 +177,8 @@ def _parse(self, msg_dict):
                 'mapping': message['mapping'],
                 'replace': message['replace'],
                 'error': message['error'],
+                '_state': message['state'],
+                '_state_tag': message['state_tag'],
             }
             for key in values.keys():
                 # Check if the value needs to be replaced
@@ -355,6 +359,10 @@ def start(self):
                 'facility': facility,
                 'severity': severity,
             }
+            if kwargs.get('_state') is not None:
+                to_publish['state'] = kwargs['_state']
+                if kwargs.get('_state_tag'):
+                    to_publish['state_tag'] = kwargs['_state_tag']
             log.debug('Queueing to be published:')
             log.debug(to_publish)
             # self.pub_pipe.send(to_publish)

napalm_logs/server.py

@@ -144,6 +144,8 @@ def _compile_prefixes(self):
                         'prefix_positions': sorted_position,
                         'raw_prefix': escaped.format(**values),
                         'values': values,
+                        'state': prefix.get('state'),
+                        'state_tag': prefix.get('state_tag'),
                     }
                 )
         # log.debug('Compiled prefixes')

napalm_logs/transport/prometheus.py

@@ -40,6 +40,17 @@ def __parse_without_details(self, msg):
             )
         self.metrics[error].labels(host=msg['host']).inc()
 
+        if msg.get('state') is not None:
+            base = error.split('_')[:-1]
+            metric = msg.get('state_tag', '_'.join(base + ['state']).lower())
+            if metric not in self.metrics:
+                self.metrics[metric] = Gauge(
+                    'napalm_logs_{}'.format(metric),
+                    'State for {} type notifications'.format('_'.join(base)),
+                    ['host'],
+                )
+            self.metrics[metric].labels(host=msg['host']).set(msg['state'])
+
     def __parse_user_action(self, msg):
         '''
         Helper to generate Counter metrics that provide the host label, together

tests/config/eos/MAINTENANCE_MODE_ENDED/default/syslog.msg

@@ -0,0 +1 @@
+<100>Feb 28 17:54:21 some-switch MaintenanceMode: %MMODE-5-MAINT_UNIT_STATE_CHANGE: Maintenance unit state changed for unit MAINT-UNIT. Old State maintenanceModeExit, New State active

tests/config/eos/MAINTENANCE_MODE_ENDED/default/yang.json

@@ -0,0 +1,29 @@
+{
+  "error": "MAINTENANCE_MODE_ENDED",
+  "host": "some-switch",
+  "ip": "127.0.0.1",
+  "timestamp": 1646070861,
+  "yang_message": {
+    "notification-messages": {
+      "notification-message": {
+        "message-text": "maintenance ended"
+      }
+    }
+  },
+  "message_details": {
+    "date": "Feb 28",
+    "time": "17:54:21",
+    "host": "some-switch",
+    "processName": "MaintenanceMode",
+    "tag": "MMODE-5-MAINT_UNIT_STATE_CHANGE",
+    "pri": "100",
+    "message": ": Maintenance unit state changed for unit MAINT-UNIT. Old State maintenanceModeExit, New State active",
+    "facility": 12,
+    "severity": 4
+  },
+  "yang_model": "ietf-notification-messages",
+  "os": "eos",
+  "facility": 12,
+  "severity": 4,
+  "state": 0
+}

tests/config/eos/MAINTENANCE_MODE_STARTED/default/syslog.msg

@@ -0,0 +1 @@
+<100>Feb 28 17:54:21 some-switch MaintenanceMode: %MMODE-5-MAINT_UNIT_STATE_CHANGE: Maintenance unit state changed for unit MAINT-UNIT. Old State maintenanceModeEnter, New State underMaintenance

tests/config/eos/MAINTENANCE_MODE_STARTED/default/yang.json

@@ -0,0 +1,29 @@
+{
+  "error": "MAINTENANCE_MODE_STARTED",
+  "host": "some-switch",
+  "ip": "127.0.0.1",
+  "timestamp": 1646070861,
+  "yang_message": {
+    "notification-messages": {
+      "notification-message": {
+        "message-text": "maintenance started"
+      }
+    }
+  },
+  "message_details": {
+    "date": "Feb 28",
+    "time": "17:54:21",
+    "host": "some-switch",
+    "processName": "MaintenanceMode",
+    "tag": "MMODE-5-MAINT_UNIT_STATE_CHANGE",
+    "pri": "100",
+    "message": ": Maintenance unit state changed for unit MAINT-UNIT. Old State maintenanceModeEnter, New State underMaintenance",
+    "facility": 12,
+    "severity": 4
+  },
+  "yang_model": "ietf-notification-messages",
+  "os": "eos",
+  "facility": 12,
+  "severity": 4,
+  "state": 1
+}