1 # AT&T Vendor Event Listener Service - Test Collector - User Guide
2 # ===================================================================
3 # Copyright © 2017 AT&T Intellectual Property. All rights reserved.
4 # ===================================================================
5 # Licensed under the Apache License, Version 2.0 (the "License");
6 # you may not use this file except in compliance with the License.
7 # You may obtain a copy of the License at
9 # http://www.apache.org/licenses/LICENSE-2.0
11 # Unless required by applicable law or agreed to in writing, software
12 # distributed under the License is distributed on an "AS IS" BASIS,
13 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 # See the License for the specific language governing permissions and
15 # limitations under the License.
16 # ============LICENSE_END============================================
18 # ECOMP and OpenECOMP are trademarks
19 # and service marks of AT&T Intellectual Property.
28 This document describes how to use the Test Collector application to simulate
29 the service API described in "AT&T Service Specification, Service:
30 Vendor Event Listener Revision 2.11, 16-Sep-2016".
35 This User Guide is intended to enable the reader to understand how
36 the Test Collector can be used to verify the operation of applications
37 supporting the Vendor Event Listener API.
43 The realization of the Test Collector is a Python script which acts as a
44 server for the Vendor Event Listener API. It uses [jsonschema](https://pypi.python.org/pypi/jsonschema)
45 in order to validate the received JSON events against AT&T's published
48 The overall system architecture is shown in Figure 1 and comprises
49 three key deliverables:
51 * The web-application itself.
55 * A validating test collector application.
57 The Test Collector is described in more detail in the
58 following sections. The other two components are described in a separate
61 * Reference VNF User Guide
63 * Reference VNF Application Note
65 Figure 1: Realization Architecture
67 ![Realization Architecture](images/architecture.png)
69 Note that items shown in green in the diagram are existing AT&T
70 systems and do not form part of the delivery.
75 The validating collector provides a basic test capability for
76 the Reference VNF. The application implements the Vendor Event
77 Listener API providing:
79 - Logging of new requests.
81 - Validating requests against the published schema.
83 - Validating the credentials provided in the request.
85 - Responding with a 202 Accepted for valid requests.
87 - Test Control endpoint allowing a test harness or user to set a pending
88 commandList, to be sent in response to the next event received.
90 - Responding with a 202 Accepted plus a pending commandList.
92 - Responding with a 401 Unauthorized error response-code and a JSON
93 exception response for failed authentication.
95 It is intended to be used in environments where the "real" AT&T
96 Vendor Event Listener service is not available in order to test the
97 Reference VNF or, indeed, any other software which needs to send
100 Using the Validating Collector
101 ==============================
103 The test collector can be run manually, either on a Linux platform
104 or a Windows PC. It is invoked with a number of command-line
108 C:> python collector.py --config <file>
115 - **config** defines the path to the config file to be used.
117 - **section** defines the section in the config file to be used.
119 - **verbose** controls the level of logging to be generated.
121 Wherever you chose to run the Test Collector, note that the
122 configuration of the backend service running on the VM generating
123 the events has to match so that the events generated by the backend
124 service are sent to the correct location and the Test Collector is
125 listening on the correct ports and URLs. The relevant section of the
126 Test Collector config file is:
129 #------------------------------------------------------------------------------
130 # Details of the Vendor Event Listener REST service.
132 # REST resources are defined with respect to a ServerRoot:
133 # ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
135 # REST resources are of the form:
136 # * {ServerRoot}/eventListener/v{apiVersion}
137 # * {ServerRoot}/eventListener/v{apiVersion}/{topicName}
138 # * {ServerRoot}/eventListener/v{apiVersion}/eventBatch
139 # * {ServerRoot}/eventListener/v{apiVersion}/clientThrottlingState
141 # The "vel\_topic\_name" parameter is used as the "topicName" element in the path
144 # Note that the path, if present, should have no leading "/" but should have a
146 #------------------------------------------------------------------------------
147 vel_domain = 127.0.0.1
149 vel_path = vendor_event_listener/
151 vel_password = This isn't very secure!
152 vel_topic_name = example_vnf
154 The equivalent section of the backend service's configuration has to
155 match, or the equivalent parameters injected in the VM by the
156 OpenStack metadata service have to match.
158 When events are sent from the web application, the results of the
159 validation will be displayed on stdout and be written to the log
160 file specified in the configuration file.
162 For example: A Fault event failing to validate:
165 <machine name>; - - [29/Feb/2016 10:58:28] "POST
166 /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1" 204 0
167 Event is not valid against schema! 'eventSeverity' is a required
169 Failed validating 'required' in
170 schema['properties']['event']['properties']['faultFields']:
171 {'description': 'fields specific to fault events',
172 'properties': {'alarmAdditionalInformation': {'description':'additional alarm information',
173 'items': {'$ref': '#/definitions/field'},
175 'alarmCondition': {'description': 'alarm condition reportedby the device',
177 'alarmInterfaceA': {'description': 'card, port, channel or interface name of the device generating the alarm',
179 'eventSeverity': {'description': 'event severity or priority',
186 'eventSourceType': {'description': 'type of event source',
195 'virtualMachine(8)'],
197 'faultFieldsVersion': {'description': 'version of the faultFields block',
199 'specificProblem': {'description': 'short description of the alarm or problem',
201 'vfStatus': {'description': 'virtual function status enumeration',
204 'Preparing to terminate',
205 'Ready to terminate',
206 'Requesting termination'],
208 'required': ['alarmCondition',
214 On instance['event']['faultFields']:
215 {'alarmAdditionalInformation': [{'name': 'extra information',
217 {'name': 'more information',
219 'alarmCondition': 'alarm condition 1',
220 'eventSourceType': 'virtualMachine(8)',
221 'faultFieldsVersion': 1,
222 'specificProblem': 'problem 1',
223 'vfStatus': 'Active'}
224 Bad JSON body decoded:
227 "commonEventHeader": {
230 "eventType": "event type 1",
231 "functionalRole": "unknown",
232 "lastEpochMicrosec": 1456743510381000.0,
233 "priority": "Normal",
234 "reportingEntityId": "Not in OpenStack",
235 "reportingEntityName": "Not in OpenStack Environment",
237 "sourceId": "Not in OpenStack",
238 "sourceName": "Not in OpenStack Environment",
239 "startEpochMicrosec": 1456743510381000.0,
243 "alarmAdditionalInformation": [
245 "name": "extra information",
249 "name": "more information",
253 "alarmCondition": "alarm condition 1",
254 "eventSourceType": "virtualMachine(8)",
255 "faultFieldsVersion": 1,
256 "specificProblem": "problem 1",
263 Test Control Interface
264 ----------------------
266 The test collector will accept any valid commandList on the Test Control interface,
267 and will store it until the next event is received at the collector.
268 At this point, it will send it to the event sender, and discard the pending commandList.
270 For example, a POST of the following JSON will result in a measurement interval change
271 command being sent to the sender of the next event.
278 "commandType": "measurementIntervalChange",
279 "measurementInterval": 60
286 A python script "test_control.py" provides an example of commandList injection,
287 and contains various functions to generate example command lists.
289 The test control script can be run manually, either on a Linux platform or a Windows PC.
290 It is invoked with optional command-line arguments for the fqdn and port number of the
291 test collector to be controlled:
293 C:> python test_control.py --fqdn 127.0.0.1 --port 30000