diff --git a/api-ref/source/events.inc b/api-ref/source/events.inc new file mode 100644 index 0000000..998f951 --- /dev/null +++ b/api-ref/source/events.inc @@ -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 `_. + +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. \ No newline at end of file diff --git a/api-ref/source/http_codes.yaml b/api-ref/source/http_codes.yaml new file mode 100644 index 0000000..b2c3eb0 --- /dev/null +++ b/api-ref/source/http_codes.yaml @@ -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. \ No newline at end of file diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index e2ee1d3..355f6c2 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -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 + diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 0000000..80b8e2e --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -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 \ No newline at end of file diff --git a/doc/api-samples/v1/req_multiple_events.json b/doc/api-samples/v1/req_multiple_events.json new file mode 100644 index 0000000..aa5a0e7 --- /dev/null +++ b/doc/api-samples/v1/req_multiple_events.json @@ -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" + } + } + ] +} \ No newline at end of file diff --git a/doc/api-samples/v1/req_simple_event.json b/doc/api-samples/v1/req_simple_event.json new file mode 100644 index 0000000..81c07e3 --- /dev/null +++ b/doc/api-samples/v1/req_simple_event.json @@ -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" + } + } + ] +} \ No newline at end of file diff --git a/releasenotes/notes/spec_documentation-5cc534fcd1a293da.yaml b/releasenotes/notes/spec_documentation-5cc534fcd1a293da.yaml new file mode 100644 index 0000000..be0bcfc --- /dev/null +++ b/releasenotes/notes/spec_documentation-5cc534fcd1a293da.yaml @@ -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.