9c222514f8
Implements: blueprint support-inspector-sb-api Change-Id: I5760a6c3abea595f6bf64c16899677462680cc76
155 lines
4.0 KiB
ReStructuredText
155 lines
4.0 KiB
ReStructuredText
..
|
||
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
|