summaryrefslogtreecommitdiffstats
path: root/docs/sections/apis
diff options
context:
space:
mode:
authorFilip Krzywka <filip.krzywka@nokia.com>2018-09-25 14:43:18 +0200
committerFilip Krzywka <filip.krzywka@nokia.com>2018-10-01 09:42:15 +0200
commitcbd2ded4ce08fd70b8e75b3ef5f0e36286687106 (patch)
treeb91f94722bf753377d83c42104ebc8bc084427da /docs/sections/apis
parent4bb79b722985784e650243248e7450e279485fa9 (diff)
Populate HV-VES API section of the documentation
Change-Id: Id5082cf8918d4568c5ae735e14ee63e0ab9ee5a8 Issue-ID: DCAEGEN2-832 Signed-off-by: Filip Krzywka <filip.krzywka@nokia.com>
Diffstat (limited to 'docs/sections/apis')
-rw-r--r--docs/sections/apis/VesEvent.proto75
-rw-r--r--docs/sections/apis/ves-hv.rst38
2 files changed, 112 insertions, 1 deletions
diff --git a/docs/sections/apis/VesEvent.proto b/docs/sections/apis/VesEvent.proto
new file mode 100644
index 00000000..0f9e5e1f
--- /dev/null
+++ b/docs/sections/apis/VesEvent.proto
@@ -0,0 +1,75 @@
+/*
+ * ============LICENSE_START=======================================================
+ * dcaegen2-collectors-veshv
+ * ================================================================================
+ * Copyright (C) 2018 NOKIA
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+syntax = "proto3";
+package org.onap.ves;
+
+message VesEvent {
+ 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
+}
+
+// VES CommonEventHeader adapted to GPB (Google Protocol Buffers)
+// Aligned with VES 7.0.1 schema, and extending to hvMeas Domain.
+
+message CommonEventHeader
+{
+ string version = 1; // required, "version of the gpb common event header"
+ 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
+
+ uint32 sequence = 3; // required, "ordering of events communicated by an event source instance or 0 if not needed"
+
+ enum Priority
+ {
+ PRIORITY_NOT_PROVIDED = 0;
+ HIGH = 1;
+ MEDIUM = 2;
+ NORMAL = 3;
+ LOW = 4;
+ }
+ Priority priority = 4; // required, "processing priority"
+
+ string eventId = 5; // required, "event key that is unique to the event source"
+ string eventName = 6; // required, "unique event name"
+ string eventType = 7; // "for example - guest05, platform"
+
+ uint64 lastEpochMicrosec = 8; // required, "the latest unix time aka epoch time associated with the event from any component--as microseconds elapsed since 1 Jan 1970 not including leap seconds"
+ uint64 startEpochMicrosec = 9; // required, "the earliest unix time aka epoch time associated with the event from any component--as microseconds elapsed since 1 Jan 1970 not including leap seconds"
+
+ string nfNamingCode = 10; // "4 character network function type, aligned with vnf naming standards"
+ string nfcNamingCode = 11; // "3 character network function component type, aligned with vfc naming standards"
+ string nfVendorName = 12; // " Vendor Name providing the nf "
+
+ bytes reportingEntityId = 13; // "UUID identifying the entity reporting the event, for example an OAM VM; must be populated by the ATT enrichment process"
+ string reportingEntityName = 14; // required, "name of the entity reporting the event, for example, an EMS name; may be the same as sourceName should match A&AI entry"
+ 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"
+
+ 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.rst b/docs/sections/apis/ves-hv.rst
index d2071077..2045b6ba 100644
--- a/docs/sections/apis/ves-hv.rst
+++ b/docs/sections/apis/ves-hv.rst
@@ -14,5 +14,41 @@ HV-VES (High Volume VES)
Overview
========
-TODO
+Component description can be found under `HV-VES Collector`_.
+
+.. _HV-VES Collector: ../services/ves-hv/index.html
+
+
+TCP Endpoint
+============
+
+HV-VES is exposed as NodePort service on Kubernetes cluster on port 30222/tcp.
+It uses plain TCP connections tunneled in SSL/TLS or can be run in insecure manner without data encryption on the socket.
+Without TLS client authentication/authorization is not possible.
+Connections are stream-based (as opposed to request-based) and long running.
+
+Payload is binary-encoded, currently using Google Protocol Buffers representation of the VES Common Header.
+
+.. literalinclude:: VesEvent.proto
+ :language: protobuf
+
+The PROTO file, which contains the VES CommonHeader, comes with a binary-type Payload parameter, where domain-specific
+data shall be placed. Domain-specific data are encoded as well with GPB, and they do require a domain-specific
+PROTO file to decode the data.
+
+HV-VES makes routing decisions based mostly on the content of the **Domain** parameter in VES Common Header.
+
+
+Healthcheck
+===========
+
+Inside HV-VES docker container runs small http service for healthcheck - exact port for this service can be configured
+at deployment using `--health-check-api-port` command line option.
+
+This service exposes single endpoint **GET /health/ready** which returns **HTTP 200 OK** in case HV-VES is healthy
+and ready for connections. Otherwise it returns **HTTP 503 Service Unavailable** with short reason of unhealthiness.
+
+
+
+