docs/specs/qos-alert.rst

   1 .. contents:: Table of Contents
   2       :depth: 3
   3
   4 =====================
   5 Support for QoS Alert
   6 =====================
   7
   8 https://git.opendaylight.org/gerrit/#/q/topic:qos-alert
   9
  10 This feature adds support to monitor the per port packet drop counts when QoS rate limit rule is
  11 applied.
  12
  13 Problem description
  14 ===================
  15
  16 If QoS bandwidth policy is applied on a neutron port, all packets exceeding the rate limit are
  17 dropped by the switch. This spec proposes a new service to monitor the packet drop ratio and log
  18 the alert message if packet drop ratio is greater than the configured threshold value.
  19
  20 Use Cases
  21 ---------
  22 Periodically monitor the port statistics of neutron ports having bandwidth limit rule and log an
  23 alert message in a log file if packet drop ratio cross the threshold value. Log file can be
  24 analyzed offline later to check the health/diagnostics of the network.
  25
  26
  27 Proposed change
  28 ===============
  29 Proposed new service will use the RPC
  30 ``/operations/opendaylight-direct-statistics:get-node-connector-statistics`` provided by
  31 openflowplugin to retrieve port statistics directly from switch by polling at regular interval.
  32 Polling interval is configurable with default value of 2 minutes.
  33
  34 Port packet drop ratio is calculated using delta of two port statistics counters
  35 ``rx_dropped`` and ``rx_received`` between the sample interval.
  36
  37  ``packet drop ratio =  100 * (rx_dropped  / (rx_received + rx_dropped ))``
  38
  39 An message is logged if packet drop ratio is greater than the configured threshold value.
  40
  41 Existing logging framework ``log4j`` shall be used to log the alert messages in the log file.
  42 A new appender ``qosalertmsg`` shall be added in ``org.ops4j.pax.logging.cfg`` to define the
  43 logging properties.
  44
  45
  46 Log file format
  47 ---------------
  48 .. code-block:: bash
  49
  50  2017-01-17 01:17:49,550 Packet drop threshold hit for qos policy qospolicy1 with qos-id qos-2dbf02f6-dcd1-4c13-90ee-6f727e21fe8d for port port-3afde68d-1103-4b8a-a38d-9cae631f7d67 on network network-563f9610-dd91-4524-ae23-8ec3c32f328e rx_received 4831 rx_dropped 4969
  51  2017-01-17 01:17:49,550 Packet drop threshold hit for qos policy qospolicy2 with qos-id qos-cb7e5f67-2552-4d49-b534-0ce90ebc8d97 for port port-09d3a437-f4a4-43eb-8655-85df8bbe4793 on network network-389532a1-2b48-4ba9-9bcd-c1705d9e28f9 rx_received 3021 rx_dropped 4768
  52  2017-01-17 01:19:49,339 Packet drop threshold hit for qos policy qospolicy1 with qos-id qos-2dbf02f6-dcd1-4c13-90ee-6f727e21fe8d for port port-3afde68d-1103-4b8a-a38d-9cae631f7d67 on network network-563f9610-dd91-4524-ae23-8ec3c32f328e rx_received 3837 rx_dropped 3961
  53  2017-01-17 01:19:49,339 Packet drop threshold hit for qos policy qospolicy2 with qos-id qos-cb7e5f67-2552-4d49-b534-0ce90ebc8d97 for port port-09d3a437-f4a4-43eb-8655-85df8bbe4793 on network network-389532a1-2b48-4ba9-9bcd-c1705d9e28f9 rx_received 2424 rx_dropped 2766
  54
  55 Pipeline changes
  56 ----------------
  57 None.
  58
  59 Yang changes
  60 ------------
  61 A new yang file shall be created for qos-alert configuration as specified below:
  62
  63 .. code-block:: none
  64    :caption: qos-alert-config.yang
  65
  66    module qosalert-config {
  67
  68      yang-version 1;
  69      namespace "urn:opendaylight:params:xml:ns:yang:netvirt:qosalert:config";
  70      prefix "qosalert";
  71
  72      revision "2017-01-03" {
  73        description "Initial revision of qosalert model";
  74      }
  75
  76      description "This YANG module defines QoS alert configuration.";
  77
  78      container qosalert-config {
  79
  80        config true;
  81
  82        leaf qos-alert-enabled {
  83          description "QoS alert enable-disable config knob";
  84          type boolean;
  85          default false;
  86        }
  87
  88        leaf qos-drop-packet-threshold {
  89          description "QoS Packet drop threshold config. Specified as % of rx packets";
  90          type uint8 {
  91            range "1..100";
  92          }
  93          default 5;
  94        }
  95
  96        leaf qos-alert-poll-interval {
  97          description "Polling interval in minutes";
  98          type uint16 {
  99            range "1..3600";
 100          }
 101          default 2;
 102        }
 103
 104      }
 105    }
 106
 107
 108
 109 Configuration impact
 110 ---------------------
 111 Following new parameters shall be made available as configuration. Initial or default configuration
 112 is specified in ``netvirt-qosalert-config.xml``
 113
 114 ======== =============================  ====================================================
 115   Sl No.  configuration                 Description
 116 ======== =============================  ====================================================
 117 1.       ``qos-alert-enabled``          configuration parameter to enable/disable the alerts
 118
 119 2.       ``qos-drop-packet-threshold``  Drop percentage threshold configuration.
 120
 121 3.       ``qos-alert-poll-interval``    Polling interval in minutes
 122 ======== =============================  ====================================================
 123
 124 Logging properties like log file name, location, size and maximum number of backup files are
 125 configured in file ``org.ops4j.pax.logging.cfg``
 126
 127 Clustering considerations
 128 -------------------------
 129 In cluster setup, only one instance of qosalert service shall poll for port statistics.
 130 Entity owner service (EOS) shall be used to determine the owner of service.
 131
 132 Other Infra considerations
 133 --------------------------
 134 N.A.
 135
 136 Security considerations
 137 -----------------------
 138 None.
 139
 140 Scale and Performance Impact
 141 ----------------------------
 142 QoS Alert Service minimizes scale and performance impact by following:
 143
 144 - Proposed service uses the direct-statistics RPC instead of OpenflowPlugin statistics-manager. This
 145   is lightweight because only node-connector statistics are queried instead of all statistics.
 146 - Polling frequency is quite slow. Default polling interval is **two minutes** and minimum allowed
 147   value is 1 minute.
 148
 149 Targeted Release
 150 -----------------
 151 Carbon.
 152
 153 Alternatives
 154 ------------
 155 N.A.
 156
 157 Usage
 158 =====
 159
 160 Features to Install
 161 -------------------
 162 This feature can be used by installing ``odl-netvirt-openstack``.
 163 This feature doesn't add any new karaf feature.
 164
 165 REST API
 166 --------
 167 Put Qos Alert Config
 168 ^^^^^^^^^^^^^^^^^^^^
 169 Following API puts Qos Alert Config.
 170
 171 **Method**: POST
 172
 173 **URI**:  /config/qosalert-config:qosalert-config
 174
 175 **Parameters**:
 176
 177 =============================  =======  ============  ===============================================
 178         Parameter              Type     Value range                   Comments
 179 =============================  =======  ============  ===============================================
 180 ``qos-alert-enabled``          Boolean  true/false    Optional (default false)
 181
 182 ``qos-drop-packet-threshold``  Uint16   1..100        Optional (default 5)
 183
 184 ``qos-alert-poll-interval``    Uint16   1..65535      Optional time interval in minute(s) (default 2)
 185 =============================  =======  ============  ===============================================
 186
 187
 188 **Example**:
 189 .. code-block:: json
 190
 191  {
 192     "input":
 193     {
 194
 195       "qos-alert-enabled": true,
 196
 197       "qos-drop-packet-threshold": 35,
 198
 199       "qos-alert-poll-interval": 5
 200
 201    }
 202
 203  }
 204
 205
 206 CLI
 207 ---
 208
 209 Following new karaf CLIs are added
 210
 211
 212 .. code-block:: bash
 213
 214
 215  qos:enable-qos-alert <true|false>
 216
 217  qos:drop-packet-threshold <threshold value in %>
 218
 219  qos:alert-poll-interval <polling interval in minutes>
 220
 221 Implementation
 222 ==============
 223
 224 Assignee(s)
 225 -----------
 226
 227 Primary assignee:
 228  - Arun Sharma (arun.e.sharma@ericsson.com)
 229
 230 Other contributors:
 231  - Ravi Sundareswaran (ravi.sundareswaran@ericsson.com)
 232  - Mukta Rani (mukta.rani@tcs.com)
 233
 234 Work Items
 235 ----------
 236 Trello Link <https://trello.com/c/780v28Yw/148-netvirt-qos-alert>
 237
 238 #. Adding new yang file and listener.
 239 #. Adding new ``log4j appender`` in odlparent ``org.ops4j.pax.logging.cfg`` file.
 240 #. Retrieval of port statistics data using the openflowplugin RPC.
 241 #. Logging alert message into the log file.
 242 #. UT and CSIT
 243
 244 Dependencies
 245 ============
 246 This doesn't add any new dependencies.
 247
 248
 249 Testing
 250 =======
 251 Capture details of testing that will need to be added.
 252
 253 Unit Tests
 254 ----------
 255 Standard UTs will be added.
 256
 257 Integration Tests
 258 -----------------
 259 N.A.
 260
 261 CSIT
 262 ----
 263 Following new CSIT tests shall be added
 264
 265 1. Verify that alerts are generated if drop packets percentage is more than the configured threshold
 266    value.
 267 2. Verify that alerts are not generated if drop packets percentage is less than threshold value.
 268 3. Verify that alerts are not generated when ``qos-alert-enabled`` if false irrespective of drop
 269    packet percentage.
 270
 271 Documentation Impact
 272 ====================
 273 This will require changes to User Guide.
 274
 275 User Guide will need to add information on how qosalert service can
 276 be used.
 277
 278 References
 279 ==========
 280
 281 [1] `Neutron QoS <http://docs.openstack.org/developer/neutron/devref/quality_of_service.html>`__
 282
 283 [2] `Spec for NetVirt QoS <http://docs.opendaylight.org/en/latest/submodules/netvirt/docs/specs/qos.html>`__
 284
 285 [3] `Openflowplugin port statistics
 286 <https://github.com/opendaylight/openflowplugin/blob/master/model/model-flow-statistics/src/main/yang/opendaylight-direct-statistics.yang>`__