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