UVAP Operation Guide

Introduction

This document gives a few useful topics for system integrators for operating UVAP.

Time synchronization using NTP

Many software components have algorithms that use the system clock. UVAP components regularly use the system time, and a divergent clock response can lead to interpreting incoming data as corrupted. The behavior under such circumstances is undefined.

For example, if UVAP requests the time and the system responds T and for the next request the system responds T - 3 seconds, a failure will occur, such as data loss or service error. Same applies if 3 seconds passes on the clock, while in real life only 10 milliseconds passes.

For this reason, it is important to have an accurate server clock that is monotonic and without jumps. It is strongly recommended not to use systemd-timesyncd, the default time synchronization on most systems. Use NTP or Chrony with proper configuration that fits the requirements above.

For information on enabling NTP time synchronization using the GUI or CLI, see Time Synchronization using NTP under UbuntuTime.

Starting UVAP services

Starting up UVAP in a production environment means to start the necessary Microservices for the given use case. A Microservice is an instance of an UVAP component. Multiple instances of the same component may be needed to be used. Separate services can be started in separate Docker containers. This requires knowledge about how to start an individual service, and since it is a bit of a larger topic, it deserves its own section in the documentation: Generic Operation Guide.

Licence expiration

UVAP MGR will not start with invalid or expired licence. If the licence expires during the running of the UVAP MGR then it will stop itself. If licence expiration is closer than 30 days then a warning will be issued in the logs in every 6 hours. Illustration of warning:

2020-02-11 22:02:33.850347 warning [multi-graph-runner-ms][0x00007fd0935fd700][A::f::lambda/82] Licence for "UVAP Multi Graph Runner" will expire soon. Valid until: 2020-02-14T22:02:58Z. 3 days left.

Monitoring of UVAP services

Health check via docker

For every UVAP microservice in the output of docker ps the STATUS field indicates the overall status of the service. For example:

$ docker ps
CONTAINER ID        IMAGE                                                COMMAND                  CREATED              STATUS                                 PORTS                                  NAMES
a4323ffc4d88        ultinous/uvap:mgr_uvap-2.680.1                       "/bin/bash -c 'exec …"   3 seconds ago       Up 1 second (health: starting)   0.0.0.0:64989-64991->64989-64991/tcp   uvap_mgr

Possible values: starting, healthy, unhealthy

Logs

Every UVAP microservice (MGR, tracker, ...) uses docker's standard logging mechanism, thus

docker logs container_name

will print the logs for the given application. If a microservice encounters problems then it will log with fatal, error or warning severity. Fatal is always followed by the shutdown of the service. Error may or may not lead to a complete shutdown, but usually results in not providing some of the features the service ought to have. Warning severity messages indicate smaller problems like wasting resources, not having enough data for providing a quality analysis or having settings that are deprecated and will be removed in the future and so on.

Functions of monitoring port

Monitoring port is set in the .properties file of the given microservice. You can query or set some properties using the configured port of the microservice, it accepts HTTP requests.

Function	Sample request	Sample response
Query log level	GET /loglevel	"warning"
Query health check	GET /healthCheck	{"value":{"problems":[],"started":true,"ok":true}}
Set log level	POST /loglevel and in the body debug
Shutdown	POST /shutdown	"Shutdown done."
Reload	POST /reload	"Reload done."

The value.problems field is an array of strings in the response of /healthCheck.

Example invocation from command line:

$ curl http://localhost:6497/healthCheck
{"value":{"problems":[],"started":true,"ok":true}}