Browse Source

Monasca-events-api spec documentation

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
Artur Basiak 1 year ago
parent
commit
3bfd48f178

+ 73
- 0
api-ref/source/events.inc View File

@@ -0,0 +1,73 @@
1
+.. -*- rst -*-
2
+..
3
+      Copyright 2017 Fujitsu LIMITED
4
+
5
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
6
+      not use this file except in compliance with the License. You may obtain
7
+      a copy of the License at
8
+
9
+          http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+      Unless required by applicable law or agreed to in writing, software
12
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
+      License for the specific language governing permissions and limitations
15
+      under the License.
16
+
17
+======
18
+Events
19
+======
20
+
21
+Accept events send from e.g. monasca-events-agent. Events are JSON objects collected from
22
+the OpenStack message bus. Events, also called notifications, are emitted by the OpenStack Cloud core components.
23
+Monasca-events-api accepts versioned notifications according to the `OpenStack
24
+documentation <https://docs.openstack.org/nova/latest/notifications.html#versioned-notifications>`_.
25
+
26
+Send Events
27
+===========
28
+
29
+.. rest_method:: POST /v1.0/events
30
+
31
+Accepts multiple events (i.e. bulk mode). Each event can be enriched with a set of dimensions
32
+with information about the notification service source (Nova, Glance, etc.), or the message bus source
33
+(topic name). A single event in bulk mode must also contain the project_id field which is required.
34
+Each event can be enriched with a set of dimensions. Dimensions can contain additional information,
35
+for example, about the topic from which the event was read or the hostname from which it was
36
+generated.
37
+
38
+.. rest_status_code:: success http_codes.yaml
39
+
40
+    - 204
41
+
42
+.. rest_status_code:: error http_codes.yaml
43
+
44
+    - 400
45
+    - 401
46
+    - 411
47
+    - 413
48
+    - 422: event_no_project
49
+    - 422: event_no_event
50
+    - 422: bad_envelope
51
+    - 503
52
+
53
+Request
54
+-------
55
+
56
+ .. rest_parameters:: parameters.yaml
57
+
58
+    - events: events
59
+
60
+**Example 1: Request with a single event**
61
+
62
+.. literalinclude:: ../../doc/api-samples/v1/req_simple_event.json
63
+   :language: javascript
64
+
65
+**Example 2:Request with multiple events**
66
+
67
+.. literalinclude:: ../../doc/api-samples/v1/req_multiple_events.json
68
+   :language: javascript
69
+
70
+Response
71
+========
72
+
73
+No body content is returned on successful POST.

+ 43
- 0
api-ref/source/http_codes.yaml View File

@@ -0,0 +1,43 @@
1
+# Copyright 2017 Fujitsu LIMITED
2
+
3
+200:
4
+  ea_up: |
5
+    API is up and running. All peripherial components are accesible.
6
+204:
7
+  default: |
8
+    Normal response code, the request was successfully processed.
9
+  ea_up: |
10
+    API is up and running.
11
+
12
+400:
13
+  default: |
14
+    Bad request.
15
+401:
16
+  default: |
17
+    Unauthorized. User must authenticate before making a request.
18
+403:
19
+  default: |
20
+    Policy does not allow current user to do this operation.
21
+411:
22
+  default: |
23
+    Content-Length header was not found in request.
24
+413:
25
+  default: |
26
+    Sent body is too large to be processed.
27
+422:
28
+  default: |
29
+    Sent data could not be processed properly.
30
+  event_no_project:
31
+    Event property must have project_id field.
32
+  event_no_event: |
33
+    Event property must have event payload object.
34
+  bad_envelope: |
35
+    Failed to create an envelope.
36
+
37
+503:
38
+  default: |
39
+    The server is currently unable to handle the request due to a
40
+    temporary overload or scheduled maintenance. This will likely be
41
+    alleviated after some delay.
42
+  no_health: |
43
+    API is running but there are problems with peripheral components.

+ 6
- 3
api-ref/source/index.rst View File

@@ -15,8 +15,11 @@
15 15
       License for the specific language governing permissions and limitations
16 16
       under the License.
17 17
 
18
-===========================
19
-Monasca Events Service APIs
20
-===========================
18
+==============================
19
+Monitoring Events Service API
20
+==============================
21 21
 
22 22
 .. rest_expand_all:
23
+
24
+.. include:: events.inc
25
+

+ 16
- 0
api-ref/source/parameters.yaml View File

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

+ 187
- 0
doc/api-samples/v1/req_multiple_events.json View File

@@ -0,0 +1,187 @@
1
+{
2
+  "timestamp": "2012-10-29T13:42:11Z+0200",
3
+  "events": [
4
+    {
5
+      "dimensions": {
6
+        "service": "compute",
7
+        "topic": "notification.sample",
8
+        "hostname": "nova-compute:compute"
9
+      },
10
+      "project_id": "6f70656e737461636b20342065766572",
11
+      "event": {
12
+        "event_type": "instance.reboot.end",
13
+        "payload": {
14
+          "nova_object.data": {
15
+            "architecture": "x86_64",
16
+            "availability_zone": "nova",
17
+            "created_at": "2012-10-29T13:42:11Z",
18
+            "deleted_at": null,
19
+            "display_name": "some-server",
20
+            "display_description": "some-server",
21
+            "fault": null,
22
+            "host": "compute",
23
+            "host_name": "some-server",
24
+            "ip_addresses": [
25
+              {
26
+                "nova_object.name": "IpPayload",
27
+                "nova_object.namespace": "nova",
28
+                "nova_object.version": "1.0",
29
+                "nova_object.data": {
30
+                  "mac": "fa:16:3e:4c:2c:30",
31
+                  "address": "192.168.1.3",
32
+                  "port_uuid": "ce531f90-199f-48c0-816c-13e38010b442",
33
+                  "meta": {},
34
+                  "version": 4,
35
+                  "label": "private-network",
36
+                  "device_name": "tapce531f90-19"
37
+                }
38
+              }
39
+            ],
40
+            "key_name": "my-key",
41
+            "auto_disk_config": "MANUAL",
42
+            "kernel_id": "",
43
+            "launched_at": "2012-10-29T13:42:11Z",
44
+            "image_uuid": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
45
+            "metadata": {},
46
+            "locked": false,
47
+            "node": "fake-mini",
48
+            "os_type": null,
49
+            "progress": 0,
50
+            "ramdisk_id": "",
51
+            "reservation_id": "r-npxv0e40",
52
+            "state": "active",
53
+            "task_state": null,
54
+            "power_state": "running",
55
+            "tenant_id": "6f70656e737461636b20342065766572",
56
+            "terminated_at": null,
57
+            "flavor": {
58
+              "nova_object.name": "FlavorPayload",
59
+              "nova_object.data": {
60
+                "flavorid": "a22d5517-147c-4147-a0d1-e698df5cd4e3",
61
+                "name": "test_flavor",
62
+                "projects": null,
63
+                "root_gb": 1,
64
+                "vcpus": 1,
65
+                "ephemeral_gb": 0,
66
+                "memory_mb": 512,
67
+                "disabled": false,
68
+                "rxtx_factor": 1.0,
69
+                "extra_specs": {
70
+                  "hw:watchdog_action": "disabled"
71
+                },
72
+                "swap": 0,
73
+                "is_public": true,
74
+                "vcpu_weight": 0
75
+              },
76
+              "nova_object.version": "1.3",
77
+              "nova_object.namespace": "nova"
78
+            },
79
+            "user_id": "fake",
80
+            "uuid": "178b0921-8f85-4257-88b6-2e743b5a975c"
81
+          },
82
+          "nova_object.name": "InstanceActionPayload",
83
+          "nova_object.namespace": "nova",
84
+          "nova_object.version": "1.3"
85
+        },
86
+        "priority": "INFO",
87
+        "publisher_id": "nova-compute:compute"
88
+      }
89
+    },
90
+    {
91
+      "dimensions": {
92
+        "service": "compute",
93
+        "topic": "notification.error",
94
+        "hostname": "nova-compute:compute"
95
+      },
96
+      "project_id": "6f70656e737461636b20342065766572",
97
+      "event": {
98
+        "priority": "ERROR",
99
+        "payload": {
100
+          "nova_object.name": "InstanceActionPayload",
101
+          "nova_object.data": {
102
+            "state": "active",
103
+            "availability_zone": "nova",
104
+            "key_name": "my-key",
105
+            "kernel_id": "",
106
+            "host_name": "some-server",
107
+            "progress": 0,
108
+            "task_state": "rebuilding",
109
+            "deleted_at": null,
110
+            "architecture": null,
111
+            "auto_disk_config": "MANUAL",
112
+            "ramdisk_id": "",
113
+            "locked": false,
114
+            "created_at": "2012-10-29T13:42:11Z",
115
+            "host": "compute",
116
+            "display_name": "some-server",
117
+            "os_type": null,
118
+            "metadata": {},
119
+            "ip_addresses": [
120
+              {
121
+                "nova_object.name": "IpPayload",
122
+                "nova_object.data": {
123
+                  "device_name": "tapce531f90-19",
124
+                  "port_uuid": "ce531f90-199f-48c0-816c-13e38010b442",
125
+                  "address": "192.168.1.3",
126
+                  "version": 4,
127
+                  "meta": {},
128
+                  "label": "private-network",
129
+                  "mac": "fa:16:3e:4c:2c:30"
130
+                },
131
+                "nova_object.version": "1.0",
132
+                "nova_object.namespace": "nova"
133
+              }
134
+            ],
135
+            "power_state": "running",
136
+            "display_description": "some-server",
137
+            "uuid": "5fafd989-4043-44b4-8acc-907e847f4b70",
138
+            "flavor": {
139
+              "nova_object.name": "FlavorPayload",
140
+              "nova_object.data": {
141
+                "disabled": false,
142
+                "ephemeral_gb": 0,
143
+                "extra_specs": {
144
+                  "hw:watchdog_action": "disabled"
145
+                },
146
+                "flavorid": "a22d5517-147c-4147-a0d1-e698df5cd4e3",
147
+                "is_public": true,
148
+                "memory_mb": 512,
149
+                "name": "test_flavor",
150
+                "projects": null,
151
+                "root_gb": 1,
152
+                "rxtx_factor": 1.0,
153
+                "swap": 0,
154
+                "vcpu_weight": 0,
155
+                "vcpus": 1
156
+              },
157
+              "nova_object.version": "1.3",
158
+              "nova_object.namespace": "nova"
159
+            },
160
+            "reservation_id": "r-pfiic52h",
161
+            "terminated_at": null,
162
+            "tenant_id": "6f70656e737461636b20342065766572",
163
+            "node": "fake-mini",
164
+            "launched_at": "2012-10-29T13:42:11Z",
165
+            "user_id": "fake",
166
+            "image_uuid": "a2459075-d96c-40d5-893e-577ff92e721c",
167
+            "fault": {
168
+              "nova_object.name": "ExceptionPayload",
169
+              "nova_object.data": {
170
+                "module_name": "nova.tests.functional.notification_sample_tests.test_instance",
171
+                "exception_message": "Insufficient compute resources: fake-resource.",
172
+                "function_name": "_compute_resources_unavailable",
173
+                "exception": "ComputeResourcesUnavailable"
174
+              },
175
+              "nova_object.version": "1.0",
176
+              "nova_object.namespace": "nova"
177
+            }
178
+          },
179
+          "nova_object.version": "1.3",
180
+          "nova_object.namespace": "nova"
181
+        },
182
+        "publisher_id": "nova-compute:compute",
183
+        "event_type": "instance.rebuild.error"
184
+      }
185
+    }
186
+  ]
187
+}

+ 91
- 0
doc/api-samples/v1/req_simple_event.json View File

@@ -0,0 +1,91 @@
1
+{
2
+  "timestamp": "2012-10-29T13:42:11Z+0200",
3
+  "events": [
4
+    {
5
+      "dimensions": {
6
+        "service": "compute",
7
+        "topic": "notification.sample",
8
+        "hostname": "nova-compute:compute"
9
+      },
10
+      "project_id": "6f70656e737461636b20342065766572",
11
+      "event": {
12
+        "event_type": "instance.reboot.end",
13
+        "payload": {
14
+          "nova_object.data": {
15
+            "architecture": "x86_64",
16
+            "availability_zone": "nova",
17
+            "created_at": "2012-10-29T13:42:11Z",
18
+            "deleted_at": null,
19
+            "display_name": "some-server",
20
+            "display_description": "some-server",
21
+            "fault": null,
22
+            "host": "compute",
23
+            "host_name": "some-server",
24
+            "ip_addresses": [
25
+              {
26
+                "nova_object.name": "IpPayload",
27
+                "nova_object.namespace": "nova",
28
+                "nova_object.version": "1.0",
29
+                "nova_object.data": {
30
+                  "mac": "fa:16:3e:4c:2c:30",
31
+                  "address": "192.168.1.3",
32
+                  "port_uuid": "ce531f90-199f-48c0-816c-13e38010b442",
33
+                  "meta": {},
34
+                  "version": 4,
35
+                  "label": "private-network",
36
+                  "device_name": "tapce531f90-19"
37
+                }
38
+              }
39
+            ],
40
+            "key_name": "my-key",
41
+            "auto_disk_config": "MANUAL",
42
+            "kernel_id": "",
43
+            "launched_at": "2012-10-29T13:42:11Z",
44
+            "image_uuid": "155d900f-4e14-4e4c-a73d-069cbf4541e6",
45
+            "metadata": {},
46
+            "locked": false,
47
+            "node": "fake-mini",
48
+            "os_type": null,
49
+            "progress": 0,
50
+            "ramdisk_id": "",
51
+            "reservation_id": "r-npxv0e40",
52
+            "state": "active",
53
+            "task_state": null,
54
+            "power_state": "running",
55
+            "tenant_id": "6f70656e737461636b20342065766572",
56
+            "terminated_at": null,
57
+            "flavor": {
58
+              "nova_object.name": "FlavorPayload",
59
+              "nova_object.data": {
60
+                "flavorid": "a22d5517-147c-4147-a0d1-e698df5cd4e3",
61
+                "name": "test_flavor",
62
+                "projects": null,
63
+                "root_gb": 1,
64
+                "vcpus": 1,
65
+                "ephemeral_gb": 0,
66
+                "memory_mb": 512,
67
+                "disabled": false,
68
+                "rxtx_factor": 1.0,
69
+                "extra_specs": {
70
+                  "hw:watchdog_action": "disabled"
71
+                },
72
+                "swap": 0,
73
+                "is_public": true,
74
+                "vcpu_weight": 0
75
+              },
76
+              "nova_object.version": "1.3",
77
+              "nova_object.namespace": "nova"
78
+            },
79
+            "user_id": "fake",
80
+            "uuid": "178b0921-8f85-4257-88b6-2e743b5a975c"
81
+          },
82
+          "nova_object.name": "InstanceActionPayload",
83
+          "nova_object.namespace": "nova",
84
+          "nova_object.version": "1.3"
85
+        },
86
+        "priority": "INFO",
87
+        "publisher_id": "nova-compute:compute"
88
+      }
89
+    }
90
+  ]
91
+}

+ 7
- 0
releasenotes/notes/spec_documentation-5cc534fcd1a293da.yaml View File

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

Loading…
Cancel
Save