Modify SNMP parsing config file

also add guide of how to support processing snmp events 
in alarm datasources

Change-Id: I74bb1f292938b42a70de5b22377d646e30802120
Implements: blueprint snmp-support
Signed-off-by: xupeipei <xu.peipei1@zte.com.cn>

doc/source/contributor/datasource-snmp-parsing-support.rst

@@ -0,0 +1,94 @@
+===========================================
+Adding Snmp Parsing Support in A Datasource
+===========================================
+
+Overview
+--------
+Vitrage provides a service to parse snmp traps and send the parsed
+event to RabbitMQ queue. To add the snmp trap to graph, there should be
+a datasource that gets the event and processes it.
+
+HOW to support Snmp Parsing Service in a datasource
+---------------------------------------------------
+In order to extend snmp support in datasources and configure it, users
+need to do the following:
+
+ 1. Add the snmp configuration file ``snmp_parsing_conf.yaml``. It configures
+    the oid that maps system information and event type when snmp parsing service
+    sends message.
+
+    **Example**
+
+    .. code:: python
+
+        - system_oid: 1.3.6.1.4.1.3902.4101.1.3.1.12
+          system: iaas_platform
+          event_type: vitrage.snmp.event
+
+ 2. Under snmp_parsing package ``__init__.py``, set ``oid_mapping`` property
+    to the path of snmp configuration file.
+
+ 3. In the driver class of your alarm datasource package, add an event type in the method
+    ``get_event_types``, which can be ``vitrage.snmp.event`` according to the config file
+    above.
+
+ 4. To transform parsed snmp trap to standard alarm event, need to add mapping of oid and
+    alarm property. Take mapping of oids and doctor event properties as an example.
+
+    **Example**
+
+    .. code:: python
+
+        OID_INFO = [('1.3.6.1.6.3.1.1.4.1.0', 'status'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.4', 'hostname'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.5', 'source'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.6', 'cause'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.7', 'severity'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.8', 'monitor_id'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.9', 'monitor_event_id'),
+                    ('1.3.6.1.4.1.3902.4101.1.3.1.12', 'system')]
+
+    The value of key '1.3.6.1.6.3.1.1.4.1.0' defines snmp trap's report or recover status,
+    and it's also an oid. There should be a mapping of this relationship.
+
+    **Example**
+
+    .. code:: python
+
+        ALARM_STATUS = {'1.3.6.1.4.1.3902.4101.1.4.1.1': 'up',
+                        '1.3.6.1.4.1.3902.4101.1.4.1.2': 'down'}
+
+
+ 5. The method ``enrich_event`` of the driver class is responsible for enriching given event.
+    The following code should be added at the beginning of ``enrich_event``. Note that the event
+    type ``vitrage.snmp.event`` here is consistent with the example of config file above.
+
+    **Example**
+
+    .. code:: python
+
+        if 'vitrage.snmp.event' == event_type:
+            self._transform_snmp_event(event)
+
+    The function ``_transform_snmp_event`` transform a parsed snmp trap to event of standard
+    format. An example is as follows. ``self.OID_INFO`` and ``self.ALARM_STATUS`` are defined
+    in the example above, and their content depends on SNMP trap organization.
+
+    **Example**
+
+    .. code:: python
+
+        def _transform_snmp_event(self, event):
+            src_details = event['details']
+            event_details = {}
+
+            for (oid, field_name) in self.OID_INFO:
+                if oid not in src_details.keys():
+                    continue
+                event_details[field_name] = self._get_oid_mapping_value(field_name, src_details[oid])
+            event['details'] = event_details
+
+        def _get_oid_mapping_value(self, field_name, value):
+            if field_name == 'status':
+                value = extract_field_value(self.ALARM_STATUS, value)
+            return value

doc/source/index.rst

@@ -91,3 +91,4 @@ Design Documents
    contributor/not_operator_support
    contributor/templates-loading
    contributor/vitrage-ha-and-history-vision
+   contributor/datasource-snmp-parsing-support

vitrage/snmp_parsing/properties.py

@@ -16,4 +16,4 @@
 class SnmpEventProperties(object):
     SYSTEM_OID = 'system_oid'
     SYSTEM = 'system'
-    DATASOURCE = 'datasource'
+    EVENT_TYPE = 'event_type'

vitrage/snmp_parsing/service.py

@@ -158,7 +158,7 @@ class SnmpParsingService(os_service.Service):
             conf_system = extract_field_value(mapping_info, SEProps.SYSTEM)
             if conf_system == extract_field_value(snmp_trap, system_oid):
                 LOG.debug('snmp trap mapped the system: %s.' % conf_system)
-                return extract_field_value(mapping_info, SEProps.DATASOURCE)
+                return extract_field_value(mapping_info, SEProps.EVENT_TYPE)
 
         LOG.error("Snmp trap does not contain system info!")
         return None

vitrage/tests/resources/snmp_parsing/snmp_parsing_conf.yaml

@@ -1,3 +1,3 @@
 - system_oid: 1.3.6.1.4.1.3902.4101.1.3.1.12
   system: Tecs Director
-  datasource: vitrage.snmp.event
+  event_type: vitrage.snmp.event