Event records (Section 7.4.x) will need to be updated to align with expected additional independent data fields supported by the ONAP DCAE components in Casablanca release

Updates to proposed new sections: 

— Cut Here —

7.4. Monitoring & Management

This section addresses data collection and event processing functionality that is directly dependent on the interfaces provided by the xNFs’ APIs. These can be in the form of asynchronous interfaces for event, fault notifications, and autonomous data streams. They can also be synchronous interfaces for on-demand requests to retrieve various performance, usage, and other event information. It should be understood that events are well structured packages of information, identified by an eventName, which are communicated to subscribers who are interested in the eventName. Events are simply a way of communicating well-structured packages of information to one or more instances of an Event Listener service.

The target direction for xNF interfaces is to employ APIs that are implemented utilizing standardized messaging and modeling protocols over standardized transports. Virtualized environments present a tremendous opportunity to eliminate the need for proprietary interfaces for xNF provider equipment while removing the traditional boundaries between Network Management Systems and Element Management Systems. Additionally, virtualized NFs provide the ability to instrument networking applications by creating event records to test and monitor end-to-end data flow through the network, similar to what physical or virtual probes provide without the need to insert probes at various points in the network. The xNF providers must be able to provide the aforementioned set of required data directly to the ONAP collection layer using standardized interfaces.

7.4.1. Data Model for Event Records

This section describes the data model for the collection of telemetry data from xNFs by Service Providers (SPs) to manage xNF health and run-time life cycle. This data model is referred to as the VES Data Model. The VES acronym originally stood for Virtual-function Event Streaming, but VES has been generalized to support network-function event streaming, whether virtualized or not.

The VES Data Model describes a vendor-agnostic common vocabulary of event payloads. Vendor-specific, product-specific or service-specific data is supported by the inclusion of a flexible additional information field structure. The VES Data Models' common vocabulary is used to drive standard and automated data analytics (policy-driven analytics) within the ONAP DCAE Framework.

While this document is focused on specifying some of the records from the ONAP perspective, there may be other external bodies using the same framework to specify additional records. For example, OPNFV has a VES project that is looking to specify records for OpenStack’s internal telemetry to manage application (xNFs), physical and virtual infrastructure (compute, storage, network devices, etc.) and virtual infrastructure managers (cloud controllers, SDN controllers). It uses ONAP’s VES Agent to generate VES events from the xNF and Intel’s collectD agent to generate infrastructure VES events. Note that any configurable parameters for these data records (e.g., frequency, granularity, policy-based configuration) will be managed using the “Configuration” framework described in the prior sections of this document. The infrastructure metrics have been funneled via the ONAP Multi-VIM Project and are now included in current specifications.

The Data Model consists of:

• Common Header Record: This data structure precedes each of the Technology Independent and Technology Specific records sections of the data model.
• Technology Independent Records: This version of the document specifies the model for Fault, Heartbeat, Measurements, Notification, pnfRegistration, State Change, Syslog, and Threshold Crossing Alerts records. In the future, these may be extended to support other types of technology independent records (work is currently progressing to define a new Performance Domain that would be able to support already defined 3GPP Metrics for xNF, e.g. 5G RAN device Use Case in Casablanca). Each of these records allows additional fields (name/ value pairs) for extensibility. The xNF provider may use these xNF provider-specific additional fields to provide additional information that may be relevant to the managing systems.
• Technology Specific Records: This version of the document specifies the model for Mobile Flow records, Signaling and Voice Quality records. In the future, these may be extended to support other types of records (e.g. Network Fabric, Security records, etc.). Each of these records allows additional fields (name/value pairs) for extensibility. The xNF provider can use these xNF-specific additional fields to provide additional information that may be relevant to the managing systems. A placeholder for additional technology specific areas of interest to be defined in the future documents has been depicted.

Figure 1. Data Model for Event Records

7.4.2. Event Records - Data Structure Description

The data structure for event records consists of:

• a Common Event Header block; and
• zero (Heartbeat) or more technology independent domain blocks; or
  • e.g., Fault, Measurements, Notification, PNF Registration, State Change, Syslog, TCA, Other Fields etc.
• technology specific domain blocks.
  • e.g., Mobile Flow, Signaling, Voice Quality, etc.

7.4.2.1. Common Event Header

The common header that precedes any of the domain-specific records contains information identifying the type of record to follow, information about the sender and other identifying characteristics related to the domain and event. (e.g., name, priority, sequence number, source, timestamp, type, etc.).

R-XXXXX: The following mandatory fields common to all events MUST be provided in the common event header:
 * domain - the event domain enumeration
 * eventId - the event key unique to the event source
 * eventName - the unique event name
 * lastEpochMicrosec - the latest unix time (aka epoch time) associated with the event
 * priority - the processing priority enumeration
 * reportingEntityName - name of the entity reporting the event or detecting a problem in another xNF
 * sequence - the ordering of events communicated by an event source
 * sourceName - name of the entity experiencing the event issue, which may be detected and reported by a separate reporting entity
 * startEpochMicrosec - the earliest unix time (aka epoch time) associated with the event
 * version - the version of the event header
 * vesEventListenerVersion - Version of the VES event listener API spec that this event is compliant with

7.4.2.2. Technology Independent Records

The current version of the data model supports the following technology independent event records:

• Fault - the Fault Record, describing a condition in the Fault domain, contains information about device failures. The fault event provides data such as the entity experiencing a fault, the severity, resulting status, etc.

• Heartbeat - the Heartbeat Record provides an optional structure for communicating information about device health. Heartbeat records would only have the Common Event Header block. An optional heartbeat domain is available to specify information such as heartbeat interval and recommended action upon missing heartbeat interval. Heartbeat avoids the need to ping a device.  A communication failure can be determined via missing heartbeat events being delivered to DCAE and appropriate action (e.g. restart VM, rebuild xNF or create ticket) can be taken by DCAE CLAMP.

• Measurements - the Measurements Record contains information about xNF and xNF resource structure and its condition to help in the management of the resources for purposes of capacity planning, elastic scaling, performance management and service assurance.  These are soft alarms providing an opportunity for proactive maintenance.

• Notification - the Notification Record provides a structure for communicating notification information from the NF. It can contain notification information related to the current operational state that is reported by the NF. As an example, when cards or port name of the entity have changed state. (e.g., offline -> online) Other use cases include notification of file ready for collection using Bulk Data Transfer or notification on configuration changes to a device.

• Other - the Other Record defines fields for events that do not have a defined domain but are needed to be collected and sent to DCAE. This record provides a mechanism to convey a complex set of fields (possibly nested or opaque) and is purely intended to address miscellaneous needs such as addressing time-to-market considerations or other proof-of-concept evaluations. Hence, use of this record type is discouraged and should be minimized.  (Note: the Other domain could be used to create and test new domain ideas.)

• pnfRegistration - the pnfRegistration Record provides a structure for registration of a physical network function. The pnfRegistration Record can contain information about attributes related to the physical network function including serial number, software revision, unit type and vendor name.

• State Change - the State Change Record provides a structure for communicating information about data flow through the xNF. The State Change Record can contain information about state change related to physical device that is reported by the xNF. As an example, when cards or port name of the entity that has changed state.  Note: The Notification Domain can also communicate similar information.

• Syslog - the Syslog Record provides a structure for communicating any type of information that may be logged by the xNF. It can contain information about system internal events, status, errors, etc. It is recommended that low volume control or session logs are communicated via a push mechanism, while other large volume logs should be sent via file transfer.

• Threshold Crossing Alert - the Threshold Crossing Alert (TCA) Record provides a structure for communicating information about threshold crossing alerts. It uses data from the Measurement or a similar domain to watch for a Key Performance Indicator (KPI) threshold that has been crossed. TCA provides alert definitions and types, actions, events, timestamps and physical or logical details.

7.4.2.3. Technology Specific Records

The current version of the data model supports the following technology specific event records:

• Mobile Flow - the Mobile Flow Record provides a structure for communicating information about data flow through the NF. It can contain information about connectivity and data flows between serving elements for mobile service, such as between LTE reference points, etc.

• Signaling - the Signaling Record provides a structure for communicating information about signaling messages, parameters and signaling state. It can contain information about data flows for signaling and controlling multimedia communication sessions such as voice and video calls.

• Voice Quality - the Voice Quality Record provides a structure for communicating information about voice quality statistics including media connection information, such as transmitted octet and packet counts, packet loss, packet delay variation, round-trip delay, QoS parameters and codec selection.

• Future Domains - the Future Domains Record is a placeholder for additional technology specific areas of interest that will be defined and described in the future documents.

7.4.2.4. Miscellaneous

The event specification contains various extensible structures (e.g. hashMap) that enable event publishers to send information that has not been explicitly defined.

R-XXXXX: Event publishers MUST NOT send information through extensible structures where the event specification has explicitly defined fields for that information.

R-XXXXX: Keys sent through extensible fields MUST use camel casing to separate words and acronyms; only the first letter of each acronym shall be capitalized.

R-XXXXX: If the event publisher collects an information field that is identified as optional in the data structures described, then the event publisher MUST sent that field.

7.4.3. Data Structure Specification and Registration of Event Records

R-XXXXX: All VES events MUST be registered using an extensible YAML format which specifies, for each eventName, the fields that are required, what field values may be sent, and any special handling that should be performed on those eventNames.

R-XXXXX: All registered events MUST be compliant with the common event format.

R-XXXXX: Specific events identified by their eventName MAY require that certain fields, which are optional in the common event format, be present when they are published.

For additional information on the event record format and the event record registration format for the data structures described above, please refer to the VNF Requirements Release Notes.

+++ Cut Here — these supplemental pointers, could be moved to the Release Notes document +++
For additional information on the event record format, please refer to the correct ONAP release version of the VES Event Listener document:

ONAP Beijing - VES Event Listener (Version 5.4.1)
ONAP Casablanca - VES Event Listener (Version 7.0.1) 

For additional information on the event record registration format, please refer to the correct ONAP release version of the VES Event Registration document:

ONAP Beijing - VES Event Registration (Version 1.6)
ONAP Casablanca - VES Event Registration (Version 3.0)
+++ Cut Here +++

7.4.4 Transports and Protocols Supporting Resource Interfaces

Transport mechanisms and protocols have been selected to enable both high volume and moderate volume datasets, as well as asynchronous and synchronous communications over secure connections. The specified encoding provides self-documenting content, so data fields can be changed as needs evolve, while minimizing changes to data delivery.

R-XXXXX: The xNF SHOULD deliver event records that fall into the event domains supported by VES.

R-XXXXX: The xNF MUST deliver event records from xNFs to ONAP using the common transport mechanisms and protocols defined in this document.

The term ‘Event Record’ is used throughout this document to represent various forms of telemetry or instrumentation made available by the xNFs including, faults, status events, various other types of xNF measurements and logs.

Common structures and delivery protocols for other types of data will be given in future versions of this document as we get more insight into data volumes and required processing. For additional information on specifications and versioning corresponding to a release, please refer to the VNF Requirements Release Notes.

In the following sections, we provide options for encoding, serialization and data delivery. Agreements between Service Providers and xNF providers determine which encoding, serialization and delivery method to use for particular data sets.

R-XXXXX:  The selected methods for encoding, serialization and data delivery MUST be agreed to between Service Providers and xNF providers prior to the on-boarding of the xNF into ONAP SDC Design Studio.

7.4.4.1. xNF Telemetry using VES/JSON Model

The preferred model for data delivery from a xNF to ONAP DCAE is the JSON driven model as depicted in Figure 2.

Figure 2. xNF Telemetry using VES/JSON Model

7.4.4.2. xNF Telemetry using Google Protocol Buffers

In addition to the default data delivery model described above, support for real-time performance management (PM) data sent using VES events as binary-encoded Google Protocol Buffers (GPB) and streamed via TCP Sockets for efficiency and TLS for security can also be supported, as depicted in Figure 3.
 

Figure 3. xNF Telemetry using Google Protocol Buffers

Note: For high-volume xNF telemetry, native (binary) Google Protocol Buffers (GPB) is the preferred serialization method. While supporting the GPB telemetry delivery approach described above, the default delivery method is the VES/REST JSON based model in DCAE. The purpose of the diagram above is to illustrate the GPB delivery concept only and not to imply a specific implementation.

Note: For additional information and uses cases for Real Time Performance Management and High Volume Stream Data Collection, please refer to the
5G - Real Time PM and High Volume Stream Data Collection ONAP Development Wiki page.

7.4.4.3 Bulk Telemetry Transmission Mechanism

The bulk xNF telemetry transmission mechanism consists of:

• event-driven bulk transfer of monitoring data from an xNF to ONAP/DCAE, using either the FTPES or SFTP protocols.
• an optional VES mapper micro-service that can extract selected measurements and publish them as VES events.

Figure 4. Bulk Telemetry Transmission Mechanism

Note: For additional information and uses cases for Bulk Telemetry Transmission Mechanism, please refer to the
5G - Bulk PM ONAP Development Wiki page.

7.4.5. Monitoring & Management Requirements¶

7.4.5.1. VNF telemetry via standardized interface¶

R-XXXXX: The xNF provider MUST provide a YAML artifact to the Service Provider that describes:
 * standard VES/JSON model information elements (key/values) that the xNF provides
 * any additional non-standard (custom) VES/JSON model information elements (key/values) that the xNF provides

R-XXXXX: All xNF telemetry data (e.g. fault event records, syslog records, performance records, etc.) MUST be delivered to ONAP using the standardized models and interfaces described in this section.

R-XXXXX: Event headers received by themselves MUST be used as heartbeat indicators. 

R-XXXXX:  The xNF provider MUST indicate specific conditions that may arise, and recommend actions that may be taken at specific thresholds, or if specific conditions repeat within a specified time interval, using the semantics and syntax supported by YAML.

R-XXXXX:  The Service Provider MAY create additional YAML artifacts (using ONAP Design Studio), which finalizes Service Provider engineering rules for the processing of the xNF events. 

R-XXXXX:  The Service Provider MAY alter the threshold levels recommended by the xNF provider. 

R-XXXXX:  The Service Provider MAY modify and more clearly specify actions that should be taken when specified conditions arise. 

R-XXXXX:  The Service Provider created version of the YAML artifact SHOULD be distributed to ONAP applications by the ONAP SDC Design Studio.

7.4.5.2. Encoding and Serialization¶

R-XXXXX: JSON SHOULD be used for delivery of event data from xNFs to ONAP DCAE. 

R-XXXXX: Google Protocol Buffers (GPB) MAY be used for delivery of high-volume real-time event data from xNFs to ONAP DCAE.

7.4.5.3. JSON¶

7.4.5.4. Google Protocol Buffers (GPB)¶

R-10623 - Telemetry data delivered using Google Protocol Buffers v3 (proto3) MUST be serialized using native Google Protocol Buffers (GPB) where:
* keys are represented as integers pointing to the system resources for the VNF being monitored
* values correspond to integers or strings that identify the operational state of the VNF resource, such a statistics counters and the state of a VNF resource.
* required Google Protocol Buffers (GPB) metadata is provided in the form of .proto files. 

R-XXXXX: xNF providers MUST provide to the Service Provider the additional following artifacts to support the delivery of high-volume xNF telemetry to DCAE via GPB over TLS/TCP:
 * a valid VES Event .proto definition file, to be used validate and decode an event
 * a valid high volume measurement .proto definition file, to be used for processing high volume events
 * a supporting PM content metadata file to be used by analytics applications to process high volume measurement events

7.4.5.5. Reporting Frequency¶

R-XXXXX: xNFs MUST report exactly one Measurement event per period per source name.

7.4.5.6. Addressing and Delivery Protocol¶

7.4.5.7. Asynchronous and Synchronous Data Delivery¶

7.4.5.8. Security¶

7.4.5.9. Bulk Performance Measurement¶

R-841740: The xNF *SHOULD* support FileReady VES event for event-driven bulk transfer of monitoring data.

R-440220: The xNF *SHOULD* support File transferring protocol, such as FTPES or SFTP, when supporting the event-driven bulk transfer of monitoring data.

R-75943: The xNF SHOULD support 3GPP TS 32.435 schema, when supporting the event-driven bulk transfer of monitoring data.

 — Cut Here —