Documentation of RAN PM

First take.

Signed-off-by: PatrikBuhr <patrik.buhr@est.tech>
Issue-ID: NONRTRIC-868
Change-Id: I9b13726a4428e99b428dd4a26923c6ecaa659afc

diff --git a/datafilecollector/docs/overview.rst b/datafilecollector/docs/overview.rst
index 74e8e9b..ef28bd4 100644 (file)
--- a/datafilecollector/docs/overview.rst
+++ b/datafilecollector/docs/overview.rst
@@ -11,12 +11,16 @@ Introduction
 ************
 
 The task of the Data File Collector is to collect OAM data files from RAN traffic-handling nodes.
-The main use case is:
+The main use case is (see also the picture below)):
 
-* The DFC receives a "File Ready" VES event from a Kafka topic. This contains a list of all available files.
-* The DFC fetches files that are not already fetched from the relevant RAN traffic-handling nodes. This is done using one of the supported file transfer protocols.
-* Each file is stored in an S3 Object Store bucket or in the file system (in a persistent volume).
-* For each stored file, a "File Publish" message is sent to a Kafka topic for further processing.
+* (1) The DFC receives a "File Ready" VES event from a Kafka topic. This contains a list of all available files.
+* (2) The DFC fetches files that are not already fetched from the relevant RAN traffic-handling nodes. This is done using one of the supported file transfer protocols.
+* (3) Each file is stored in an S3 Object Store bucket or in the file system (in a persistent volume).
+* (4) For each stored file, a "File Publish" message is sent to a Kafka topic for further processing.
+* (5) The "File Publish" message can be subscribed by other components, which can then read the fetched file and process it further.
+
+.. image:: ./Architecture.png
+   :width: 1000pt
 
 Supported file transfer protocols are:
 
@@ -25,12 +29,8 @@ Supported file transfer protocols are:
 * HTTP
 * HTTPS
 
-
 The service is implemented in Java Spring Boot.
 
-.. image:: ./Architecture.png
-   :width: 1000pt
-
 This product is a part of :doc:`NONRTRIC <nonrtric:index>`.
 
 **************************

diff --git a/docs/Components.png b/docs/Components.png
new file mode 100644 (file)
index 0000000..01c6053
Binary files /dev/null and b/docs/Components.png differ

diff --git a/docs/ControlFlow.png b/docs/ControlFlow.png
new file mode 100644 (file)
index 0000000..f0802bf
Binary files /dev/null and b/docs/ControlFlow.png differ

diff --git a/docs/DataFlow.png b/docs/DataFlow.png
new file mode 100644 (file)
index 0000000..d317e7e
Binary files /dev/null and b/docs/DataFlow.png differ

diff --git a/docs/DesignTimeDependencies.png b/docs/DesignTimeDependencies.png
new file mode 100644 (file)
index 0000000..08e3fe7
Binary files /dev/null and b/docs/DesignTimeDependencies.png differ

diff --git a/docs/Pictures.pptx b/docs/Pictures.pptx
new file mode 100644 (file)
index 0000000..bba2e94
Binary files /dev/null and b/docs/Pictures.pptx differ

diff --git a/docs/overview.rst b/docs/overview.rst
index 97b1434..aafcb22 100644 (file)
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -2,18 +2,109 @@
 .. SPDX-License-Identifier: CC-BY-4.0
 .. Copyright (C) 2023 Nordix
 
-Non-RT RIC RAN PM Use-case/Functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Non-RT RIC RAN PM Measurement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Parent repo Non-RT RIC RAN PM Use-case/Functions
+Parent repository for components implementing Non-RT RIC RAN PM Use-case.
 
-**************
-Implementation
-**************
 
-Implemented as multiple functions in sub directories:
+********
+Overview
+********
 
+The OSC Non-RT RIC provides a high performing, fully scalable end-to-end solution for handling
+PM Mesurements. A PM report (containing aggregated PM measurements over a time interval) is
+an XML file. The format is defined by 3GPP (TS 32.432 and 3GPP TS 32.435).
+The files are collected from the RAN and stored. An rApp can subscribe for chosen measurement types from
+measured resources in the network.
+
+
+**********
+Components
+**********
+
+The picture illustrates the components involved.
+
+* The PM Data File Collector fetches the XML files from the RAN.
+* The PM Data Converter converts these to a Json format. The structure and the contents
+  is the same as the XML format.
+* The PM Producer handles filtering and distribution of PM data to subscribers. These subscribers can be rApps.
+* The Influx Logger stores selected PM mesurements into a time series database.
+* HTTPS-SERVER is for testing and implements functionality to simulate file transfer from thye RAN nodes.
+
+The third party products used are:
+
+* Minio object storage, for storing of files.
+* Kafka for transferring of data (not the full PM reports, though)
+* Influx time series database for storing of selected PM mesurements over time.
+
+.. image:: ./Components.png
+   :width: 500pt
+
+For more detailed documentation of the components:
+
+* :doc:`Non-RT RIC - RAN PM - PM Data File Collector (Documentation site) <datafilecollector:index>`.
+* PM Data Converter TBD
 * :doc:`Non-RT RIC - RAN PM - PM Producer (Documentation site) <pmproducer:index>`.
 * :doc:`Non-RT RIC - RAN PM - Influx Logger (Documentation site) <influxlogger:index>`.
-* :doc:`Non-RT RIC - RAN PM - PM Data File Collector (Documentation site) <datafilecollector:index>`.
+* `Non-RT RIC - Information Coordinator Service (Documentation site) <https://docs.o-ran-sc.org/projects/o-ran-sc-nonrtric-plt-informationcoordinatorservice/en/latest/>`_.
+* HTTPS-SERVER TBD
+
+
+
+*********
+Data Flow
+*********
+
+The figure below gives an overview of the data flow through the components.
+
+.. image:: ./DataFlow.png
+   :width: 900pt
+
+1. The RAN node sends a VES event with available PM measurement report files.
+2. The VES event is put on a Kafka topic and picked up by the Data File Collector.
+3. A PM report file is fetched from the RAN node by a file transfer protocol. Which protocol to use is defined in the VES event.
+4. The collected file is stored
+5. A File collected object is put on a Kafka topic and is picked up by the PM Data Converter.
+6. The file data is read from the file store.
+7. A PM report in json format is stored.
+8. A message (a Json object) indicating that a new PM report (in Json format) is available is put on a Kafka topic and is picked up by the PM Data Producer.
+9. The PM data producer reads the Json file
+10. The subscribed PM data is sent to the PM data consumers (over Kafka). An rApp may be a PM data consumer.
+11. The Influx Logger, which is a PM data consumer, stores PM data in an Influx database.
+
+At anytime an rApp can read logged PM data from the Influx database.
+
+********************
+PM Data Subscription
+********************
+PM measurement data is subscribed by creating an Information Job using the Information Coordination Service (ICS).
+This a subscription broker and is part of what is called Data Managament an Exposure (DME) in O-RAN.
+The ICS makes sure that all data producers gets its data subscriptions (jobs).
+
+In the picture below, an rApp and the Influx Logger are consumers of PM data.
+
+.. image:: ./ControlFlow.png
+   :width: 500pt
+
+The PM Data Influx logger will create a PM data subscription based on a configuration file. An rApp can create
+PM data subscpition. The PM Data producer will deliver received PM measurements according to the subscriptions.
+
+The PM Data file collector will fetch all PM measurement files. The PM Data Converted will convert all fetched xml files
+to json. So these does not use any subscriptions.
+
+**************************************
+PM Subscriber design time dependencies
+**************************************
+
+An rApp uses the ICS API, which is avaiable in `Non-RT RIC - Information Coordinator Service (Documentation site) <https://docs.o-ran-sc.org/projects/o-ran-sc-nonrtric-plt-informationcoordinatorservice/en/latest/>`_.
+
+The schema for the PM Mesaurement information jobs is defined in `Non-RT RIC - RAN PM - PM Producer (Documentation site) <pmproducer:index>`.
+This schema defines parameters used in the subscription (info job) and defines which measurements to subscribe for and on which
+kafka topic the information shall be delivered to.
+
+An application retrieving logged PM data from the Influx database needs to know how the data is stored. That is
+defined in :doc:`Non-RT RIC - RAN PM - Influx Logger (Documentation site) <influxlogger:index>`.
 
+.. image:: ./DesignTimeDependencies.png
+   :width: 500pt
\ No newline at end of file