vnfs/VES5.0/collector/docs/test_collector_user_guide/test_collector_user_guide.md

   1 # AT&T Vendor Event Listener Service - Test Collector - User Guide
   2
   3 Introduction
   4 ============
   5
   6 Background
   7 ----------
   8
   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".
  12
  13 Purpose
  14 -------
  15
  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.
  19
  20
  21 Realization
  22 ===========
  23
  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
  27 schema for the API.
  28
  29 The overall system architecture is shown in Figure 1 and comprises
  30     three key deliverables:
  31
  32 *    The web-application itself.
  33
  34 *    A Backend service.
  35
  36 *    A validating test collector application.
  37
  38 The Test Collector is described in more detail in the
  39     following sections.  The other two components are described in a separate
  40     documents:
  41
  42 *    Reference VNF User Guide
  43
  44 *    Reference VNF Application Note
  45
  46 Figure 1: Realization Architecture
  47
  48 ![Realization Architecture](images/architecture.png)
  49
  50 Note that items shown in green in the diagram are existing AT&T
  51     systems and do not form part of the delivery.
  52
  53 Validating Collector
  54 --------------------
  55
  56 The validating collector provides a basic test capability for
  57     the Reference VNF. The application implements the Vendor Event
  58     Listener API providing:
  59
  60 -   Logging of new requests.
  61
  62 -   Validating requests against the published schema.
  63
  64 -   Validating the credentials provided in the request.
  65
  66 -   Responding with a 202 Accepted for valid requests.
  67
  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.
  70
  71 -   Responding with a 202 Accepted plus a pending commandList.
  72
  73 -   Responding with a 401 Unauthorized error response-code and a JSON
  74     exception response for failed authentication.
  75
  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
  79     events to a server.
  80
  81 Using the Validating Collector
  82 ==============================
  83
  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
  86     arguments:
  87
  88 ```
  89   C:> python collector.py --config <file>
  90                           --section <section>
  91                           --verbose
  92 ```
  93
  94 Where:
  95
  96   -  **config** defines the path to the config file to be used.
  97
  98   -  **section** defines the section in the config file to be used.
  99
 100   -  **verbose** controls the level of logging to be generated.
 101
 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:
 108
 109 ```
 110     #------------------------------------------------------------------------------
 111     # Details of the Vendor Event Listener REST service.
 112     #
 113     # REST resources are defined with respect to a ServerRoot:
 114     # ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
 115     #
 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
 121     #
 122     # The "vel\_topic\_name" parameter is used as the "topicName" element in the path
 123     # and may be empty.
 124     #
 125     # Note that the path, if present, should have no leading "/" but should have a
 126     # training "/".
 127     #------------------------------------------------------------------------------
 128     vel_domain = 127.0.0.1
 129     vel_port = 30000
 130     vel_path = vendor_event_listener/
 131     vel_username = Alice
 132     vel_password = This isn't very secure!
 133     vel_topic_name = example_vnf
 134 ```
 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.
 138
 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.
 142
 143 For example: A Fault event failing to validate:
 144
 145 ```
 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
 149     property
 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'},
 155                                                       'type': 'array'},
 156                        'alarmCondition': {'description': 'alarm condition reportedby the device',
 157                                                       'type': 'string'},
 158                        'alarmInterfaceA': {'description': 'card, port, channel or interface name of the device generating the alarm',
 159                                                       'type': 'string'},
 160                        'eventSeverity': {'description': 'event severity or priority',
 161                                          'enum': ['CRITICAL',
 162                                                    'MAJOR',
 163                                                    'MINOR',
 164                                                    'WARNING',
 165                                                    'NORMAL'],
 166                                          'type': 'string'},
 167                        'eventSourceType': {'description': 'type of event source',
 168                                            'enum': ['other(0)',
 169                                                      'router(1)',
 170                                                      'switch(2)',
 171                                                      'host(3)',
 172                                                      'card(4)',
 173                                                      'port(5)',
 174                                                      'slotThreshold(6)',
 175                                                      'portThreshold(7)',
 176                                                      'virtualMachine(8)'],
 177                                            'type': 'string'},
 178                        'faultFieldsVersion': {'description': 'version of the faultFields block',
 179                                               'type': 'number'},
 180                        'specificProblem': {'description': 'short description of the alarm or problem',
 181                                               'type': 'string'},
 182                        'vfStatus': {'description': 'virtual function status enumeration',
 183                                     'enum': ['Active',
 184                                               'Idle',
 185                                               'Preparing to terminate',
 186                                               'Ready to terminate',
 187                                               'Requesting termination'],
 188                                     'type': 'string'}},
 189             'required': ['alarmCondition',
 190                           'eventSeverity',
 191                           'eventSourceType',
 192                           'specificProblem',
 193                           'vfStatus'],
 194             'type': 'object'}
 195     On instance['event']['faultFields']:
 196         {'alarmAdditionalInformation': [{'name': 'extra information',
 197                                           'value': '2'},
 198                                          {'name': 'more information',
 199                                           'value': '1'}],
 200          'alarmCondition': 'alarm condition 1',
 201          'eventSourceType': 'virtualMachine(8)',
 202          'faultFieldsVersion': 1,
 203          'specificProblem': 'problem 1',
 204          'vfStatus': 'Active'}
 205     Bad JSON body decoded:
 206     {
 207         "event": {
 208             "commonEventHeader": {
 209                 "domain": "fault",
 210                 "eventId": "6",
 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",
 217                 "sequence": 0,
 218                 "sourceId": "Not in OpenStack",
 219                 "sourceName": "Not in OpenStack Environment",
 220                 "startEpochMicrosec": 1456743510381000.0,
 221                 "version": 1
 222             },
 223             "faultFields": {
 224                 "alarmAdditionalInformation": [
 225                     {
 226                         "name": "extra information",
 227                         "value": "2"
 228                     },
 229                     {
 230                         "name": "more information",
 231                         "value": "1"
 232                     }
 233                ],
 234                "alarmCondition": "alarm condition 1",
 235                "eventSourceType": "virtualMachine(8)",
 236                "faultFieldsVersion": 1,
 237                "specificProblem": "problem 1",
 238                "vfStatus": "Active"
 239             }
 240         }
 241     }
 242 ```
 243
 244 Test Control Interface
 245 ----------------------
 246
 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.
 250
 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.
 253
 254 ```
 255 {
 256     "commandList": [
 257         {
 258             "command": {
 259                 "commandType": "measurementIntervalChange",
 260                 "measurementInterval": 60
 261             }
 262         }
 263     ]
 264 }
 265 ```
 266
 267 A python script "test_control.py" provides an example of commandList injection,
 268 and contains various functions to generate example command lists.
 269
 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:
 273 ```
 274   C:> python test_control.py --fqdn 127.0.0.1 --port 30000
 275 ```