vnfs/VES5.0/evel/evel-test-collector/docs/test_collector_user_guide/test_collector_user_guide.md

   1 # AT&T Vendor Event Listener Service - Test Collector - User Guide
   2 #  ===================================================================
   3 #  Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4 #  ===================================================================
   5 #  Licensed under the Apache License, Version 2.0 (the "License");
   6 #  you may not use this file except in compliance with the License.
   7 #  You may obtain a copy of the License at
   8 #
   9 #         http://www.apache.org/licenses/LICENSE-2.0
  10 #
  11 #  Unless required by applicable law or agreed to in writing, software
  12 #  distributed under the License is distributed on an "AS IS" BASIS,
  13 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 #  See the License for the specific language governing permissions and
  15 #  limitations under the License.
  16 #  ============LICENSE_END============================================
  17 #
  18 #  ECOMP and OpenECOMP are trademarks
  19 #  and service marks of AT&T Intellectual Property.
  20
  21
  22 Introduction
  23 ============
  24
  25 Background
  26 ----------
  27
  28 This document describes how to use the Test Collector application to simulate
  29 the service API described in "AT&T Service Specification, Service:
  30 Vendor Event Listener Revision 2.11, 16-Sep-2016".
  31
  32 Purpose
  33 -------
  34
  35 This User Guide is intended to enable the reader to understand how
  36     the Test Collector can be used to verify the operation of applications
  37     supporting the Vendor Event Listener API.
  38
  39
  40 Realization
  41 ===========
  42
  43 The realization of the Test Collector is a Python script which acts as a
  44 server for the Vendor Event Listener API. It uses [jsonschema](https://pypi.python.org/pypi/jsonschema)
  45 in order to validate the received JSON events against AT&T's published
  46 schema for the API.
  47
  48 The overall system architecture is shown in Figure 1 and comprises
  49     three key deliverables:
  50
  51 *    The web-application itself.
  52
  53 *    A Backend service.
  54
  55 *    A validating test collector application.
  56
  57 The Test Collector is described in more detail in the
  58     following sections.  The other two components are described in a separate
  59     documents:
  60
  61 *    Reference VNF User Guide
  62
  63 *    Reference VNF Application Note
  64
  65 Figure 1: Realization Architecture
  66
  67 ![Realization Architecture](images/architecture.png)
  68
  69 Note that items shown in green in the diagram are existing AT&T
  70     systems and do not form part of the delivery.
  71
  72 Validating Collector
  73 --------------------
  74
  75 The validating collector provides a basic test capability for
  76     the Reference VNF. The application implements the Vendor Event
  77     Listener API providing:
  78
  79 -   Logging of new requests.
  80
  81 -   Validating requests against the published schema.
  82
  83 -   Validating the credentials provided in the request.
  84
  85 -   Responding with a 202 Accepted for valid requests.
  86
  87 -   Test Control endpoint allowing a test harness or user to set a pending
  88     commandList, to be sent in response to the next event received.
  89
  90 -   Responding with a 202 Accepted plus a pending commandList.
  91
  92 -   Responding with a 401 Unauthorized error response-code and a JSON
  93     exception response for failed authentication.
  94
  95 It is intended to be used in environments where the "real" AT&T
  96     Vendor Event Listener service is not available in order to test the
  97     Reference VNF or, indeed, any other software which needs to send
  98     events to a server.
  99
 100 Using the Validating Collector
 101 ==============================
 102
 103 The test collector can be run manually, either on a Linux platform
 104     or a Windows PC. It is invoked with a number of command-line
 105     arguments:
 106
 107 ```
 108   C:> python collector.py --config <file>
 109                           --section <section>
 110                           --verbose
 111 ```
 112
 113 Where:
 114
 115   -  **config** defines the path to the config file to be used.
 116
 117   -  **section** defines the section in the config file to be used.
 118
 119   -  **verbose** controls the level of logging to be generated.
 120
 121 Wherever you chose to run the Test Collector, note that the
 122     configuration of the backend service running on the VM generating
 123     the events has to match so that the events generated by the backend
 124     service are sent to the correct location and the Test Collector is
 125     listening on the correct ports and URLs. The relevant section of the
 126     Test Collector config file is:
 127
 128 ```
 129     #------------------------------------------------------------------------------
 130     # Details of the Vendor Event Listener REST service.
 131     #
 132     # REST resources are defined with respect to a ServerRoot:
 133     # ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
 134     #
 135     # REST resources are of the form:
 136     # * {ServerRoot}/eventListener/v{apiVersion}
 137     # * {ServerRoot}/eventListener/v{apiVersion}/{topicName}
 138     # * {ServerRoot}/eventListener/v{apiVersion}/eventBatch
 139     # * {ServerRoot}/eventListener/v{apiVersion}/clientThrottlingState
 140     #
 141     # The "vel\_topic\_name" parameter is used as the "topicName" element in the path
 142     # and may be empty.
 143     #
 144     # Note that the path, if present, should have no leading "/" but should have a
 145     # training "/".
 146     #------------------------------------------------------------------------------
 147     vel_domain = 127.0.0.1
 148     vel_port = 30000
 149     vel_path = vendor_event_listener/
 150     vel_username = Alice
 151     vel_password = This isn't very secure!
 152     vel_topic_name = example_vnf
 153 ```
 154 The equivalent section of the backend service's configuration has to
 155     match, or the equivalent parameters injected in the VM by the
 156     OpenStack metadata service have to match.
 157
 158 When events are sent from the web application, the results of the
 159     validation will be displayed on stdout and be written to the log
 160     file specified in the configuration file.
 161
 162 For example: A Fault event failing to validate:
 163
 164 ```
 165     <machine name>; - - [29/Feb/2016 10:58:28] "POST
 166     /vendor_event_listener/eventListener/v1/example_vnf HTTP/1.1" 204  0
 167     Event is not valid against schema! 'eventSeverity' is a required
 168     property
 169     Failed validating 'required' in
 170     schema['properties']['event']['properties']['faultFields']:
 171         {'description': 'fields specific to fault events',
 172         'properties': {'alarmAdditionalInformation': {'description':'additional alarm information',
 173                                                       'items': {'$ref': '#/definitions/field'},
 174                                                       'type': 'array'},
 175                        'alarmCondition': {'description': 'alarm condition reportedby the device',
 176                                                       'type': 'string'},
 177                        'alarmInterfaceA': {'description': 'card, port, channel or interface name of the device generating the alarm',
 178                                                       'type': 'string'},
 179                        'eventSeverity': {'description': 'event severity or priority',
 180                                          'enum': ['CRITICAL',
 181                                                    'MAJOR',
 182                                                    'MINOR',
 183                                                    'WARNING',
 184                                                    'NORMAL'],
 185                                          'type': 'string'},
 186                        'eventSourceType': {'description': 'type of event source',
 187                                            'enum': ['other(0)',
 188                                                      'router(1)',
 189                                                      'switch(2)',
 190                                                      'host(3)',
 191                                                      'card(4)',
 192                                                      'port(5)',
 193                                                      'slotThreshold(6)',
 194                                                      'portThreshold(7)',
 195                                                      'virtualMachine(8)'],
 196                                            'type': 'string'},
 197                        'faultFieldsVersion': {'description': 'version of the faultFields block',
 198                                               'type': 'number'},
 199                        'specificProblem': {'description': 'short description of the alarm or problem',
 200                                               'type': 'string'},
 201                        'vfStatus': {'description': 'virtual function status enumeration',
 202                                     'enum': ['Active',
 203                                               'Idle',
 204                                               'Preparing to terminate',
 205                                               'Ready to terminate',
 206                                               'Requesting termination'],
 207                                     'type': 'string'}},
 208             'required': ['alarmCondition',
 209                           'eventSeverity',
 210                           'eventSourceType',
 211                           'specificProblem',
 212                           'vfStatus'],
 213             'type': 'object'}
 214     On instance['event']['faultFields']:
 215         {'alarmAdditionalInformation': [{'name': 'extra information',
 216                                           'value': '2'},
 217                                          {'name': 'more information',
 218                                           'value': '1'}],
 219          'alarmCondition': 'alarm condition 1',
 220          'eventSourceType': 'virtualMachine(8)',
 221          'faultFieldsVersion': 1,
 222          'specificProblem': 'problem 1',
 223          'vfStatus': 'Active'}
 224     Bad JSON body decoded:
 225     {
 226         "event": {
 227             "commonEventHeader": {
 228                 "domain": "fault",
 229                 "eventId": "6",
 230                 "eventType": "event type 1",
 231                 "functionalRole": "unknown",
 232                 "lastEpochMicrosec": 1456743510381000.0,
 233                 "priority": "Normal",
 234                 "reportingEntityId": "Not in OpenStack",
 235                 "reportingEntityName": "Not in OpenStack Environment",
 236                 "sequence": 0,
 237                 "sourceId": "Not in OpenStack",
 238                 "sourceName": "Not in OpenStack Environment",
 239                 "startEpochMicrosec": 1456743510381000.0,
 240                 "version": 1
 241             },
 242             "faultFields": {
 243                 "alarmAdditionalInformation": [
 244                     {
 245                         "name": "extra information",
 246                         "value": "2"
 247                     },
 248                     {
 249                         "name": "more information",
 250                         "value": "1"
 251                     }
 252                ],
 253                "alarmCondition": "alarm condition 1",
 254                "eventSourceType": "virtualMachine(8)",
 255                "faultFieldsVersion": 1,
 256                "specificProblem": "problem 1",
 257                "vfStatus": "Active"
 258             }
 259         }
 260     }
 261 ```
 262
 263 Test Control Interface
 264 ----------------------
 265
 266 The test collector will accept any valid commandList on the Test Control interface,
 267 and will store it until the next event is received at the collector.
 268 At this point, it will send it to the event sender, and discard the pending commandList.
 269
 270 For example, a POST of the following JSON will result in a measurement interval change
 271 command being sent to the sender of the next event.
 272
 273 ```
 274 {
 275     "commandList": [
 276         {
 277             "command": {
 278                 "commandType": "measurementIntervalChange",
 279                 "measurementInterval": 60
 280             }
 281         }
 282     ]
 283 }
 284 ```
 285
 286 A python script "test_control.py" provides an example of commandList injection,
 287 and contains various functions to generate example command lists.
 288
 289 The test control script can be run manually, either on a Linux platform or a Windows PC.
 290 It is invoked with optional command-line arguments for the fqdn and port number of the
 291 test collector to be controlled:
 292 ```
 293   C:> python test_control.py --fqdn 127.0.0.1 --port 30000
 294 ```