docs/sections/apis/ves-hv/index.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 ========================
   5 HV-VES (High Volume VES)
   6 ========================
   7
   8 :Date: 2018-10-05
   9
  10 .. contents::
  11     :depth: 4
  12 ..
  13
  14 Overview
  15 ========
  16
  17 Component description can be found under `HV-VES Collector`_.
  18
  19 .. _HV-VES Collector: ../../services/ves-hv/index.html
  20
  21 .. _tcp_endpoint:
  22
  23 TCP Endpoint
  24 ============
  25
  26 HV-VES is exposed as NodePort service on Kubernetes cluster on port 30222/tcp.
  27 It uses plain, insecure TCP connection without socket data encryption. In Casablanca release, there is an experimental option to enable SSL/TLS (see :ref:`authorization`).
  28 Without TLS client authentication/authorization is not possible.
  29 Connections are stream-based (as opposed to request-based) and long-running.
  30
  31 Communication is wrapped with thin Wire Transfer Protocol, which mainly provides delimitation.
  32
  33 .. literalinclude:: WTP.asn
  34     :language: asn
  35
  36 Payload is binary-encoded, using Google Protocol Buffers (GPB) representation of the VES Event.
  37
  38 .. literalinclude:: VesEvent.proto
  39     :language: protobuf
  40
  41 HV-VES makes routing decisions based mostly on the content of the **Domain** parameter in the VES Common Event Header.
  42
  43 The PROTO file, which contains the VES CommonEventHeader, comes with a binary-type Payload (eventFields) parameter, where domain-specific
  44 data should be placed. Domain-specific data are encoded as well with GPB. A domain-specific PROTO file is required to decode the data.
  45
  46 Domain **perf3gpp**
  47 ===================
  48
  49 The purpose of the **perf3gpp** domain is to deliver performance measurements from a network function (NF) to ONAP in 3GPP format.
  50 The first application of this domain is frequent periodic delivery of structured RAN PM data commonly referred to as Real Time PM (RTPM).
  51 The equipment sends an event right after collecting the PM data for a granularity period.
  52
  53 The characteristics of each event in the **perf3gpp** domain:
  54
  55 - Single measured entity, for example, BTS
  56 - Single granularity period (collection *begin time* and *duration*)
  57 - Optional top-level grouping in one or more PM groups
  58 - Grouping in one or more measured objects, for example, cells
  59 - One or more reported PM values for each measured object
  60
  61 Due to the single granularity period per event, single equipment supporting multiple concurrent granularity periods might send more than one event at a given reporting time.
  62
  63 The **perf3gpp** domain is based on 3GPP specifications:
  64
  65 - `3GPP TS 28.550 <http://www.3gpp.org/ftp//Specs/archive/28_series/28.550/>`_
  66 - `3GPP TS 32.431 <http://www.3gpp.org/ftp//Specs/archive/32_series/32.431/>`_
  67 - `3GPP TS 32.436 <http://www.3gpp.org/ftp//Specs/archive/32_series/32.436/>`_
  68
  69 The event structure is changed in comparison to the one presented in 3GPP technical specifications. The 3GPP structure is enhanced to provide support for efficient transport.
  70
  71 Definitions for the **perf3gpp** domain are stored in Perf3gppFields.proto and MeasDataCollection.proto, listed below:
  72
  73 .. literalinclude:: Perf3gppFields.proto
  74     :language: protobuf
  75
  76 .. literalinclude:: MeasDataCollection.proto
  77     :language: protobuf
  78
  79
  80 API towards DMaaP
  81 =================
  82
  83 HV-VES Collector forwards incoming messages to a particular DMaaP Kafka topic based on the domain and configuration. Every Kafka record is comprised of a key and a value. In case of HV-VES:
  84
  85 - **Kafka record key** is a GPB-encoded `CommonEventHeader`.
  86 - **Kafka record value** is a GPB-encoded `VesEvent` (`CommonEventHeader` and domain-specific `eventFields`).
  87
  88 In both cases raw bytes might be extracted using ``org.apache.kafka.common.serialization.ByteArrayDeserializer``. The resulting bytes might be further passed to ``parseFrom`` methods included in classes generated from GPB definitions. WTP is not used here - it is only used in communication between PNF/VNF and the collector.
  89
  90
  91 .. _hv_ves_behaviors:
  92
  93 HV-VES behaviors
  94 ================
  95
  96 Connections with HV-VES are stream-based (as opposed to request-based) and long-running. In case of interrupted or closed connection, the collector logs such event but does not try to reconnect to client.
  97 Communication is wrapped with thin Wire Transfer Protocol, which mainly provides delimitation. Wire Transfer Protocol Frame:
  98
  99 - is dropped after decoding and validating and only GPB is used in further processing.
 100 - has to start with **MARKER_BYTE**, as defined in protocol specification (see :ref:`tcp_endpoint`). If **MARKER_BYTE** is invalid, HV-VES disconnects from client.
 101
 102 HV-VES decodes only CommonEventHeader from GPB message received. Collector does not decode or validate the rest of the GPB message and publishes it to Kafka topic intact.
 103 Kafka topic for publishing events with specific domain can be configured through Consul service as described in :ref:`run_time_configuration`.
 104 In case of Kafka service unavailability, the collector drops currently handled messages and disconnects the client.
 105
 106 Messages handling:
 107
 108 - HV-VES Collector skips messages with unknown/invalid GPB CommonEventHeader format.
 109 - HV-VES Collector skips messages with unsupported domain. Domain is unsupported if there is no route for it in configuration (see :ref:`run_time_configuration`).
 110 - HV-VES Collector skips messages with invalid Wire Frame format, unsupported WTP version or inconsistencies of data in the frame (other than invalid **MARKER_BYTE**).
 111 - HV-VES Collector interrupts connection when it encounters a message with too big GPB payload. Default maximum size and ways to change it are described in :ref:`deployment`.
 112
 113 .. note:: xNF (VNF/PNF) can split  messages bigger than 1 MiB and set `sequence` field in CommonEventHeader accordingly. It is advised to use smaller than 1 MiB messages for GPBs encoding/decoding efficiency.
 114
 115 - Skipped messages (for any of the above reasons) might not leave any trace in HV-VES logs.