Merge pull request #369 from napalm-automation/counter-part-state

Add a simplified way to have counter-part messages

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
+}