# AT&T Vendor Event Listener Service - Test Collector - User Guide 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 ![Realization Architecture](images/architecture.png) 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 --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: ``` ; - - [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 ```