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, 0 insertions, 275 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 deleted file mode 100644 index 5e12a904..00000000 --- a/vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md +++ /dev/null @@ -1,275 +0,0 @@ -# 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 -``` |