docs/Chapter7/Monitoring-And-Management.rst

   1 .. Modifications Copyright © 2017-2018 AT&T Intellectual Property.
   2
   3 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.
   4    (the "License"); you may not use this documentation except in compliance
   5    with the License. You may obtain a copy of the License at
   6
   7 .. https://creativecommons.org/licenses/by/4.0/
   8
   9 .. Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14
  15 Monitoring & Management
  16 -----------------------
  17
  18 In ONAP, DCAE is responsible of collecting, receiving, and analyzing
  19 NF monitoring data. This data serves the basis for tracking the health,
  20 performance, and operational status of the NF. DCAE provides a
  21 number of predefined interfaces based upon accepted, open standards to support
  22 monitoring data ingestion. Some of these interfaces collect data by polling or
  23 pulling data from the NF using standard protocols. Other DCAE interfaces receive
  24 monitoring data (such as VES events) that are pushed from the NFs.
  25
  26 A NF that produces monitoring data and uses protocols that are compatible with
  27 ONAP's predefined monitoring ingestion capabilities can easily be integrated
  28 with ONAP through simple configuration rather than custom development.
  29
  30 This chapter will define the expected requirements for a NF to easily integrate
  31 with an instance of ONAP.
  32
  33 Monitoring and Fault Protocol Selection
  34 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  35
  36 This section provides the proper guidance on how a NF should determine the
  37 protocol and data format for providing a specific types of telemetry data to
  38 ONAP.
  39
  40 .. req::
  41    :id: R-82909
  42    :target: VNF or PNF
  43    :keyword: MUST
  44    :introduced: guilin
  45
  46    The VNF or PNF **MUST** report faults and alarms using either
  47    :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>`
  48    or :ref:`SNMP <snmp_monitoring_requirements>`. (NOTE: See relevant sections
  49    for more detailed requirements)
  50
  51 .. req::
  52    :id: R-554966
  53    :target: VNF or PNF
  54    :keyword: MUST
  55    :introduced: guilin
  56
  57    The VNF or PNF **MUST** report performance metrics using
  58    :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>`
  59    or :ref:`bulk_performance_measurement`.
  60
  61 .. req::
  62    :id: R-69111
  63    :target: VNF or PNF
  64    :keyword: MUST
  65    :introduced: guilin
  66
  67    The VNF or PNF **MUST** report application logs using either
  68    :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>`
  69    or Syslog in compliance with
  70    `RFC 5424 <https://tools.ietf.org/html/rfc5424>`__ .
  71
  72
  73 .. req::
  74    :id: R-209104
  75    :target: VNF or PNF
  76    :keyword: SHOULD
  77    :introduced: guilin
  78
  79    The VNF or PNF producing VES syslog events **SHOULD** restrict these
  80    events to those that convey significant errors or warnings needed to support
  81    the operation or troubleshooting of the VNF or PNF. It is expected the
  82    volume of such events would be lower (e.g. less than 2000 per day) than
  83    more detailed events produced in the course of normal operations.
  84
  85 .. req::
  86    :id: R-332680
  87    :target: VNF or PNF
  88    :keyword: SHOULD
  89    :impacts: dcae
  90    :validation_mode: in_service
  91    :introduced: casablanca
  92    :updated: guilin
  93
  94    The VNF or PNF producing VES events **SHOULD** deliver syslog messages
  95    that meet the criteria in R-209104 to the VES Event Listener using the
  96    ``syslog`` VES domain.
  97
  98 .. req::
  99    :id: R-935717
 100    :target: VNF or PNF
 101    :keyword: MUST
 102    :introduced: guilin
 103
 104    The VNF or PNF **MUST** report heartbeats using
 105    :ref:`Virtual Function Event Streaming (VES) <ves_monitoring_requirements>`.
 106
 107 .. req::
 108    :id: R-697654
 109    :target: VNF or PNF
 110    :keyword: MAY
 111    :introduced: casablanca
 112    :updated: guilin
 113    :impacts: DCAE
 114    :validation_mode: in_service
 115
 116    The VNF or PNF **MAY** leverage ONAP's High Volume VNF Event Streaming
 117    (HV-VES) when there is a need to deliver large volumes of real-time
 118    performance management metrics. See
 119    `HV-VES Collector <https://onap-doc.readthedocs.io/projects/onap-dcaegen2/en/latest/sections/services/ves-hv/index.html>`__
 120    service details for more information.
 121
 122 .. req::
 123    :id: R-857511
 124    :target: VNF or PNF PROVIDER
 125    :keyword: MUST
 126    :introduced: guilin
 127    :impacts: DCAE
 128    :validation_mode: none
 129
 130    VNF or PNF Provider **MUST** have agreement with the Service Provider before
 131    utilizing the HV-VES option for monitoring as this option does not fully
 132    integrate with the ONAP's DCAE event processing capabilities.
 133
 134 .. req::
 135    :id: R-908291
 136    :target: VNF or PNF
 137    :keyword: MAY
 138    :introduced: casablanca
 139    :impacts: dcae, dmaap
 140    :validation_mode: in_service
 141    :updated: guilin
 142
 143    The VNF or PNF **MAY** leverage a bulk VNF or PNF telemetry transmission
 144    mechanism in instances where other transmission
 145    methods are not practical or advisable.
 146
 147    NOTE: For additional information and use cases for the Bulk Telemetry
 148    Transmission Mechanism, please refer to
 149    the :ref:`bulk_performance_measurement` requirements and the
 150    `5G - Bulk PM ONAP Development <https://wiki.onap.org/display/DW/5G+-+Bulk+PM>`__
 151    Wiki page.
 152
 153 .. _snmp_monitoring_requirements:
 154
 155 SNMP Monitoring Requirements
 156 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 157
 158 .. req::
 159    :id: R-261501
 160    :target: VNF or PNF
 161    :keyword: MUST
 162    :introduced: guilin
 163
 164    If the VNF or PNF is using SNMP, then the VNF or PNF Provider **MUST**
 165    provide a Management Information Base (MIB) file that uniquely identifies
 166    and describes all SNMP events exposed by the network function.
 167
 168 .. req::
 169    :id: R-233922
 170    :target: VNF or PNF
 171    :keyword: SHOULD
 172    :introduced: guilin
 173
 174    If the VNF or PNF is using SNMP, then the VNF or PNF Provider **SHOULD**
 175    provide examples of all SNMP alarms.
 176
 177 .. _ves_monitoring_requirements:
 178
 179 Virtual Function Event Streaming (VES) Client Requirements
 180 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 181
 182 The VES protocol enables NFs to transmit telemetry data in a non-proprietary,
 183 extensible format to ONAP using the HTTP protocol. This chapter will define
 184 the requirements for a NF to deliver events to ONAP's VES event listeners in
 185 a manner that conforms with the appropriate VES Event Listener specifications,
 186 and ensures the NF can be configured to maximize the reliability of telemetry
 187 data delivery.
 188
 189
 190 Event Definition and Registration
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192
 193 .. req::
 194    :id: R-520802
 195    :target: VNF or PNF PROVIDER
 196    :keyword: MUST
 197    :introduced: casablanca
 198    :validation_mode: static
 199    :impacts: dcae
 200    :updated: guilin
 201
 202    If the VNF or PNF is using VES, then the VNF or PNF Provider **MUST** provide
 203    a YAML file formatted in adherence with the
 204    :ref:`VES Event Registration specification <ves_event_registration_3_2>`
 205    that defines the following information for each event produced by the VNF:
 206
 207    * ``eventName``
 208    * Required fields
 209    * Optional fields
 210    * Any special handling to be performed for that event
 211
 212 .. req::
 213    :id: R-120182
 214    :target: VNF or PNF PROVIDER
 215    :keyword: MUST
 216    :introduced: casablanca
 217    :updated: guilin
 218    :validation_mode: static
 219    :impacts: dcae
 220
 221    A VNF or PNF Provider utilizing VES **MUST** indicate specific conditions
 222    that may arise, and recommend actions that may be taken at specific
 223    thresholds, or if specific conditions repeat within a specified time
 224    interval, using the semantics and syntax described by the
 225    :ref:`VES Event Registration specification <ves_event_registration_3_2>`.
 226
 227    **NOTE:** The Service Provider may override VNF or PNF provider Event
 228    Registrations using the ONAP SDC Design Studio to finalizes Service
 229    Provider engineering rules for the processing of the VNF or PNF events.
 230    These changes may modify any of the following:
 231
 232    * Threshold levels
 233    * Specified actions related to conditions
 234
 235 .. req::
 236    :id: R-123044
 237    :target: VNF or PNF PROVIDER
 238    :keyword: MUST
 239    :introduced: casablanca
 240    :validation_mode: in_service
 241    :impacts: dcae
 242    :updated: dublin
 243
 244    The VNF or PNF Provider **MAY** require that specific events, identified by
 245    their ``eventName``, require that certain fields, which are optional in the
 246    common event format, must be present when they are published.
 247
 248 Event Formatting and Usage
 249 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 250
 251 .. req::
 252    :id: R-570134
 253    :target: VNF or PNF
 254    :keyword: MUST
 255    :introduced: casablanca
 256    :updated: guilin
 257    :validation_mode: in_service
 258    :impacts: dcae
 259
 260    The VES events produced by the VNF or PNF **MUST** be compliant with the
 261    common event formats defined in one of the following specifications:
 262
 263    * :ref:`VES Event Listener 5.4.1<ves_event_listener_5_4_1>`
 264    * :ref:`VES Event Listener 7.1.1<ves_event_listener_7_1>`
 265    * :ref:`VES Event Listener 7.2<ves_event_listener_7_2>`
 266
 267    The latest version (7.2) should be preferred. Earlier versions are
 268    provided for backwards compatibility.
 269
 270 .. req::
 271    :id: R-528866
 272    :target: VNF or PNF
 273    :introduced: casablanca
 274    :validation_mode: in_service
 275    :impacts: dcae
 276    :keyword: MUST
 277    :updated: guilin
 278
 279    The VES events produced by the VNF or PNF **MUST** conform to the schema and
 280    other formatting requirements specified in the relevant VES Event Listener
 281    specification.
 282
 283 .. req::
 284    :id: R-283988
 285    :target: VNF or PNF
 286    :introduced: casablanca
 287    :updated: guilin
 288    :validation_mode: in_service
 289    :impacts: dcae
 290    :keyword: MUST NOT
 291
 292    A VNF or PNF producing VES events **MUST NOT** send information through
 293    extensible structures if the event specification has explicitly defined
 294    fields for that information.
 295
 296 .. req::
 297    :id: R-470963
 298    :target: VNF or PNF
 299    :introduced: casablanca
 300    :updated: guilin
 301    :validation_mode: in_service
 302    :impacts: dcae
 303    :keyword: SHOULD
 304
 305    A VNF or PNF producing VES events **SHOULD** leverage camel case to
 306    separate words and acronyms used as keys that will be sent through extensible
 307    fields. When an acronym is used as the key, then only the first letter shall
 308    be capitalized.
 309
 310 .. req::
 311    :id: R-408813
 312    :target: VNF or PNF
 313    :keyword: MUST
 314    :introduced: casablanca
 315    :updated: guilin
 316    :validation_mode: none
 317    :impacts: dcae
 318
 319    A VNF or PNF producing VES events **MUST** pass all information it is
 320    able to collect even if the information field is identified as optional.
 321    However, if the data cannot be collected, then optional fields can be
 322    omitted.
 323
 324 Configuration Requirements
 325 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 326
 327 This section defines the types the configuration options and defaults a NF
 328 producing VES events should provide to ensure the NF can be configured properly
 329 for the Service Provider's ONAP environment and ensure reliable delivery of
 330 VES events.
 331
 332 There are several methods available to provide configuration settings to a
 333 network function. This document does not specify the exact manner in which
 334 the configuration elements described below must be required. The
 335 configuration can be provided during instantiation (e.g. preload), provided by
 336 an ONAP controller action, or provided manually.
 337
 338 .. req::
 339    :id: R-460012
 340    :target: VNF or PNF
 341    :keyword: MUST
 342    :introduced: guilin
 343
 344    The VNF or PNF producing VES events **MUST** allow the configuration of
 345    the attributes defined in Table 1 and utilize the provided default value
 346    (where applicable) when the configuration value is not provided by the
 347    Service Provider.
 348
 349 .. req::
 350    :id: R-940591
 351    :target: VNF or PNF
 352    :keyword: SHOULD
 353    :introduced: guilin
 354
 355    A VNF or PNF producing VES events **SHOULD** use the recommended parameter
 356    name for the configurable value from Table 1.
 357
 358 .. table:: **Table 1**: VES Configurable Values
 359
 360    +----------------------+-----------------------------------+----------------+-------------------------------------+
 361    |Parameter             | Description                       |  Default       | Parameter Name (VES 7.2+)           |
 362    +======================+===================================+================+=====================================+
 363    |VES Listener Endpoint | FQDN or IP of the Event Listener  |       n/a      | ves_listener_endpoint               |
 364    +----------------------+-----------------------------------+----------------+-------------------------------------+
 365    |Heartbeat Interval    | Frequency in seconds the NF must  |        60      | ves_heartbeat_interval_seconds      |
 366    |                      | send a heartbeat to the event     |                |                                     |
 367    |                      | listener                          |                |                                     |
 368    +----------------------+-----------------------------------+----------------+-------------------------------------+
 369    |Timeout Value         | Duration in seconds the NF should |         5      | ves_timeout_seconds                 |
 370    |                      | wait for ACK from the event       |                |                                     |
 371    |                      | listener before timeout           |                |                                     |
 372    +----------------------+-----------------------------------+----------------+-------------------------------------+
 373    |Measurement Interval  | Window size in seconds to use for |        300     | ves_measurement_interval_seconds    |
 374    |                      | aggregated measurements           |                |                                     |
 375    +----------------------+-----------------------------------+----------------+-------------------------------------+
 376    |HTTP Username         | Required if NF supports HTTP      |        n/a     | ves_http_username                   |
 377    |                      | Basic Authentication with the     |                |                                     |
 378    |                      | VES Event Listener                |                |                                     |
 379    +----------------------+-----------------------------------+----------------+-------------------------------------+
 380    |HTTP Password         | Required if NF supports HTTP      |        n/a     | ves_http_password                   |
 381    |                      | Basic Authentication with the     |                |                                     |
 382    |                      | VES Event Listener                |                |                                     |
 383    +----------------------+-----------------------------------+----------------+-------------------------------------+
 384
 385
 386 VES Listener Endpoint and DNS Resolution
 387 ++++++++++++++++++++++++++++++++++++++++
 388
 389 In a high availability deployment of a VES Event Listener, a round-robin DNS or
 390 dynamic DNS may be used to either load balance or provide fault tolerance of
 391 the Event Listener.  Adherence to the following requirements ensure the VNF or
 392 PNF interacts properly with this deployment configuration.
 393
 394 .. req::
 395    :id: R-70492
 396    :target: VNF or PNF
 397    :keyword: MUST
 398    :introduced: guilin
 399
 400    The VNF or PNF **MUST** support DNS resolution of the VES Listener Endpoint
 401    if a Fully Qualified Domain Name (FQDN) is provided.
 402
 403 .. req::
 404    :id: R-130645
 405    :target: VNF or PNF
 406    :keyword: MUST
 407    :introduced: guilin
 408
 409    The VNF or PNF **MUST** respect the Time To Live provided by the DNS for
 410    the VES Event Listener FQDN.
 411
 412 Event Delivery Requirements
 413 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 414
 415 .. req::
 416    :id: R-06924
 417    :target: VNF or PNF
 418    :keyword: MUST
 419    :updated: guilin
 420
 421    The VNF or PNF producing VES events **MUST** deliver VES events as it
 422    becomes available or according to the configured measurement interval.
 423
 424 .. req::
 425     :id: R-655209
 426     :target: VNF or PNF
 427     :keyword: MUST
 428     :introduced: guilin
 429
 430     The VNF or PNF producing VES events **MUST** respect the configured
 431     VES Timeout Value when delivering VES events, and abort any call where
 432     the VES Event Listener does not successfully acknowledge the delivery of
 433     event(s) within the Timeout Value. These failed transactions should be
 434     buffered and retried in accordance with the
 435     :ref:`ves_buffering_requirements` Requirements.
 436
 437 .. req::
 438    :id: R-176945
 439    :target: VNF or PNF
 440    :keyword: SHOULD NOT
 441    :introduced: guilin
 442
 443    The VNF or PNF producing VES events **SHOULD NOT** send syslog events to the
 444    VES Event Listener during debug mode, but rather store syslog events locally
 445    for access or possible file transfer.
 446
 447 .. _ves_buffering_requirements:
 448
 449 Buffering and Redelivery
 450 ~~~~~~~~~~~~~~~~~~~~~~~~
 451
 452 To maximize the reliable delivery of VES events when the VES Listener becomes
 453 unavailable or unhealthy, the NF must adhere to these requirements.
 454
 455 .. req::
 456    :id: R-658596
 457    :target: VNF or PNF
 458    :keyword: MUST
 459    :introduced: guilin
 460
 461    A VNF or PNF producing VES events **MUST** buffer events that meet the
 462    following criteria if the VES Event Listener is unreachable or the request
 463    encounters a timeout.
 464
 465    * Faults with eventSeverity of ``MINOR``, ``MAJOR``, ``NORMAL``, or
 466      ``CRITICAL``
 467    * Syslog with syslogSev of ``Emergency``, ``Alert``, ``Critical``,
 468      ``Error``, or ``Warning``
 469    * All measurement events
 470
 471 .. req::
 472    :id: R-636251
 473    :target: VNF or PNF
 474    :keyword: MUST
 475    :introduced: guilin
 476
 477    A VNF or PNF producing VES events **MUST** size the event buffer
 478    referenced in R-658596 such that it can buffer a minimum of 1 hours of
 479    events under nominal load.
 480
 481 .. req::
 482    :id: R-498679
 483    :target: VNF or PNF
 484    :keyword: MAY
 485    :introduced: guilin
 486
 487    A VNF or PNF producing VES events **MAY** discard buffered events older
 488    than a maximum retention period, not less than 1 hour, even if the event
 489    was never successfully delivered to the event listener. While discarding
 490    based on this retention period is supported for backwards compatibility, it
 491    is recommended to retain events until the maximum buffer size is reached per
 492    R-346137 as that will maximize the number of events delivered.
 493
 494 .. req::
 495    :id: R-346137
 496    :target: VNF or PNF
 497    :keyword: MUST
 498    :introduced: guilin
 499
 500    A VNF or PNF producing VES events that is buffering events per R-658596
 501    **MUST** store in-scope events even when the maximum capacity of the
 502    buffer (defined in R-636251) has been reached. To make room for new events
 503    in this situation, hte oldest event in the buffer shall be removed
 504    as necessary. (i.e. First In First Out)
 505
 506 .. req::
 507    :id: R-379523
 508    :target: VNF or PNF
 509    :keyword: MUST
 510    :introduced: guilin
 511
 512    A VNF or PNF producing VES events that is buffering events due to an
 513    unavailable VES Event Listener **MUST** redeliver all buffered events
 514    according to the following rules when the VNF or PNF detects the VES Event
 515    Listener has become available:
 516
 517    * Deliver all previously buffered events before sending new events
 518    * Deliver buffered events in the order they were received
 519
 520 .. req::
 521    :id: R-818859
 522    :target: VNF or PNF
 523    :keyword: MUST
 524    :introduced: guilin
 525
 526    The VNF or PNF producing VES events **MUST** not allow an unavailable or
 527    timing out VES Event Listener to impact the performance, stability, or
 528    correct execution of network function.
 529
 530 .. req::
 531    :id: R-103464
 532    :target: VNF or PNF
 533    :keyword: MAY
 534    :introduced: guilin
 535
 536    A VNF or PNF producing VES events that is buffering events due to an
 537    unavailable VES Event Listener **MAY** leverage to ``publishEventBatch``
 538    operation to redeliver buffered events. Please note this can only be
 539    used when all buffered events belong to the same domain due to the
 540    restrictions in place for the operation.
 541
 542 Security
 543 ~~~~~~~~~~
 544
 545 .. req::
 546     :id: R-68165
 547     :target: VNF or PNF
 548     :keyword: MUST
 549     :updated: dublin
 550
 551     The VNF or PNF **MUST** encrypt any content containing Sensitive Personal
 552     Information (SPI) or certain proprietary data, in addition to applying the
 553     regular procedures for securing access and delivery.
 554
 555
 556 .. req::
 557    :id: R-33878
 558    :target: VNF or PNF
 559    :keyword: MUST
 560    :introduced: el alto
 561    :updated: guilin
 562
 563    The VNF or PNF **MUST** utilize one of the authentication methods
 564    prescribed by the relevant VES Event Listener specification.
 565
 566 .. _bulk_performance_measurement:
 567
 568 Bulk Performance Measurement
 569 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 570
 571 .. req::
 572     :id: R-841740
 573     :target: VNF or PNF
 574     :keyword: SHOULD
 575     :introduced: casablanca
 576     :impacts: dcae, dmaap
 577     :updated: dublin
 578
 579     The VNF or PNF **SHOULD** support FileReady VES event for event-driven bulk transfer
 580     of monitoring data.
 581
 582 .. req::
 583     :id: R-440220
 584     :target: VNF or PNF
 585     :keyword: SHOULD
 586     :introduced: casablanca
 587     :impacts: dcae, dmaap
 588     :updated: dublin
 589
 590     The VNF or PNF **SHOULD** support File transferring protocol, such as FTPES or SFTP,
 591     when supporting the event-driven bulk transfer of monitoring data.
 592
 593 .. req::
 594     :id: R-75943
 595     :target: VNF or PNF
 596     :keyword: SHOULD
 597     :introduced: casablanca
 598     :impacts: dcae, dmaap
 599     :updated: dublin
 600
 601     The VNF or PNF **SHOULD** support the data schema defined in 3GPP TS 32.435, when
 602     supporting the event-driven bulk transfer of monitoring data.
 603
 604 .. req::
 605     :id: R-807129
 606     :target: VNF or PNF
 607     :keyword: SHOULD
 608     :introduced: dublin
 609     :impacts: dcae, dmaap
 610
 611     The VNF or PNF **SHOULD** report the files in FileReady for as long as they are
 612     available at VNF or PNF.
 613
 614     Note: Recommended period is at least 24 hours.
 615
 616
 617 .. |image0| image:: ../Data_Model_For_Event_Records.png
 618
 619 .. |image1| image:: ../VES_JSON_Driven_Model.png
 620       :width: 5in
 621       :height: 3in
 622
 623 .. |image2| image:: ../Protocol_Buffers_Driven_Model.png
 624       :width: 4.74in
 625       :height: 3.3in
 626
 627 .. |image3| image:: ../Bulk_Data_Transfer_Mechv1.png
 628       :width: 4.74in
 629       :height: 3.3in