Event API

Event 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.

  • X-Auth-Token (string, required) - Keystone auth token

  • Accept (string) - application/json

  • User-Agent (String)

  • Content-Type (String): application/json

Path Parameters


Query Parameters


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/
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',
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’).



Primary assignee:



The changes will be tested by unit tests and tempest tests.

Documentation Impact

The new api should be documented

Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.