openstack/monasca-events-api
Code Issues Proposed changes

Monasca-events-api spec documentation

Browse Source 
Provide new endpoint to monasca-events-api.
Endpoint accept events in a bulk mode.
Provide HTTP response codes and examples about request
body.

Story: 2001112
Task: 4803

Change-Id: I18d9f4ec543c76bfe1311ed1ee940827d4162298
This commit is contained in:
Artur Basiak 2017-07-11 06:18:57 +02:00
parent ae9f8255db
commit 3bfd48f178
7 changed files with 423 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
api-ref/source/events.inc Normal file
View File

@ -0,0 +1,73 @@
.. -*- rst -*-
..
Copyright 2017 Fujitsu LIMITED
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
======
Events
======
Accept events send from e.g. monasca-events-agent. Events are JSON objects collected from
the OpenStack message bus. Events, also called notifications, are emitted by the OpenStack Cloud core components.
Monasca-events-api accepts versioned notifications according to the `OpenStack
documentation <https://docs.openstack.org/nova/latest/notifications.html#versioned-notifications>`_.
Send Events
===========
.. rest_method:: POST /v1.0/events
Accepts multiple events (i.e. bulk mode). Each event can be enriched with a set of dimensions
with information about the notification service source (Nova, Glance, etc.), or the message bus source
(topic name). A single event in bulk mode must also contain the project_id field which is required.
Each event can be enriched with a set of dimensions. Dimensions can contain additional information,
for example, about the topic from which the event was read or the hostname from which it was
generated.
.. rest_status_code:: success http_codes.yaml
- 204
.. rest_status_code:: error http_codes.yaml
- 400
- 401
- 411
- 413
- 422: event_no_project
- 422: event_no_event
- 422: bad_envelope
- 503
Request
-------
.. rest_parameters:: parameters.yaml
- events: events
**Example 1: Request with a single event**
.. literalinclude:: ../../doc/api-samples/v1/req_simple_event.json
:language: javascript
**Example 2:Request with multiple events**
.. literalinclude:: ../../doc/api-samples/v1/req_multiple_events.json
:language: javascript
Response
========
No body content is returned on successful POST.

43
api-ref/source/http_codes.yaml Normal file
View File

@ -0,0 +1,43 @@
# Copyright 2017 Fujitsu LIMITED
200:
ea_up: |
API is up and running. All peripherial components are accesible.
204:
default: |
Normal response code, the request was successfully processed.
ea_up: |
API is up and running.
400:
default: |
Bad request.
401:
default: |
Unauthorized. User must authenticate before making a request.
403:
default: |
Policy does not allow current user to do this operation.
411:
default: |
Content-Length header was not found in request.
413:
default: |
Sent body is too large to be processed.
422:
default: |
Sent data could not be processed properly.
event_no_project:
Event property must have project_id field.
event_no_event: |
Event property must have event payload object.
bad_envelope: |
Failed to create an envelope.
503:
default: |
The server is currently unable to handle the request due to a
temporary overload or scheduled maintenance. This will likely be
alleviated after some delay.
no_health: |
API is running but there are problems with peripheral components.

9
api-ref/source/index.rst
View File

@ -15,8 +15,11 @@
License for the specific language governing permissions and limitations
under the License.
===========================
Monasca Events Service APIs
===========================
==============================
Monitoring Events Service API
==============================
.. rest_expand_all:
.. include:: events.inc

16
api-ref/source/parameters.yaml Normal file
View File

@ -0,0 +1,16 @@
# Copyright 2017 Fujitsu LIMITED
# body params
events:
description: |
Array containing the events.
in: body
required: true
type: array
timestamp:
description: |
The timestamp recorded by the agent while sending the events object to the API.
The timestamp should include the timezone, e.g.: 2012-10-29T13:42:11Z+0200 .
in: body
required: true
type: string

187
doc/api-samples/v1/req_multiple_events.json Normal file
View File

@ -0,0 +1,187 @@
{
"timestamp": "2012-10-29T13:42:11Z+0200",
"events": [
{
"dimensions": {
"service": "compute",
"topic": "notification.sample",
"hostname": "nova-compute:compute"
},
"project_id": "6f70656e737461636b20342065766572",
"event": {
"event_type": "instance.reboot.end",
"payload": {
"nova_object.data": {
"architecture": "x86_64",
"availability_zone": "nova",
"created_at": "2012-10-29T13:42:11Z",
"deleted_at": null,
"display_name": "some-server",
"display_description": "some-server",
"fault": null,
"host": "compute",
"host_name": "some-server",
"ip_addresses": [
{
"nova_object.name": "IpPayload",
"nova_object.namespace": "nova",
"nova_object.version": "1.0",
"nova_object.data": {
"mac": "fa:16:3e:4c:2c:30",
"address": "192.168.1.3",
"port_uuid": "ce531f90-199f-48c0-816c-13e38010b442",
"meta": {},
"version": 4,
"label": "private-network",
"device_name": "tapce531f90-19"
}
}
],
"key_name": "my-key",
"auto_disk_config": "MANUAL",
"kernel_id": "",
"launched_at": "2012-10-29T13:42:11Z",
"image_uuid": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
"metadata": {},
"locked": false,
"node": "fake-mini",
"os_type": null,
"progress": 0,
"ramdisk_id": "",
"reservation_id": "r-npxv0e40",
"state": "active",
"task_state": null,
"power_state": "running",
"tenant_id": "6f70656e737461636b20342065766572",
"terminated_at": null,
"flavor": {
"nova_object.name": "FlavorPayload",
"nova_object.data": {
"flavorid": "a22d5517-147c-4147-a0d1-e698df5cd4e3",
"name": "test_flavor",
"projects": null,
"root_gb": 1,
"vcpus": 1,
"ephemeral_gb": 0,
"memory_mb": 512,
"disabled": false,
"rxtx_factor": 1.0,
"extra_specs": {
"hw:watchdog_action": "disabled"
},
"swap": 0,
"is_public": true,
"vcpu_weight": 0
},
"nova_object.version": "1.3",
"nova_object.namespace": "nova"
},
"user_id": "fake",
"uuid": "178b0921-8f85-4257-88b6-2e743b5a975c"
},
"nova_object.name": "InstanceActionPayload",
"nova_object.namespace": "nova",
"nova_object.version": "1.3"
},
"priority": "INFO",
"publisher_id": "nova-compute:compute"
}
},
{
"dimensions": {
"service": "compute",
"topic": "notification.error",
"hostname": "nova-compute:compute"
},
"project_id": "6f70656e737461636b20342065766572",
"event": {
"priority": "ERROR",
"payload": {
"nova_object.name": "InstanceActionPayload",
"nova_object.data": {
"state": "active",
"availability_zone": "nova",
"key_name": "my-key",
"kernel_id": "",
"host_name": "some-server",
"progress": 0,
"task_state": "rebuilding",
"deleted_at": null,
"architecture": null,
"auto_disk_config": "MANUAL",
"ramdisk_id": "",
"locked": false,
"created_at": "2012-10-29T13:42:11Z",
"host": "compute",
"display_name": "some-server",
"os_type": null,
"metadata": {},
"ip_addresses": [
{
"nova_object.name": "IpPayload",
"nova_object.data": {
"device_name": "tapce531f90-19",
"port_uuid": "ce531f90-199f-48c0-816c-13e38010b442",
"address": "192.168.1.3",
"version": 4,
"meta": {},
"label": "private-network",
"mac": "fa:16:3e:4c:2c:30"
},
"nova_object.version": "1.0",
"nova_object.namespace": "nova"
}
],
"power_state": "running",
"display_description": "some-server",
"uuid": "5fafd989-4043-44b4-8acc-907e847f4b70",
"flavor": {
"nova_object.name": "FlavorPayload",
"nova_object.data": {
"disabled": false,
"ephemeral_gb": 0,
"extra_specs": {
"hw:watchdog_action": "disabled"
},
"flavorid": "a22d5517-147c-4147-a0d1-e698df5cd4e3",
"is_public": true,
"memory_mb": 512,
"name": "test_flavor",
"projects": null,
"root_gb": 1,
"rxtx_factor": 1.0,
"swap": 0,
"vcpu_weight": 0,
"vcpus": 1
},
"nova_object.version": "1.3",
"nova_object.namespace": "nova"
},
"reservation_id": "r-pfiic52h",
"terminated_at": null,
"tenant_id": "6f70656e737461636b20342065766572",
"node": "fake-mini",
"launched_at": "2012-10-29T13:42:11Z",
"user_id": "fake",
"image_uuid": "a2459075-d96c-40d5-893e-577ff92e721c",
"fault": {
"nova_object.name": "ExceptionPayload",
"nova_object.data": {
"module_name": "nova.tests.functional.notification_sample_tests.test_instance",
"exception_message": "Insufficient compute resources: fake-resource.",
"function_name": "_compute_resources_unavailable",
"exception": "ComputeResourcesUnavailable"
},
"nova_object.version": "1.0",
"nova_object.namespace": "nova"
}
},
"nova_object.version": "1.3",
"nova_object.namespace": "nova"
},
"publisher_id": "nova-compute:compute",
"event_type": "instance.rebuild.error"
}
}
]
}

91
doc/api-samples/v1/req_simple_event.json Normal file
View File

@ -0,0 +1,91 @@
{
"timestamp": "2012-10-29T13:42:11Z+0200",
"events": [
{
"dimensions": {
"service": "compute",
"topic": "notification.sample",
"hostname": "nova-compute:compute"
},
"project_id": "6f70656e737461636b20342065766572",
"event": {
"event_type": "instance.reboot.end",
"payload": {
"nova_object.data": {
"architecture": "x86_64",
"availability_zone": "nova",
"created_at": "2012-10-29T13:42:11Z",
"deleted_at": null,
"display_name": "some-server",
"display_description": "some-server",
"fault": null,
"host": "compute",
"host_name": "some-server",
"ip_addresses": [
{
"nova_object.name": "IpPayload",
"nova_object.namespace": "nova",
"nova_object.version": "1.0",
"nova_object.data": {
"mac": "fa:16:3e:4c:2c:30",
"address": "192.168.1.3",
"port_uuid": "ce531f90-199f-48c0-816c-13e38010b442",
"meta": {},
"version": 4,
"label": "private-network",
"device_name": "tapce531f90-19"
}
}
],
"key_name": "my-key",
"auto_disk_config": "MANUAL",
"kernel_id": "",
"launched_at": "2012-10-29T13:42:11Z",
"image_uuid": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
"metadata": {},
"locked": false,
"node": "fake-mini",
"os_type": null,
"progress": 0,
"ramdisk_id": "",
"reservation_id": "r-npxv0e40",
"state": "active",
"task_state": null,
"power_state": "running",
"tenant_id": "6f70656e737461636b20342065766572",
"terminated_at": null,
"flavor": {
"nova_object.name": "FlavorPayload",
"nova_object.data": {
"flavorid": "a22d5517-147c-4147-a0d1-e698df5cd4e3",
"name": "test_flavor",
"projects": null,
"root_gb": 1,
"vcpus": 1,
"ephemeral_gb": 0,
"memory_mb": 512,
"disabled": false,
"rxtx_factor": 1.0,
"extra_specs": {
"hw:watchdog_action": "disabled"
},
"swap": 0,
"is_public": true,
"vcpu_weight": 0
},
"nova_object.version": "1.3",
"nova_object.namespace": "nova"
},
"user_id": "fake",
"uuid": "178b0921-8f85-4257-88b6-2e743b5a975c"
},
"nova_object.name": "InstanceActionPayload",
"nova_object.namespace": "nova",
"nova_object.version": "1.3"
},
"priority": "INFO",
"publisher_id": "nova-compute:compute"
}
}
]
}

7
releasenotes/notes/spec_documentation-5cc534fcd1a293da.yaml Normal file
View File

@ -0,0 +1,7 @@
---
features:
- |
Add documentation for the /v1.0/events edpoint.
An endpoint accepts requests from the peripheral agents.
Each request contains one or more events objects that are
processed by the events pipeline.