README.md

   1 RIC VESPA manager
   2 =================
   3
   4 The VESPA manager uses the VES Agent [https://github.com/nokia/ONAP-VESPA](https://github.com/nokia/ONAP-VESPA)
   5 to adapt near-RT RIC internal statistics' collection using Prometheus
   6 (xApps and platform containers) to ONAP's VES (VNF event streaming).
   7
   8 The vesmgr container runs two processes: the VESPA manager and the VES
   9 Agent (i.s. VESPA).
  10
  11 The VESPA manager starts and configures the VES Agent.
  12
  13 The VES Agent is a service acting as a bridge between Prometheus and
  14 ONAP's VES Collector.
  15
  16 # Application metrics definition
  17
  18 The application metrics are defined in the application descriptor.
  19 For each counter, the following fields are required in the "metrics"
  20 section of the descriptor:
  21
  22 * name - Prometheus name of the counter
  23 * objectName - object name in VES
  24 * objectInstance - object instance in VE
  25
  26 The VESPA manager receives the application metrics configuration from the
  27 application manager. It subscribes the app notification messages from the
  28 application manager, and after having received one, requests the latest
  29 application configuration, creates the VES Agent configuration based on it,
  30 and restarts the VES Agent.
  31
  32 The VES Agent does not report any other metrics to VES.
  33
  34 # Prometheus configuration
  35
  36 The VES Agent reads the ricComponentName from Prometheus label
  37 "kubernetes_name".
  38
  39 # VES Collector event format
  40
  41 The VES Agent transmits events to the VES Collector in the
  42 VES Common Event Format v5.4.1.
  43 The Common Event Format is expressed in JSON schema v28.4.1.
  44
  45 VES Event Listener 5.4.1:
  46 <https://docs.onap.org/en/casablanca/submodules/vnfsdk/model.git/docs/files/VESEventListener.html>
  47
  48 JSON schema v28.4.1:
  49 <https://github.com/nokia/ONAP-VESPA/blob/8e9d9e93bb00bed0f5402c9de9502385d5e80acc/doc/CommonEventFormat_28.4.1.json>
  50
  51 # Environment variables
  52
  53 The VESPA manager container requires the following environment variables:
  54
  55 * VESMGR_VNFNAME - VNF name as a string. Default: Vespa.
  56 * VESMGR_NFNAMINGCODE - NF naming code as a string. Default: ricp.
  57 * VESMGR_HB_INTERVAL - VES heartbeat interval as a string. For example: 30s.
  58 * VESMGR_MEAS_INTERVAL - Measurement interval as a string. For example: 60s.
  59 * VESMGR_PROMETHEUS_ADDR - Prometheus address. For example: http://127.0.0.1:123
  60 * VESMGR_ALERTMANAGER_BIND_ADDR - Bind address to receive alerts from Prometheus AlertManager
  61
  62 * VESMGR_PRICOLLECTOR_ADDR - Primary collector FQDN as a string. For example: ricaux-entry.
  63 * VESMGR_PRICOLLECTOR_PORT - Primary collector port id as an integer. Default: 8443.
  64 * VESMGR_PRICOLLECTOR_SERVERROOT - Path before the /eventListener part of the POST URL as a string.
  65 * VESMGR_PRICOLLECTOR_TOPIC - Primary collector topic as a string.
  66 * VESMGR_PRICOLLECTOR_SECURE - Use HTTPS for VES collector. Possible string values: true or false.
  67 * VESMGR_PRICOLLECTOR_USER - User name as a string.
  68 * VESMGR_PRICOLLECTOR_PASSWORD - Password as a string.
  69 * VESMGR_PRICOLLECTOR_PASSPHASE - Passphrase as a string.
  70
  71 * VESMGR_APPMGRDOMAIN - Application manager domain. This is for testing purposes, only. Default: service-ricplt-appmgr-http.ricplt.svc.cluster.local.
  72
  73 # Liveness probe
  74
  75 The VESPA manager replies to liveness HTTP GET at path /supervision.
  76
  77 # Errors
  78
  79 The VESPA manager exits in the following error cases:
  80
  81 * The VES Agent exits
  82 * An unrecoverable system error during the initialization, for example
  83   * Creation of the VES Agent configuration file fails
  84   * Creation of a HTTP request message fails
  85
  86 # Unit Tests
  87
  88 In order to run the VESPA manager unit tests, give the following command:
  89
  90 ```shell
  91 go test ./... -v
  92 ```
  93
  94 # License
  95
  96 See [LICENSES.txt](./LICENSES.txt) file.