Heartbeat Microservice User Documentation

User Documentation for heartbeat Microservice
Issue-ID: DCAEGEN2-280

Change-Id: I158680b11b5d5de4a0d58f4d2f03816e2b1941fc
Signed-off-by: PrakashH <pbhandar@techmahindra.com>

1 files changed, 166 insertions, 0 deletions

diff --git a/docs/sections/services/heartbeat-ms/design.rst b/docs/sections/services/heartbeat-ms/design.rst
new file mode 100644
index 00000000..fa4490f4
--- /dev/null
+++ b/docs/sections/services/heartbeat-ms/design.rst
@@ -0,0 +1,166 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.

+.. http://creativecommons.org/licenses/by/4.0

+

+.. _design:

+

+Design

+======

+

+There are 4 processes created as below

+

+Main process

+------------

+ 

+This is the initial process which does the following.

+

+- Download CBS configuration and update the vnf_table_1

+- Spawns HB worker process, DB Monitoring process and CBS polling

+  process (if required)

+- Periodically update the hb_common table

+

+HB worker process

+-----------------

+

+This process is created by main process and does the following.

+

+- It waits on the HB Json event message from DMaaP message router

+- It receives the HB Json message and retrieves sourceName,

+  lastEpochTime, eventName in the incoming message

+- It checks for the received eventName against the eventName in

+  vnf_table_1. If eventName is not matched, then it discards the

+  message.

+- It checks for the received sourceName in the vnf_table_2. If the

+  sourceName is already there in vnf_table_2, then it updates the

+  received HB Json message in vnf_table_2 against that sourceName. If

+  the sourceName is not there in vnf_table_2, then it adds an entry in

+  vnf_table_2 for that eventName and increments the sourceName count in

+  vnf_table_1

+

+DB Monitoring process

+---------------------

+

+This process is created by main process and does the following.

+

+- The DB monitoring process scans through each entry of vnf_table_1 and

+  looks at the corresponding vnf_table_2 and checks the condition for

+  Control Loop event is met or not

+- If it finds that the multiple consecutive HB are missed, it raises

+  the Control Loop event.

+- It also clears the control loop event by looking at recently received

+  HB message.

+- Because of reconfiguration procedure, some of the existing entries in

+  vnf_table_1 may become invalid. DB Monitoring process would clean the

+  DB by looking at validity flag maintained in each vnf_table_1 table

+  entry. If not valid, it removes the entry in vnf_table_1 and also

+  removes the corresponding entries of vnf_table_2.

+

+CBS polling process

+-------------------

+

+If the local configuration file (config/hbproperties.yaml) indicates

+that CBS polling is required, then main process would create the CBS 

+polling process. It does the following.

+

+- It takes the CBS polling interval from the configuration file.

+

+- For every CBS polling interval, it sets the hb_common with state as

+  reconfiguration to indicate the main process to download CBS

+  configuration

+

+CBS configuration download support

+----------------------------------

+

+Apart from the above, a function/method is provided to Docker container

+that would download the CBS configuration whenever the configuration

+changes. This method/function would read hb_common state and change the

+state to reconfiguration.

+

+Heartbeat Microserice Multi instance support

+--------------------------------------------

+

+In order to work smoothly in an environment having multiple HB micro

+services instances, processes would work differently as mentioned below.

+

+**Main Process:**

+

+    Active Instance:

+     - Download CBS configuration and process it

+     - Spawns processes

+     - Periodically update hb_common with last accessed time to indicate that active instance is Alive.

+	 

+    Inactive Instance:

+        - Spawns processes

+        - Constantly check hb_common entry for last accessed time

+        - If the last accessed time is more than a minute or so, then it assumes the role of active instance 

+    

+**HB worker process:** Both active and inactive instance behaves the sames as metnioned in the Design section.

+

+**DB Monitoring process:** Both active periodically checks its process ID/hostname with hb_common data to know whether it is an active instance or not. If inactive instance it does nothing. If active instance, it behaves as mentioned in design section.

+

+**CBS Polling process:** Periodically checks its process ID/hostname with hb_common data to know whether it is an active instance or not. If inactive instance it does nothing. If active instance, it behaves as mentioned in design section.

+

+Handling of some of the failure scenarios

+-----------------------------------------

+

+Failure to download the configuration from CBS – In this case, local

+configuration file etc/config.json is considered as the configuration

+file and vnf_table_1 is updated accordingly.

+

+The Reconfiguration procedure is as below

+-----------------------------------------

+

+- If the state is Reconfiguration, then HB worker process, DB

+  monitoring process and CBS polling process would wait for

+  reconfiguration to complete.

+- Set each entry as invalid by using validity flag in vnf_table_1

+- Download the json file from CBS.

+- Set the validity flag to indicate to valid when an entry is updated.

+

+Postgres Database

+-----------------

+

+There are 3 tables maintained.

+

+**Vnf_table_1 table:** 

+This is table is indexed by eventName. Each entry

+has following parameters in it.

+

+- eventName

+- Configured heartbeat Missed Count

+- Configured Heartbeat Interval

+- Number of SourceName having same eventName

+- Validity flag that indicates VNF entry is valid or not

+- It also has following parameter related to Control loop event

+   - policyVersion

+   - policyName

+   - policyScope

+   - target_type

+   - target

+   - closedLoopControlName

+   - version

+

+**Vnf_table_2 table:** 

+For each sourceName there would be an entry in vnf_table_2. 

+This is indexed by eventName and SourceName. Each entry has

+below parameters

+

+- SourceName

+- Last received heartbeat epoch time

+- Control loop event raised flag. 0 indicates not raised, 1 indicates

+  CL event raised

+

+**hb_common table:** 

+This is a single entry table.

+

+- The configuration status which would have one of the below.

+   - **RECONFIGURATION** – indicates CBS configuration processing is in

+      progress.

+   - **RUNNING** – CBS configuration is completed and ready to process HB

+      event and send CL event.

+- The process ID – This indicates the main process ID of the active HB

+  instance which is responsible to take care of reconfiguration

+- The source Name – It has 2 parts, hostname and service name. The

+  hostname is the Docker container ID. The service name is the

+  environment variable set for SERVICE_NAME

+- The last accessed time – The time last accessed by the main process

+  having the above process ID.