diff options
Diffstat (limited to 'vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md')
| -rw-r--r-- | vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md b/vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md new file mode 100644 index 00000000..5e12a904 --- /dev/null +++ b/vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md @@ -0,0 +1,275 @@ +# 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 + + + +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 +``` |