1 # AT&T Vendor Event Listener Service - Test Collector - User Guide
9 This document describes how to use the Test Collector application to simulate
10 the service API described in "AT&T Service Specification, Service:
11 Vendor Event Listener Revision 2.11, 16-Sep-2016".
16 This User Guide is intended to enable the reader to understand how
17 the Test Collector can be used to verify the operation of applications
18 supporting the Vendor Event Listener API.
24 The realization of the Test Collector is a Python script which acts as a
25 server for the Vendor Event Listener API. It uses [jsonschema](https://pypi.python.org/pypi/jsonschema)
26 in order to validate the received JSON events against AT&T's published
29 The overall system architecture is shown in Figure 1 and comprises
30 three key deliverables:
32 * The web-application itself.
36 * A validating test collector application.
38 The Test Collector is described in more detail in the
39 following sections. The other two components are described in a separate
42 * Reference VNF User Guide
44 * Reference VNF Application Note
46 Figure 1: Realization Architecture
48 ![Realization Architecture](images/architecture.png)
50 Note that items shown in green in the diagram are existing AT&T
51 systems and do not form part of the delivery.
56 The validating collector provides a basic test capability for
57 the Reference VNF. The application implements the Vendor Event
58 Listener API providing:
60 - Logging of new requests.
62 - Validating requests against the published schema.
64 - Validating the credentials provided in the request.
66 - Responding with a 202 Accepted for valid requests.
68 - Test Control endpoint allowing a test harness or user to set a pending
69 commandList, to be sent in response to the next event received.
71 - Responding with a 202 Accepted plus a pending commandList.
73 - Responding with a 401 Unauthorized error response-code and a JSON
74 exception response for failed authentication.
76 It is intended to be used in environments where the "real" AT&T
77 Vendor Event Listener service is not available in order to test the
78 Reference VNF or, indeed, any other software which needs to send
81 Using the Validating Collector
82 ==============================
84 The test collector can be run manually, either on a Linux platform
85 or a Windows PC. It is invoked with a number of command-line
89 C:> python collector.py --config <file>
96 - **config** defines the path to the config file to be used.
98 - **section** defines the section in the config file to be used.
100 - **verbose** controls the level of logging to be generated.
102 Wherever you chose to run the Test Collector, note that the
103 configuration of the backend service running on the VM generating
104 the events has to match so that the events generated by the backend
105 service are sent to the correct location and the Test Collector is
106 listening on the correct ports and URLs. The relevant section of the
107 Test Collector config file is:
110 #------------------------------------------------------------------------------
111 # Details of the Vendor Event Listener REST service.
113 # REST resources are defined with respect to a ServerRoot:
114 # ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
116 # REST resources are of the form:
117 # * {ServerRoot}/eventListener/v{apiVersion}
118 # * {ServerRoot}/eventListener/v{apiVersion}/{topicName}
119 # * {ServerRoot}/eventListener/v{apiVersion}/eventBatch
120 # * {ServerRoot}/eventListener/v{apiVersion}/clientThrottlingState
122 # The "vel\_topic\_name" parameter is used as the "topicName" element in the path
125 # Note that the path, if present, should have no leading "/" but should have a
127 #------------------------------------------------------------------------------
128 vel_domain = 127.0.0.1
130 vel_path = vendor_event_listener/
132 vel_password = This isn't very secure!
133 vel_topic_name = example_vnf
135 The equivalent section of the backend service's configuration has to
136 match, or the equivalent parameters injected in the VM by the
137 OpenStack metadata service have to match.
139 When events are sent from the web application, the results of the
140 validation will be displayed on stdout and be written to the log
141 file specified in the configuration file.
143 For example: A Fault event failing to validate:
146 <machine name>; - - [29/Feb/2016 10:58:28] "POST
147 /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1" 204 0
148 Event is not valid against schema! 'eventSeverity' is a required
150 Failed validating 'required' in
151 schema['properties']['event']['properties']['faultFields']:
152 {'description': 'fields specific to fault events',
153 'properties': {'alarmAdditionalInformation': {'description':'additional alarm information',
154 'items': {'$ref': '#/definitions/field'},
156 'alarmCondition': {'description': 'alarm condition reportedby the device',
158 'alarmInterfaceA': {'description': 'card, port, channel or interface name of the device generating the alarm',
160 'eventSeverity': {'description': 'event severity or priority',
167 'eventSourceType': {'description': 'type of event source',
176 'virtualMachine(8)'],
178 'faultFieldsVersion': {'description': 'version of the faultFields block',
180 'specificProblem': {'description': 'short description of the alarm or problem',
182 'vfStatus': {'description': 'virtual function status enumeration',
185 'Preparing to terminate',
186 'Ready to terminate',
187 'Requesting termination'],
189 'required': ['alarmCondition',
195 On instance['event']['faultFields']:
196 {'alarmAdditionalInformation': [{'name': 'extra information',
198 {'name': 'more information',
200 'alarmCondition': 'alarm condition 1',
201 'eventSourceType': 'virtualMachine(8)',
202 'faultFieldsVersion': 1,
203 'specificProblem': 'problem 1',
204 'vfStatus': 'Active'}
205 Bad JSON body decoded:
208 "commonEventHeader": {
211 "eventType": "event type 1",
212 "functionalRole": "unknown",
213 "lastEpochMicrosec": 1456743510381000.0,
214 "priority": "Normal",
215 "reportingEntityId": "Not in OpenStack",
216 "reportingEntityName": "Not in OpenStack Environment",
218 "sourceId": "Not in OpenStack",
219 "sourceName": "Not in OpenStack Environment",
220 "startEpochMicrosec": 1456743510381000.0,
224 "alarmAdditionalInformation": [
226 "name": "extra information",
230 "name": "more information",
234 "alarmCondition": "alarm condition 1",
235 "eventSourceType": "virtualMachine(8)",
236 "faultFieldsVersion": 1,
237 "specificProblem": "problem 1",
244 Test Control Interface
245 ----------------------
247 The test collector will accept any valid commandList on the Test Control interface,
248 and will store it until the next event is received at the collector.
249 At this point, it will send it to the event sender, and discard the pending commandList.
251 For example, a POST of the following JSON will result in a measurement interval change
252 command being sent to the sender of the next event.
259 "commandType": "measurementIntervalChange",
260 "measurementInterval": 60
267 A python script "test_control.py" provides an example of commandList injection,
268 and contains various functions to generate example command lists.
270 The test control script can be run manually, either on a Linux platform or a Windows PC.
271 It is invoked with optional command-line arguments for the fqdn and port number of the
272 test collector to be controlled:
274 C:> python test_control.py --fqdn 127.0.0.1 --port 30000