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
  16 Monitoring & Management
  17 -----------------------
  18
  19 This section addresses data collection and event processing functionality that
  20 is directly dependent on the interfaces provided by the xNFs’ APIs. These can
  21 be in the form of asynchronous interfaces for event, fault notifications, and
  22 autonomous data streams. They can also be synchronous interfaces for on-demand
  23 requests to retrieve various performance, usage, and other event information.
  24 It should be understood that events are well structured packages of
  25 information, identified by an eventName, which are communicated to subscribers
  26 who are interested in the eventName. Events are simply a way of communicating
  27 well-structured packages of information to one or more instances of an Event
  28 Listener service.
  29
  30 The target direction for xNF interfaces is to employ APIs that are implemented
  31 utilizing standardized messaging and modeling protocols over standardized
  32 transports. Virtualized environments present a tremendous opportunity to
  33 eliminate the need for proprietary interfaces for xNF provider equipment while
  34 removing the traditional boundaries between Network Management Systems and
  35 Element Management Systems. Additionally, virtualized NFs provide the ability
  36 to instrument networking applications by creating event records to test and
  37 monitor end-to-end data flow through the network, similar to what physical or
  38 virtual probes provide without the need to insert probes at various points in
  39 the network. The xNF providers must be able to provide the aforementioned set
  40 of required data directly to the ONAP collection layer using standardized
  41 interfaces.
  42
  43 Data Model for Event Records
  44 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  45
  46 This section describes the data model for the collection of telemetry data from
  47 xNFs by Service Providers (SPs) to manage xNF health and run-time life cycle.
  48 This data model is referred to as the VES Data Model. The VES acronym
  49 originally stood for Virtual-function Event Streaming, but VES has been
  50 generalized to support network-function event streaming, whether virtualized or
  51 not.
  52
  53 The VES Data Model describes a vendor-agnostic common vocabulary of event
  54 payloads. Vendor-specific, product-specific or service-specific data is
  55 supported by the inclusion of a flexible additional information field
  56 structure. The VES Data Models' common vocabulary is used to drive
  57 standard and automated data analytics (policy-driven analytics) within the
  58 ONAP DCAE Framework.
  59
  60 While this document is focused on specifying some of the records from the ONAP
  61 perspective, there may be other external bodies using the same framework to
  62 specify additional records. For example, OPNFV has a VES project that is
  63 looking to specify records for OpenStack’s internal telemetry to manage
  64 application (xNFs), physical and virtual infrastructure (compute, storage,
  65 network devices, etc.) and virtual infrastructure managers (cloud controllers,
  66 SDN controllers). It uses ONAP’s VES Agent to generate VES events from the xNF
  67 and Intel’s collectD agent to generate infrastructure VES events. Note that any
  68 configurable parameters for these data records (e.g., frequency, granularity,
  69 policy-based configuration) will be managed using the "Configuration" framework
  70 described in the prior sections of this document. The infrastructure metrics
  71 have been funneled via the ONAP Multi-VIM Project and are now included in
  72 current specifications.
  73
  74 The Data Model consists of:
  75
  76    * Common Header Record: This data structure precedes each of the Technology
  77      Independent and Technology Specific records sections of the data model.
  78
  79    * Technology Independent Records: This version of the document specifies the
  80      model for Fault, Heartbeat, Measurements, Notification, pnfRegistration,
  81      State Change, Syslog, and Threshold Crossing Alerts records. In the
  82      future, these may be extended to support other types of technology
  83      independent records (work is currently progressing to define a new
  84      Performance Domain that would be able to support already defined 3GPP
  85      Metrics for xNF, e.g. 5G RAN device Use Case in Casablanca). Each of
  86      these records allows additional fields (name/ value pairs) for
  87      extensibility. The xNF provider may use these xNF provider-specific
  88      additional fields to provide additional information that may be relevant
  89      to the managing systems.
  90
  91    * Technology Specific Records: This version of the document specifies the
  92      model for Mobile Flow records, Signaling and Voice Quality records.
  93      In the future, these may be extended to support other types of records
  94      (e.g. Network Fabric, Security records, etc.). Each of these records
  95      allows additional fields (name/value pairs) for extensibility. The xNF
  96      provider can use these xNF-specific additional fields to provide
  97      additional information that may be relevant to the managing systems.
  98      A placeholder for additional technology specific areas of interest to
  99      be defined in the future documents has been depicted.
 100
 101 |image0|
 102
 103 Figure 1. Data Model for Event Records
 104
 105 Event Records - Data Structure Description
 106 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 107
 108 The data structure for event records consists of:
 109
 110 -  a Common Event Header block; and
 111
 112 -  zero (Heartbeat) or more technology independent domain blocks; or
 113
 114    -  e.g. Fault, Measurements, Notification, PNF Registration, State Change,
 115       Syslog, TCA, Other Fields etc.
 116
 117 -  technology specific domain blocks.
 118
 119    -  e.g. Mobile Flow, Signaling, Voice Quality, etc.
 120
 121 Common Event Header
 122 ~~~~~~~~~~~~~~~~~~~~~
 123
 124 The common header that precedes any of the domain-specific records contains
 125 information identifying the type of record to follow, information about the
 126 sender and other identifying characteristics related to the domain and event.
 127 (e.g., name, priority, sequence number, source, timestamp, type, etc.).
 128
 129 .. req::
 130    :id: R-528866
 131    :target: VNF
 132    :introduced: casablanca
 133    :validation_mode: in_service
 134    :impacts: dcae
 135    :keyword: MUST
 136
 137    The VNF **MUST** produce VES events that include the following mandatory
 138    fields in the common event header.
 139
 140     * ``domain`` - the event domain enumeration
 141     * ``eventId`` - the event key unique to the event source
 142     * ``eventName`` - the unique event name
 143     * ``lastEpochMicrosec`` - the latest unix time (aka epoch time) associated
 144       with the event
 145     * ``priority`` - the processing priority enumeration
 146     * ``reportingEntityName`` - name of the entity reporting the event or
 147       detecting a problem in another xNF
 148     * ``sequence`` - the ordering of events communicated by an event source
 149     * ``sourceName`` - name of the entity experiencing the event issue, which
 150       may be detected and reported by a separate reporting entity
 151     * ``startEpochMicrosec`` - the earliest unix time (aka epoch time)
 152       associated with the event
 153     * ``version`` - the version of the event header
 154     * ``vesEventListenerVersion`` - Version of the VES event listener API spec
 155       that this event is compliant with
 156
 157 Technology Independent Records – Fault Fields
 158 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 159
 160 The current version of the data model supports the following technology
 161 independent event records:
 162
 163    * ``Fault`` - the Fault Record, describing a condition in the Fault domain,
 164      contains information about device failures. The fault event provides data
 165      such as the entity experiencing a fault, the severity, resulting status,
 166      etc.
 167
 168    * ``Heartbeat`` - the Heartbeat Record provides an optional structure for
 169      communicating information about device health. Heartbeat records would
 170      only have the Common Event Header block. An optional heartbeat domain is
 171      available to specify information such as heartbeat interval and
 172      recommended action upon missing heartbeat interval. Heartbeat avoids the
 173      need to ping a device.  A communication failure can be determined via
 174      missing heartbeat events being delivered to DCAE and appropriate action
 175      (e.g. restart VM, rebuild xNF or create ticket) can be taken by DCAE
 176      CLAMP.
 177
 178    * ``Measurements`` - the Measurements Record contains information about xNF
 179      and xNF resource structure and its condition to help in the management of
 180      the resources for purposes of capacity planning, elastic scaling,
 181      performance management and service assurance.  These are soft alarms
 182      providing an opportunity for proactive maintenance.
 183
 184    * ``Notification`` - the Notification Record provides a structure for
 185      communicating notification information from the NF. It can contain
 186      notification information related to the current operational state that is
 187      reported by the NF. As an example, when cards or port name of the entity
 188      have changed state. (e.g., offline -> online) Other use cases include
 189      notification of file ready for collection using Bulk Data Transfer or
 190      notification on configuration changes to a device.
 191
 192    * ``Other`` - the Other Record defines fields for events that do not have a
 193      defined domain but are needed to be collected and sent to DCAE. This
 194      record provides a mechanism to convey a complex set of fields (possibly
 195      nested or opaque) and is purely intended to address miscellaneous needs
 196      such as addressing time-to-market considerations or other proof-of-concept
 197      evaluations. Hence, use of this record type is discouraged and should be
 198      minimized.  (Note: the Other domain could be used to create and test new
 199      domain ideas.)
 200
 201    * ``pnfRegistration`` - the pnfRegistration Record provides a structure for
 202      registration of a physical network function. The pnfRegistration Record
 203      can contain information about attributes related to the physical network
 204      function including serial number, software revision, unit type and vendor
 205      name.
 206
 207    * ``State Change`` - the State Change Record provides a structure for
 208      communicating information about data flow through the xNF. The State
 209      Change Record can contain information about state change related to
 210      physical device that is reported by the xNF. As an example, when cards or
 211      port name of the entity that has changed state.  Note: The Notification
 212      Domain can also communicate similar information.
 213
 214    * ``Syslog`` - the Syslog Record provides a structure for communicating any
 215      type of information that may be logged by the xNF. It can contain
 216      information about system internal events, status, errors, etc. It is
 217      recommended that low volume control or session logs are communicated via a
 218      push mechanism, while other large volume logs should be sent via file
 219      transfer.
 220
 221    * ``Threshold Crossing Alert`` - the Threshold Crossing Alert (TCA) Record
 222      provides a structure for communicating information about threshold
 223      crossing alerts. It uses data from the Measurement or a similar domain to
 224      watch for a Key Performance Indicator (KPI) threshold that has been
 225      crossed. TCA provides alert definitions and types, actions, events,
 226      timestamps and physical or logical details.
 227
 228
 229 Technology Specific Records
 230 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 231
 232 The current version of the data model supports the following technology
 233 specific event records:
 234
 235    * ``Mobile Flow`` - the Mobile Flow Record provides a structure for
 236      communicating information about data flow through the NF. It can contain
 237      information about connectivity and data flows between serving elements for
 238      mobile service, such as between LTE reference points, etc.
 239
 240    * ``Signaling`` - the Signaling Record provides a structure for
 241      communicating information about signaling messages, parameters and
 242      signaling state. It can contain information about data flows for signaling
 243      and controlling multimedia communication sessions such as voice and video
 244      calls.
 245
 246    * ``Voice Quality`` - the Voice Quality Record provides a structure for
 247      communicating information about voice quality statistics including media
 248      connection information, such as transmitted octet and packet counts,
 249      packet loss, packet delay variation, round-trip delay, QoS parameters and
 250      codec selection.
 251
 252    * ``Future Domains`` - the Future Domains Record is a placeholder for
 253      additional technology specific areas of interest that will be defined and
 254      described in the future documents.
 255
 256 Miscellaneous
 257 ~~~~~~~~~~~~~
 258
 259 The event specification contains various extensible structures (e.g. hashMap)
 260 that enable event publishers to send information that has not been explicitly
 261 defined.
 262
 263 .. req::
 264    :id: R-283988
 265    :target: VNF
 266    :introduced: casablanca
 267    :validation_mode: in_service
 268    :impacts: dcae
 269    :keyword: MUST NOT
 270
 271    The VNF, when publishing events, **MUST NOT** send information through
 272    extensible structures if the event specification has explicitly defined
 273    fields for that information.
 274
 275 .. req::
 276    :id: R-470963
 277    :target: VNF
 278    :introduced: casablanca
 279    :validation_mode: in_service
 280    :impacts: dcae
 281    :keyword: MUST
 282
 283    The VNF, when publishing events, **MUST** leverage camel case to separate
 284    words and acronyms used as keys that will be sent through extensible fields.
 285    When an acronym is used as the key, then only the first letter shall be
 286    capitalized.
 287
 288 .. req::
 289    :id: R-408813
 290    :target: VNF
 291    :keyword: MUST
 292    :introduced: casablanca
 293    :validation_mode: none
 294    :impacts: dcae
 295
 296    The VNF, when publishing events, **MUST** pass all information it is
 297    able to collect even if the information field is identified as optional.
 298    However, if the data cannot be collected, then optional fields can be
 299    omitted.
 300
 301
 302 Data Structure Specification of the Event Record
 303 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 304
 305 .. req::
 306    :id: R-520802
 307    :target: XNF PROVIDER
 308    :keyword: MUST
 309    :introduced: casablanca
 310    :validation_mode: static
 311    :impacts: dcae
 312
 313    The xNF provider **MUST** provide a YAML file formatted in adherence with
 314    the :doc:`VES Event Registration specification <../../../../vnfsdk/model.git/docs/files/VESEventRegistration_3_0>`
 315    that defines the following information for each event produced by the VNF:
 316
 317    * ``eventName``
 318    * Required fields
 319    * Optional fields
 320    * Any special handling to be performed for that event
 321
 322 .. req::
 323    :id: R-120182
 324    :target: XNF PROVIDER
 325    :keyword: MUST
 326    :introduced: casablanca
 327    :validation_mode: static
 328    :impacts: dcae
 329
 330    The xNF provider **MUST** indicate specific conditions that may arise, and
 331    recommend actions that may be taken at specific thresholds, or if specific
 332    conditions repeat within a specified time interval, using the semantics and
 333    syntax described by the :doc:`VES Event Registration specification <../../../../vnfsdk/model.git/docs/files/VESEventRegistration_3_0>`.
 334
 335 **NOTE:** The Service Provider may override xNF provider Event
 336 Registrations using the ONAP SDC Design Studio to finalizes Service
 337 Provider engineering rules for the processing of the xNF events.
 338 These changes may modify any of the following:
 339
 340 * Threshold levels
 341 * Specified actions related to conditions
 342
 343
 344 .. req::
 345    :id: R-570134
 346    :target: XNF
 347    :keyword: MUST
 348    :introduced: casablanca
 349    :validation_mode: in_service
 350    :impacts: dcae
 351
 352    The events produced by the xNF **MUST** must be compliant with the common
 353    event format defined in the
 354    :doc:`VES Event Listener<../../../../vnfsdk/model.git/docs/files/VESEventListener_7_0_1>`
 355    specification.
 356
 357 .. req::
 358    :id: R-123044
 359    :target: XNF PROVIDER
 360    :keyword: MUST
 361    :introduced: casablanca
 362    :validation_mode: in_service
 363    :impacts: dcae
 364
 365    The xNF Provider **MAY** require that specific events, identified by their
 366    ``eventName``, require that certain fields, which are optional in the common
 367    event format, must be present when they are published.
 368
 369
 370 Transports and Protocols Supporting Resource Interfaces
 371 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 372
 373 Transport mechanisms and protocols have been selected to enable both high
 374 volume and moderate volume data sets, as well as asynchronous and synchronous
 375 communications over secure connections. The specified encoding provides
 376 self-documenting content, so data fields can be changed as needs evolve, while
 377 minimizing changes to data delivery.
 378
 379 .. req::
 380    :id: R-798933
 381    :target: XNF
 382    :keyword: SHOULD
 383    :impacts: dcae
 384    :validation_mode: in_service
 385    :introduced: casablanca
 386
 387    The xNF **SHOULD** deliver event records that fall into the event domains
 388    supported by VES.
 389
 390 .. req::
 391    :id: R-821839
 392    :target: XNF
 393    :keyword: MUST
 394    :impacts: dcae
 395    :validation_mode: in_service
 396    :introduced: casablanca
 397
 398    The xNF **MUST** deliver event records to ONAP using the common transport
 399    mechanisms and protocols defined in this document.
 400
 401 The term ‘Event Record’ is used throughout this document to represent various
 402 forms of telemetry or instrumentation made available by the xNFs
 403 including, faults, status events, various other types of xNF measurements
 404 and logs.
 405
 406 Common structures and delivery protocols for other types of data will be given
 407 in future versions of this document as we gain more insight into data volumes
 408 and required processing.
 409
 410 In the following sections, we provide options for encoding, serialization and
 411 data delivery. Agreements between Service Providers and xNF providers determine
 412 which encoding, serialization and delivery method to use for particular
 413 data sets.
 414
 415 .. req::
 416    :id: R-932071
 417    :target: XNF
 418    :keyword: MUST
 419    :impacts: dcae
 420    :validation_mode: none
 421    :introduced: casablanca
 422
 423    The xNF provider **MUST** reach agreement with the Service Provider on
 424    the selected methods for encoding, serialization and data delivery
 425    prior to the on-boarding of the xNF into ONAP SDC Design Studio.
 426
 427
 428 xNF Telemetry using VES/JSON Model
 429 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 430
 431 .. req::
 432    :id: R-659655
 433    :target: XNF
 434    :keyword: SHOULD
 435    :impacts: dcae
 436    :validation_mode: in_service
 437    :introduced: casablanca
 438
 439    The xNF **SHOULD** leverage the JSON-driven model, as depicted in Figure 2,
 440    for data delivery unless there are specific performance or operational
 441    concerns agreed upon by the Service Provider that would warrant using an
 442    alternate model.
 443
 444 |image1|
 445
 446 Figure 2. VES/JSON Driven Model
 447
 448 xNF Telemetry using Google Protocol Buffers
 449 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 450
 451 .. req::
 452    :id: R-697654
 453    :target: XNF
 454    :keyword: MAY
 455    :impacts: dcae
 456    :validation_mode: in_service
 457    :introduced: casablanca
 458
 459    The xNF **MAY** leverage the Google Protocol Buffers (GPB) delivery model
 460    depicted in Figure 3 to support real-time performance management (PM) data.
 461    In this model the VES events are streamed as binary-encoded GBPs over via
 462    TCP sockets.
 463
 464 |image2|
 465
 466 Figure 3. xNF Telemetry using Google Protocol Buffers
 467
 468
 469 **NOTE:** For high-volume xNF telemetry, native (binary) Google Protocol
 470 Buffers (GPB) is the preferred serialization method. While supporting the GPB
 471 telemetry delivery approach described above, the default delivery method
 472 is the VES/REST JSON based model in DCAE. The purpose of the diagram above
 473 is to illustrate the GPB delivery concept only and not to imply a specific
 474 implementation.
 475
 476 For additional information and uses cases for Real Time Performance
 477 Management and High Volume Stream Data Collection, please refer to the
 478 `5G - Real Time PM and High Volume Stream Data Collection ONAP Development <https://wiki.onap.org/display/DW/5G+-+Real+Time+PM+and+High+Volume+Stream+Data+Collection>`__
 479 Wiki page.
 480
 481 Bulk Telemetry Transmission
 482 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 483
 484 .. req::
 485    :id: R-908291
 486    :target: XNF
 487    :keyword: MAY
 488    :introduced: casablanca
 489    :impacts: dcae, dmaap
 490    :validation_mode: in_service
 491
 492    The XNF **MAY** leverage bulk xNF telemetry transmission mechanism, as
 493    depicted in Figure 4, in instances where other transmission methods are not
 494    practical or advisable.
 495
 496 |image3|
 497
 498 Figure 4. xNF Telemetry using Bulk Transmission
 499
 500 **NOTE:** An optional VES mapper micro-service can be leveraged to to extract
 501 measurements and publish them as VES events.
 502
 503 For additional information and use cases for the Bulk Telemetry Transmission
 504 Mechanism, please refer to the `5G - Bulk PM ONAP Development <https://wiki.onap.org/display/DW/5G+-+Bulk+PM>`__
 505 Wiki page.
 506
 507 Monitoring & Management Requirements
 508 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 509
 510 VNF telemetry via standardized interface
 511 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 512
 513 .. req::
 514    :id: R-821473
 515    :target: XNF
 516    :keyword: MUST
 517    :introduced: casablanca
 518    :impacts: dcae
 519    :validation_mode: in_service
 520
 521    The xNF MUST produce heartbeat indicators consisting of events containing
 522    the common event header only per the VES Listener Specification.
 523
 524
 525 JSON
 526 ~~~~~~~~~~~~~~~~~~
 527
 528 .. req::
 529     :id: R-19624
 530     :target: XNF
 531     :keyword: MUST
 532     :updated: casablanca
 533
 534     The xNF, when leveraging JSON for events, **MUST** encode and serialize
 535     content delivered to ONAP using JSON (RFC 7159) plain text format.
 536     High-volume data is to be encoded and serialized using
 537     `Avro <http://avro.apache.org/>`_, where the Avro [#7.4.1]_ data
 538     format are described using JSON.
 539
 540 Note:
 541
 542   - JSON plain text format is preferred for moderate volume data sets
 543     (option 1), as JSON has the advantage of having well-understood simple
 544     processing and being human-readable without additional decoding. Examples
 545     of moderate volume data sets include the fault alarms and performance
 546     alerts, heartbeat messages, measurements used for xNF scaling and syslogs.
 547   - Binary format using Avro is preferred for high volume data sets
 548     (option 2) such as mobility flow measurements and other high-volume
 549     streaming events (such as mobility signaling events or SIP signaling)
 550     or bulk data, as this will significantly reduce the volume of data
 551     to be transmitted. As of the date of this document, all events are
 552     reported using plain text JSON and REST.
 553   - Avro content is self-documented, using a JSON schema. The JSON schema is
 554     delivered along with the data content
 555     (http://avro.apache.org/docs/current/ ). This means the presence and
 556     position of data fields can be recognized automatically, as well as the
 557     data format, definition and other attributes. Avro content can be
 558     serialized as JSON tagged text or as binary. In binary format, the
 559     JSON schema is included as a separate data block, so the content is
 560     not tagged, further compressing the volume. For streaming data, Avro
 561     will read the schema when the stream is established and apply the
 562     schema to the received content.
 563
 564 In addition to the preferred method (JSON), content can be delivered
 565 from xNFs to ONAP can be encoded and serialized using Google Protocol
 566 Buffers (GPB).
 567
 568 Google Protocol Buffers (GPB)
 569 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 570
 571 .. req::
 572    :id: R-257367
 573    :target: XNF
 574    :keyword: MUST
 575    :introduced: casablanca
 576    :validation_mode: in_service
 577
 578    The xNF, when leveraging Google Protocol Buffers for events, **MUST**
 579    serialize the events using native Google Protocol Buffers (GPB) according
 580    to the following guidelines:
 581
 582       * The keys are represented as integers pointing to the system resources
 583         for the xNF being monitored
 584       * The values correspond to integers or strings that identify the
 585         operational state of the VNF resource, such a statistics counters and
 586         the state of an xNF resource.
 587       * The required Google Protocol Buffers (GPB) metadata is provided in the
 588         form of .proto files.
 589
 590 .. req::
 591    :id: R-978752
 592    :target: XNF PROVIDER
 593    :keyword: MUST
 594    :introduced: casablanca
 595    :validation_mode: static
 596
 597    The xNF providers **MUST** provide the Service Provider the following
 598    artifacts to support the delivery of high-volume xNF telemetry to
 599    DCAE via GPB over TLS/TCP:
 600
 601       * A valid VES Event .proto definition file, to be used validate and
 602         decode an event
 603       * A valid high volume measurement .proto definition file, to be used for
 604         processing high volume events
 605       * A supporting PM content metadata file to be used by analytics
 606         applications to process high volume measurement events
 607
 608 Reporting Frequency
 609 ~~~~~~~~~~~~~~~~~~~~~
 610
 611 .. req::
 612    :id: R-146931
 613    :target: XNF
 614    :keyword: MUST
 615    :introduced: casablanca
 616    :validation_mode: in_service
 617
 618    The xNF **MUST** report exactly one Measurement event per period
 619    per source name.
 620
 621 .. req::
 622     :id: R-98191
 623     :target: XNF
 624     :keyword: MUST
 625
 626     The xNF **MUST** vary the frequency that asynchronous data
 627     is delivered based on the content and how data may be aggregated or
 628     grouped together.
 629
 630         Note:
 631
 632         - For example, alarms and alerts are expected to be delivered as
 633           soon as they appear. In contrast, other content, such as performance
 634           measurements, KPIs or reported network signaling may have various
 635           ways of packaging and delivering content. Some content should be
 636           streamed immediately; or content may be monitored over a time
 637           interval, then packaged as collection of records and delivered
 638           as block; or data may be collected until a package of a certain
 639           size has been collected; or content may be summarized statistically
 640           over a time interval, or computed as a KPI, with the summary or KPI
 641           being delivered.
 642         - We expect the reporting frequency to be configurable depending on
 643           the virtual network functions needs for management. For example,
 644           Service Provider may choose to vary the frequency of collection
 645           between normal and trouble-shooting scenarios.
 646         - Decisions about the frequency of data reporting will affect
 647           the size of delivered data sets, recommended delivery method,
 648           and how the data will be interpreted by ONAP. These considerations
 649           should not affect deserialization and decoding of the data, which
 650           will be guided by the accompanying JSON schema or GPB definition
 651           files.
 652
 653 Addressing and Delivery Protocol
 654 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 655
 656 ONAP destinations can be addressed by URLs for RESTful data PUT. Future
 657 data sets may also be addressed by host name and port number for TCP
 658 streaming, or by host name and landing zone directory for SFTP transfer
 659 of bulk files.
 660
 661 .. req::
 662     :id: R-88482
 663     :target: XNF
 664     :keyword: SHOULD
 665
 666     The xNF **SHOULD** use REST using HTTPS delivery of plain
 667     text JSON for moderate sized asynchronous data sets, and for high
 668     volume data sets when feasible.
 669
 670 .. req::
 671     :id: R-84879
 672     :target: XNF
 673     :keyword: MUST
 674
 675     The xNF **MUST** have the capability of maintaining a primary
 676     and backup DNS name (URL) for connecting to ONAP collectors, with the
 677     ability to switch between addresses based on conditions defined by policy
 678     such as time-outs, and buffering to store messages until they can be
 679     delivered. At its discretion, the service provider may choose to populate
 680     only one collector address for a xNF. In this case, the network will
 681     promptly resolve connectivity problems caused by a collector or network
 682     failure transparently to the xNF.
 683
 684 .. req::
 685     :id: R-81777
 686     :target: XNF
 687     :keyword: MUST
 688
 689     The xNF **MUST** be configured with initial address(es) to use
 690     at deployment time. Subsequently, address(es) may be changed through
 691     ONAP-defined policies delivered from ONAP to the xNF using PUTs to a
 692     RESTful API, in the same manner that other controls over data reporting
 693     will be controlled by policy.
 694
 695 .. req::
 696     :id: R-08312
 697     :target: XNF
 698     :keyword: MAY
 699
 700     The xNF **MAY** use another option which is expected to include REST
 701     delivery of binary encoded data sets.
 702
 703 .. req::
 704     :id: R-79412
 705     :target: XNF
 706     :keyword: MAY
 707
 708     The xNF **MAY** use another option which is expected to include TCP
 709     for high volume streaming asynchronous data sets and for other high volume
 710     data sets. TCP delivery can be used for either JSON or binary encoded data
 711     sets.
 712
 713 .. req::
 714     :id: R-01033
 715     :target: XNF
 716     :keyword: MAY
 717
 718     The xNF **MAY** use another option which is expected to include SFTP
 719     for asynchronous bulk files, such as bulk files that contain large volumes
 720     of data collected over a long time interval or data collected across many
 721     xNFs. (Preferred is to reorganize the data into more frequent or more focused
 722     data sets, and deliver these by REST or TCP as appropriate.)
 723
 724 .. req::
 725     :id: R-63229
 726     :target: XNF
 727     :keyword: MAY
 728
 729     The xNF **MAY** use another option which is expected to include REST
 730     for synchronous data, using RESTCONF (e.g., for xNF state polling).
 731
 732 .. req::
 733     :id: R-03070
 734     :target: XNF
 735     :keyword: MUST
 736
 737     The xNF **MUST**, by ONAP Policy, provide the ONAP addresses
 738     as data destinations for each xNF, and may be changed by Policy while
 739     the xNF is in operation. We expect the xNF to be capable of redirecting
 740     traffic to changed destinations with no loss of data, for example from
 741     one REST URL to another, or from one TCP host and port to another.
 742
 743 Asynchronous and Synchronous Data Delivery
 744 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 745
 746 .. req::
 747     :id: R-06924
 748     :target: XNF
 749     :keyword: MUST
 750
 751     The xNF **MUST** deliver asynchronous data as data becomes
 752     available, or according to the configured frequency.
 753
 754 .. req::
 755     :id: R-73285
 756     :target: XNF
 757     :keyword: MUST
 758
 759     The xNF **MUST** must encode, address and deliver the data
 760     as described in the previous paragraphs.
 761
 762 .. req::
 763     :id: R-42140
 764     :target: XNF
 765     :keyword: MUST
 766
 767     The xNF **MUST** respond to data requests from ONAP as soon
 768     as those requests are received, as a synchronous response.
 769
 770 .. req::
 771     :id: R-34660
 772     :target: XNF
 773     :keyword: MUST
 774
 775     The xNF **MUST** use the RESTCONF/NETCONF framework used by
 776     the ONAP configuration subsystem for synchronous communication.
 777
 778 .. req::
 779     :id: R-86586
 780     :target: XNF
 781     :keyword: MUST
 782
 783     The xNF **MUST** use the YANG configuration models and RESTCONF
 784     [RFC8040] (https://tools.ietf.org/html/rfc8040).
 785
 786 .. req::
 787     :id: R-11240
 788     :target: XNF
 789     :keyword: MUST
 790
 791     The xNF **MUST** respond with content encoded in JSON, as
 792     described in the RESTCONF specification. This way the encoding of a
 793     synchronous communication will be consistent with Avro.
 794
 795 .. req::
 796     :id: R-70266
 797     :target: XNF
 798     :keyword: MUST
 799
 800     The xNF **MUST** respond to an ONAP request to deliver the
 801     current data for any of the record types defined in
 802     `Event Records - Data Structure Description`_ by returning the requested
 803     record, populated with the current field values. (Currently the defined
 804     record types include fault fields, mobile flow fields, measurements for
 805     xNF scaling fields, and syslog fields. Other record types will be added
 806     in the future as they become standardized and are made available.)
 807
 808 .. req::
 809    :id: R-332680
 810    :target: XNF
 811    :keyword: SHOULD
 812    :impacts: dcae
 813    :validation_mode: in_service
 814    :introduced: casablanca
 815
 816    The xNF **SHOULD** deliver all syslog messages to the VES Collector per the
 817    specifications in Monitoring and Management chapter.
 818
 819 .. req::
 820     :id: R-46290
 821     :target: XNF
 822     :keyword: MUST
 823
 824     The xNF **MUST** respond to an ONAP request to deliver granular
 825     data on device or subsystem status or performance, referencing the YANG
 826     configuration model for the xNF by returning the requested data elements.
 827
 828 .. req::
 829     :id: R-43327
 830     :target: XNF
 831     :keyword: SHOULD
 832
 833     The xNF **SHOULD** use `Modeling JSON text with YANG
 834     <https://tools.ietf.org/html/rfc7951>`_, If YANG models need to be
 835     translated to and from JSON{RFC7951]. YANG configuration and content can
 836     be represented via JSON, consistent with Avro, as described in "Encoding
 837     and Serialization" section.
 838
 839 Security
 840 ~~~~~~~~~~
 841
 842 .. req::
 843     :id: R-42366
 844     :target: XNF
 845     :keyword: MUST
 846
 847     The xNF **MUST** support secure connections and transports such as
 848     Transport Layer Security (TLS) protocol
 849     [`RFC5246 <https://tools.ietf.org/html/rfc5246>`_] and should adhere to
 850     the best current practices outlined in
 851     `RFC7525 <https://tools.ietf.org/html/rfc7525>`_.
 852
 853 .. req::
 854     :id: R-44290
 855     :target: XNF
 856     :keyword: MUST
 857
 858     The xNF **MUST** control access to ONAP and to xNFs, and creation
 859     of connections, through secure credentials, log-on and exchange mechanisms.
 860
 861 .. req::
 862     :id: R-47597
 863     :target: XNF
 864     :keyword: MUST
 865
 866     The xNF **MUST** carry data in motion only over secure connections.
 867
 868 .. req::
 869     :id: R-68165
 870     :target: XNF
 871     :keyword: MUST
 872
 873     The xNF **MUST** encrypt any content containing Sensitive Personal
 874     Information (SPI) or certain proprietary data, in addition to applying the
 875     regular procedures for securing access and delivery.
 876
 877 .. req::
 878     :id: R-01427
 879     :target: XNF
 880     :keyword: MUST
 881     :introduced: casablanca
 882     :updated: dublin
 883
 884     The xNF **MUST** support the provisioning of security and authentication
 885     parameters (HTTP username and password) in order to be able to authenticate
 886     with DCAE (in ONAP).
 887
 888     Note: In R3, a username and password are used with the DCAE VES Event
 889     Listener which are used for HTTP Basic Authentication.
 890
 891     Note: The configuration management and provisioning software are specific
 892     to a vendor architecture.
 893
 894 .. req::
 895     :id: R-894004
 896     :target: XNF
 897     :keyword: MUST
 898     :introduced: casablanca
 899     :updated: dublin
 900
 901     When the xNF sets up a HTTP or HTTPS connection to the collector, it **MUST**
 902     provide a username and password to the DCAE VES Collector for HTTP Basic
 903     Authentication.
 904
 905     Note: HTTP Basic Authentication has 4 steps: Request, Authenticate,
 906     Authorization with Username/Password Credentials, and Authentication Status
 907     as per RFC7617 and RFC 2617.
 908
 909 Bulk Performance Measurement
 910 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 911
 912 .. req::
 913     :id: R-841740
 914     :target: XNF
 915     :keyword: SHOULD
 916     :introduced: casablanca
 917     :impacts: dcae, dmaap
 918
 919     The xNF **SHOULD** support FileReady VES event for event-driven bulk transfer
 920     of monitoring data.
 921
 922
 923 .. req::
 924     :id: R-440220
 925     :target: XNF
 926     :keyword: SHOULD
 927     :introduced: casablanca
 928     :impacts: dcae, dmaap
 929
 930     The xNF **SHOULD** support File transferring protocol, such as FTPES or SFTP,
 931     when supporting the event-driven bulk transfer of monitoring data.
 932
 933 .. req::
 934     :id: R-75943
 935     :target: XNF
 936     :keyword: SHOULD
 937     :introduced: casablanca
 938     :impacts: dcae, dmaap
 939
 940     The xNF **SHOULD** support the data schema defined in 3GPP TS 32.435, when
 941     supporting the event-driven bulk transfer of monitoring data.
 942
 943 .. req::
 944     :id: R-807129
 945     :target: VNF or PNF
 946     :keyword: SHOULD
 947     :introduced: dublin
 948     :impacts: dcae, dmaap
 949
 950     The VNF or PNF **SHOULD** report the files in FileReady for as long as they are
 951     available at VNF or PNF.
 952
 953     Note: Recommended period is at least 24 hours.
 954
 955
 956
 957 .. |image0| image:: ../Data_Model_For_Event_Records.png
 958
 959 .. |image1| image:: ../VES_JSON_Driven_Model.png
 960       :width: 5in
 961       :height: 3in
 962
 963 .. |image2| image:: ../Protocol_Buffers_Driven_Model.png
 964       :width: 4.74in
 965       :height: 3.3in
 966
 967 .. |image3| image:: ../Bulk_Data_Transfer_Mechv1.PNG
 968       :width: 4.74in
 969       :height: 3.3in