1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
# AT&T Vendor Event Listener Service - Test Collector - User Guide
# ===================================================================
# Copyright © 2017 AT&T Intellectual Property. All rights reserved.
# ===================================================================
# 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.
# ============LICENSE_END============================================
#
# ECOMP and OpenECOMP are trademarks
# and service marks of AT&T Intellectual Property.
Introduction
============
Background
----------
This document describes how to use the Test Collector application to simulate
the service API described in "AT&T Service Specification, Service:
Vendor Event Listener Revision 2.11, 16-Sep-2016".
Purpose
-------
This User Guide is intended to enable the reader to understand how
the Test Collector can be used to verify the operation of applications
supporting the Vendor Event Listener API.
Realization
===========
The realization of the Test Collector is a Python script which acts as a
server for the Vendor Event Listener API. It uses [jsonschema](https://pypi.python.org/pypi/jsonschema)
in order to validate the received JSON events against AT&T's published
schema for the API.
The overall system architecture is shown in Figure 1 and comprises
three key deliverables:
* The web-application itself.
* A Backend service.
* A validating test collector application.
The Test Collector is described in more detail in the
following sections. The other two components are described in a separate
documents:
* Reference VNF User Guide
* Reference VNF Application Note
Figure 1: Realization Architecture
Note that items shown in green in the diagram are existing AT&T
systems and do not form part of the delivery.
Validating Collector
--------------------
The validating collector provides a basic test capability for
the Reference VNF. The application implements the Vendor Event
Listener API providing:
- Logging of new requests.
- Validating requests against the published schema.
- Validating the credentials provided in the request.
- Responding with a 202 Accepted for valid requests.
- Test Control endpoint allowing a test harness or user to set a pending
commandList, to be sent in response to the next event received.
- Responding with a 202 Accepted plus a pending commandList.
- Responding with a 401 Unauthorized error response-code and a JSON
exception response for failed authentication.
It is intended to be used in environments where the "real" AT&T
Vendor Event Listener service is not available in order to test the
Reference VNF or, indeed, any other software which needs to send
events to a server.
Using the Validating Collector
==============================
The test collector can be run manually, either on a Linux platform
or a Windows PC. It is invoked with a number of command-line
arguments:
```
C:> python collector.py --config <file>
--section <section>
--verbose
```
Where:
- **config** defines the path to the config file to be used.
- **section** defines the section in the config file to be used.
- **verbose** controls the level of logging to be generated.
Wherever you chose to run the Test Collector, note that the
configuration of the backend service running on the VM generating
the events has to match so that the events generated by the backend
service are sent to the correct location and the Test Collector is
listening on the correct ports and URLs. The relevant section of the
Test Collector config file is:
```
#------------------------------------------------------------------------------
# Details of the Vendor Event Listener REST service.
#
# REST resources are defined with respect to a ServerRoot:
# ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
#
# REST resources are of the form:
# * {ServerRoot}/eventListener/v{apiVersion}
# * {ServerRoot}/eventListener/v{apiVersion}/{topicName}
# * {ServerRoot}/eventListener/v{apiVersion}/eventBatch
# * {ServerRoot}/eventListener/v{apiVersion}/clientThrottlingState
#
# The "vel\_topic\_name" parameter is used as the "topicName" element in the path
# and may be empty.
#
# Note that the path, if present, should have no leading "/" but should have a
# training "/".
#------------------------------------------------------------------------------
vel_domain = 127.0.0.1
vel_port = 30000
vel_path = vendor_event_listener/
vel_username = Alice
vel_password = This isn't very secure!
vel_topic_name = example_vnf
```
The equivalent section of the backend service's configuration has to
match, or the equivalent parameters injected in the VM by the
OpenStack metadata service have to match.
When events are sent from the web application, the results of the
validation will be displayed on stdout and be written to the log
file specified in the configuration file.
For example: A Fault event failing to validate:
```
<machine name>; - - [29/Feb/2016 10:58:28] "POST
/vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1" 204 0
Event is not valid against schema! 'eventSeverity' is a required
property
Failed validating 'required' in
schema['properties']['event']['properties']['faultFields']:
{'description': 'fields specific to fault events',
'properties': {'alarmAdditionalInformation': {'description':'additional alarm information',
'items': {'$ref': '#/definitions/field'},
'type': 'array'},
'alarmCondition': {'description': 'alarm condition reportedby the device',
'type': 'string'},
'alarmInterfaceA': {'description': 'card, port, channel or interface name of the device generating the alarm',
'type': 'string'},
'eventSeverity': {'description': 'event severity or priority',
'enum': ['CRITICAL',
'MAJOR',
'MINOR',
'WARNING',
'NORMAL'],
'type': 'string'},
'eventSourceType': {'description': 'type of event source',
'enum': ['other(0)',
'router(1)',
'switch(2)',
'host(3)',
'card(4)',
'port(5)',
'slotThreshold(6)',
'portThreshold(7)',
'virtualMachine(8)'],
'type': 'string'},
'faultFieldsVersion': {'description': 'version of the faultFields block',
'type': 'number'},
'specificProblem': {'description': 'short description of the alarm or problem',
'type': 'string'},
'vfStatus': {'description': 'virtual function status enumeration',
'enum': ['Active',
'Idle',
'Preparing to terminate',
'Ready to terminate',
'Requesting termination'],
'type': 'string'}},
'required': ['alarmCondition',
'eventSeverity',
'eventSourceType',
'specificProblem',
'vfStatus'],
'type': 'object'}
On instance['event']['faultFields']:
{'alarmAdditionalInformation': [{'name': 'extra information',
'value': '2'},
{'name': 'more information',
'value': '1'}],
'alarmCondition': 'alarm condition 1',
'eventSourceType': 'virtualMachine(8)',
'faultFieldsVersion': 1,
'specificProblem': 'problem 1',
'vfStatus': 'Active'}
Bad JSON body decoded:
{
"event": {
"commonEventHeader": {
"domain": "fault",
"eventId": "6",
"eventType": "event type 1",
"functionalRole": "unknown",
"lastEpochMicrosec": 1456743510381000.0,
"priority": "Normal",
"reportingEntityId": "Not in OpenStack",
"reportingEntityName": "Not in OpenStack Environment",
"sequence": 0,
"sourceId": "Not in OpenStack",
"sourceName": "Not in OpenStack Environment",
"startEpochMicrosec": 1456743510381000.0,
"version": 1
},
"faultFields": {
"alarmAdditionalInformation": [
{
"name": "extra information",
"value": "2"
},
{
"name": "more information",
"value": "1"
}
],
"alarmCondition": "alarm condition 1",
"eventSourceType": "virtualMachine(8)",
"faultFieldsVersion": 1,
"specificProblem": "problem 1",
"vfStatus": "Active"
}
}
}
```
Test Control Interface
----------------------
The test collector will accept any valid commandList on the Test Control interface,
and will store it until the next event is received at the collector.
At this point, it will send it to the event sender, and discard the pending commandList.
For example, a POST of the following JSON will result in a measurement interval change
command being sent to the sender of the next event.
```
{
"commandList": [
{
"command": {
"commandType": "measurementIntervalChange",
"measurementInterval": 60
}
}
]
}
```
A python script "test_control.py" provides an example of commandList injection,
and contains various functions to generate example command lists.
The test control script can be run manually, either on a Linux platform or a Windows PC.
It is invoked with optional command-line arguments for the fqdn and port number of the
test collector to be controlled:
```
C:> python test_control.py --fqdn 127.0.0.1 --port 30000
```
|
