Update API section with WTP definition
Change-Id: I611602ad52df6b954fda2b3217534472c2270cb2
Issue-ID: DCAEGEN2-858
Signed-off-by: Piotr Jaszczyk <piotr.jaszczyk@nokia.com>
diff --git a/docs/sections/apis/VesEvent.proto b/docs/sections/apis/ves-hv/VesEvent.proto
similarity index 81%
rename from docs/sections/apis/VesEvent.proto
rename to docs/sections/apis/ves-hv/VesEvent.proto
index 0f9e5e1..dbe0aa3 100644
--- a/docs/sections/apis/VesEvent.proto
+++ b/docs/sections/apis/ves-hv/VesEvent.proto
@@ -20,25 +20,26 @@
syntax = "proto3";
package org.onap.ves;
-message VesEvent {
+message VesEvent // top-level message, currently the maximum event size supported by the HV-VES Collector is 1 MiB
+{
CommonEventHeader commonEventHeader=1; // required
bytes eventFields=2; // required, payload
- // this field contains a domain-specific GPB message
- // the field being opaque (bytes), the decoding of the payload occurs in a separate step
- // the name of the GPB message for domain XYZ is XYZFields
- // e.g. for domain==HVMEAS, the GPB message is HVMEASFields
+ // this field contains a domain-specific GPB message
+ // the field being opaque (bytes), the decoding of the payload occurs in a separate step
+ // the name of the GPB message for domain XYZ is XyzFields
+ // e.g. for domain==perf3gpp, the GPB message is Perf3gppFields
}
// VES CommonEventHeader adapted to GPB (Google Protocol Buffers)
-// Aligned with VES 7.0.1 schema, and extending to hvMeas Domain.
+// Aligned with VES 7.0.1 schema, and extending to Performance Domain.
message CommonEventHeader
{
- string version = 1; // required, "version of the gpb common event header"
+ string version = 1; // required, "version of the gpb common event header", current value "1.0"
string domain = 2; // required, "the eventing domain associated with the event", allowed values:
- // FAULT, HEARTBEAT, MEASUREMENT, MOBILE_FLOW, OTHER, PNFREGISTRATION, SIP_SIGNALING,
- // STATE_CHANGE, SYSLOG, THRESHOLD_CROSSING_ALERT, VOICE_QUALITY, HVMEAS
+ // fault, heartbeat, measurement, mobileFlow, other, pnfRegistration, sipSignaling,
+ // stateChange, syslog, thresholdCrossingAlert, voiceQuality, perf3gpp
uint32 sequence = 3; // required, "ordering of events communicated by an event source instance or 0 if not needed"
@@ -68,7 +69,7 @@
bytes sourceId = 15; // "UUID identifying the entity experiencing the event issue; must be populated by the ATT enrichment process"
string sourceName = 16; // required, "name of the entity experiencing the event issued use A&AI entry"
string timeZoneOffset = 17; // "Offset to GMT to indicate local time zone for the device"
- string vesEventListenerVersion = 18; // required, "Version of the VesEvent Listener"
+ string vesEventListenerVersion = 18; // required, "Version of the VesEvent Listener", current value "7.0.2"
reserved "InternalHeaderFields"; // "enrichment fields for internal VES Event Listener service use only, not supplied by event sources"
reserved 100;
diff --git a/docs/sections/apis/ves-hv/WTP.asn b/docs/sections/apis/ves-hv/WTP.asn
new file mode 100644
index 0000000..3c0178d
--- /dev/null
+++ b/docs/sections/apis/ves-hv/WTP.asn
@@ -0,0 +1,17 @@
+-- Wire Transfer Protocol (binary, defined using ASN.1 notation)
+-- Encoding: use "direct encoding" to the number of octets indicated in the comment [n], using network byte order.
+
+WTP DEFINITIONS ::= BEGIN
+
+-- Used to sent data from the data provider
+WtpData ::= SEQUENCE {
+ magic INTEGER (0..255), -- [1] always 0xAA
+ versionMajor INTEGER (0..255), -- [1] major interface version, forward incompatible with previous major version, current value: 1
+ versionMinor INTEGER (0..255), -- [1] minor interface version, forward compatible with previous minor version, current value: 0
+ reserved OCTET STRING (SIZE (3)), -- [3] reserved for future use (ignored, but use 0)
+ payloadId INTEGER (0..65535), -- [2] payload type: 0x0000=undefined, 0x0001=ONAP VesEvent (protobuf)
+ payloadLength INTEGER (0..4294967295). -- [4] payload length in octets
+ payload OCTET STRING -- [length as per payloadLength]
+}
+
+END
diff --git a/docs/sections/apis/ves-hv.rst b/docs/sections/apis/ves-hv/index.rst
similarity index 88%
rename from docs/sections/apis/ves-hv.rst
rename to docs/sections/apis/ves-hv/index.rst
index 2045b6b..799f92d 100644
--- a/docs/sections/apis/ves-hv.rst
+++ b/docs/sections/apis/ves-hv/index.rst
@@ -5,7 +5,7 @@
HV-VES (High Volume VES)
========================
-:Date: 2018-09-24
+:Date: 2018-10-05
.. contents::
:depth: 3
@@ -16,7 +16,7 @@
Component description can be found under `HV-VES Collector`_.
-.. _HV-VES Collector: ../services/ves-hv/index.html
+.. _HV-VES Collector: ../../services/ves-hv/index.html
TCP Endpoint
@@ -27,6 +27,11 @@
Without TLS client authentication/authorization is not possible.
Connections are stream-based (as opposed to request-based) and long running.
+Communication is wrapped with thin Wire Transfer Protocol, which mainly provides delimitation.
+
+.. literalinclude:: WTP.asn
+ :language: asn
+
Payload is binary-encoded, currently using Google Protocol Buffers representation of the VES Common Header.
.. literalinclude:: VesEvent.proto
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
index 937cc8f..c5c652e 100644
--- a/docs/sections/offeredapis.rst
+++ b/docs/sections/offeredapis.rst
@@ -9,7 +9,7 @@
apis/deployment-handler.rst
apis/inventory.rst
apis/ves.rst
- apis/ves-hv.rst
+ apis/ves-hv/index.rst
apis/dcaecdap.rst
apis/PRH.rst