Add event api

Implements: blueprint support-inspector-sb-api Change-Id: I5760a6c3abea595f6bf64c16899677462680cc76
2017-01-16 16:54:44 +00:00 · 2017-01-16 16:54:44 +00:00 · 9c222514f8
commit 9c222514f8
parent 62c3ca273c
1 changed files with 154 additions and 0 deletions
--- a/specs/ocata/event-api.rst
+++ b/specs/ocata/event-api.rst
@ -0,0 +1,154 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=========
+Event API
+=========
+
+https://blueprints.launchpad.net/vitrage/+spec/support-inspector-sb-api
+
+This blueprint defines an API for sending events to Vitrage datasources.
+
+
+Problem description
+===================
+As a reference implementation to OPNFV Doctor Inspector project, Vitrage has
+to implement the Inspector SB API. This is a REST API that each monitoring
+service should call in order to push events to the Inspector.
+
+
+Proposed change
+===============
+
+New API will be added to allow sending events to the Vitrage datasources.
+The events will be sent to Oslo message bus, and will be consumed by the one of
+the datasource drivers according to the ``type`` property.
+
+For example, the Doctor datasource will handle events of type ``compute.host.down``,
+while the Nova instance datasource will handle events of type ``compute.instance.delete.start``.
+(Using this API for Nova is not a real use case, but can be used for debugging).
+
+For the Doctor datasource, the events will contain the details defined in the
+Doctor specification. Future datasources may also use this API in order to send
+their own events to Vitrage.
+
+
+REST API impact
+---------------
+
+POST /v1.0/event/
+^^^^^^^^^^^^^^^^^
+
+Post an event to Vitrage message queue, to be consumed by a datasource driver.
+
+Headers
+"""""""
+
+-  X-Auth-Token (string, required) - Keystone auth token
+-  Accept (string) - application/json
+-  User-Agent (String)
+-  Content-Type (String): application/json
+
+Path Parameters
+"""""""""""""""
+
+None.
+
+Query Parameters
+""""""""""""""""
+
+None.
+
+Request Body
+""""""""""""
+
+An event to be posted. Will contain the following fields:
+
+- time: a timestamp of the event. In case of a monitor event, should specify when the fault has occurred.
+- type: the type of the event.
+- details: a key-value map of metadata.
+
+A list of some potential details, copied from the Doctor SB API reference:
+
+- hostname: the hostname on which the event occurred.
+- source: the display name of reporter of this event. This is not limited to monitor, other entity can be specified such as ‘KVM’.
+- cause: description of the cause of this event which could be different from the type of this event.
+- severity: the severity of this event set by the monitor.
+- status: the status of target object in which error occurred.
+- monitorID: the ID of the monitor sending this event.
+- monitorEventID: the ID of the event in the monitor. This can be used by operator while tracking the monitor log.
+- relatedTo: the array of IDs which related to this event.
+
+Request Examples
+""""""""""""""""
+::
+
+    POST /v1/event/
+    Host: 135.248.18.122:8999
+    User-Agent: keystoneauth1/2.3.0 python-requests/2.9.1 CPython/2.7.6
+    Content-Type: application/json
+    Accept: application/json
+    X-Auth-Token: 2b8882ba2ec44295bf300aecb2caa4f7
+
+
+::
+
+    {
+        'event': {
+            'time': '2016-04-12T08:00:00',
+            'type': 'compute.host.down',
+            'details': {
+                'hostname': 'compute-1',
+                'source': 'sample_monitor',
+                'cause': 'link-down',
+                'severity': 'critical',
+                'status': 'down',
+                'monitor_id': 'monitor-1',
+                'monitor_event_id': '123',
+            }
+        }
+    }
+
+Response
+""""""""
+
+Status code
+~~~~~~~~~~~
+
+-  200 - OK
+-  400 - Bad request
+
+Response Body
+~~~~~~~~~~~~~
+
+Returns an empty response body if the request was OK.
+Otherwise returns a detailed error message (e.g. 'missing time parameter').
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  ifat-afek
+
+Testing
+=======
+
+The changes will be tested by unit tests and tempest tests.
+
+Documentation Impact
+====================
+The new api should be documented
+
+References
+==========
+
+- https://wiki.opnfv.org/display/doctor/Doctor+Home
+- http://artifacts.opnfv.org/doctor/docs/requirements/05-implementation.html
+  section 4.5.6
+- https://blueprints.launchpad.net/vitrage/+spec/doctor-datasource