From: PatrikBuhr Date: Wed, 10 May 2023 12:07:22 +0000 (+0200) Subject: Documentation of RAN PM X-Git-Tag: 1.0.0~12 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=499fc3793b4af0fafa36b5ed0eded6e8f1ec4a39;p=nonrtric%2Fplt%2Franpm.git Documentation of RAN PM Added PM Data Converter skeleton. Signed-off-by: PatrikBuhr Issue-ID: NONRTRIC-868 Change-Id: Iaab65af511e7d9f8ecdff6b0514463ea7e901293 --- diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 4225bf6..ab5d752 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -37,6 +37,7 @@ build: - sphinx-build -W -b html --keep-going -n -d _readthedocs/tmp/doctrees/datafilecollector ./datafilecollector/docs/ _readthedocs/html/datafilecollector - sphinx-build -W -b html --keep-going -n -d _readthedocs/tmp/doctrees/influxlogger ./influxlogger/docs/ _readthedocs/html/influxlogger - sphinx-build -W -b html --keep-going -n -d _readthedocs/tmp/doctrees/pmproducer ./pmproducer/docs/ _readthedocs/html/pmproducer + - sphinx-build -W -b html --keep-going -n -d _readthedocs/tmp/doctrees/kafka-pm-producer ./kafka-pm-producer/docs/ _readthedocs/html/kafka-pm-producer python: install: @@ -44,6 +45,7 @@ python: - requirements: datafilecollector/docs/requirements-docs.txt - requirements: influxlogger/docs/requirements-docs.txt - requirements: pmproducer/docs/requirements-docs.txt + - requirements: kafka-pm-producer/docs/requirements-docs.txt sphinx: configuration: docs/conf.py diff --git a/datafilecollector/tox.ini b/datafilecollector/tox.ini index bdc407f..52803ed 100644 --- a/datafilecollector/tox.ini +++ b/datafilecollector/tox.ini @@ -16,7 +16,7 @@ # documentation only [tox] -minversion = 2.0 +minversion = 4.0 envlist = docs, docs-linkcheck, diff --git a/docs/overview.rst b/docs/overview.rst index aafcb22..2964761 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -67,7 +67,7 @@ The figure below gives an overview of the data flow through the components. 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. +7. A PM report in json format is stored (compressed with gzip). 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. @@ -99,7 +99,7 @@ PM Subscriber design time dependencies An rApp uses the ICS API, which is avaiable in `Non-RT RIC - Information Coordinator Service (Documentation site) `_. -The schema for the PM Mesaurement information jobs is defined in `Non-RT RIC - RAN PM - PM Producer (Documentation site) `. +The schema for the PM Mesaurement information jobs is defined in :doc:`Non-RT RIC - RAN PM - PM Producer (Documentation site) `. 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. diff --git a/influxlogger/tox.ini b/influxlogger/tox.ini index bdc407f..52803ed 100644 --- a/influxlogger/tox.ini +++ b/influxlogger/tox.ini @@ -16,7 +16,7 @@ # documentation only [tox] -minversion = 2.0 +minversion = 4.0 envlist = docs, docs-linkcheck, diff --git a/kafka-pm-producer/docs/Architecture.png b/kafka-pm-producer/docs/Architecture.png new file mode 100644 index 0000000..95e64f6 Binary files /dev/null and b/kafka-pm-producer/docs/Architecture.png differ diff --git a/kafka-pm-producer/docs/Pictures.pptx b/kafka-pm-producer/docs/Pictures.pptx new file mode 100644 index 0000000..439312c Binary files /dev/null and b/kafka-pm-producer/docs/Pictures.pptx differ diff --git a/kafka-pm-producer/docs/_static/logo.png b/kafka-pm-producer/docs/_static/logo.png new file mode 100644 index 0000000..c3b6ce5 Binary files /dev/null and b/kafka-pm-producer/docs/_static/logo.png differ diff --git a/kafka-pm-producer/docs/conf.py b/kafka-pm-producer/docs/conf.py new file mode 100644 index 0000000..bc39c07 --- /dev/null +++ b/kafka-pm-producer/docs/conf.py @@ -0,0 +1,36 @@ +# ============LICENSE_START=============================================== +# Copyright (C) 2021-2023 Nordix Foundation. All rights reserved. +# ======================================================================== +# 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================================================= +# + +from docs_conf.conf import * + +#branch configuration + +branch = 'latest' + +linkcheck_ignore = [ + 'http://localhost.*', + 'http://127.0.0.1.*', + 'https://gerrit.o-ran-sc.org.*', +] + +extensions = ['sphinx.ext.intersphinx',] + + +#intershpinx mapping with other projects +intersphinx_mapping = {} + +intersphinx_mapping['nonrtric'] = ('https://docs.o-ran-sc.org/projects/o-ran-sc-nonrtric/en/%s' % branch, None) diff --git a/kafka-pm-producer/docs/conf.yaml b/kafka-pm-producer/docs/conf.yaml new file mode 100644 index 0000000..9f420ed --- /dev/null +++ b/kafka-pm-producer/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: oran +project: nonrtric-plt-pmdataconverter diff --git a/kafka-pm-producer/docs/favicon.ico b/kafka-pm-producer/docs/favicon.ico new file mode 100644 index 0000000..00b0fd0 Binary files /dev/null and b/kafka-pm-producer/docs/favicon.ico differ diff --git a/kafka-pm-producer/docs/index.rst b/kafka-pm-producer/docs/index.rst new file mode 100644 index 0000000..ac5b863 --- /dev/null +++ b/kafka-pm-producer/docs/index.rst @@ -0,0 +1,13 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2023 Nordix + +Non-RT RIC PM Data Converter +============================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ./overview.rst + diff --git a/kafka-pm-producer/docs/overview.rst b/kafka-pm-producer/docs/overview.rst new file mode 100644 index 0000000..b2469ef --- /dev/null +++ b/kafka-pm-producer/docs/overview.rst @@ -0,0 +1,129 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2023 Nordix + + +PM Data Converter +~~~~~~~~~~~~~~~~~ + + +******** +Overview +******** + +The task of the PM Data Converter is to convert PM Measurement report files, +(XML formatted according to 3GPP TS 32.432 and 3GPP TS 32.435) into Json. + +The component receives objects from kafka that indicates that new PM Report files +are collected from the RAN. The event is sent by the Data File Collector. + +The XML file is read from the storage, converted to Json, gzipped and stored. + +A Json object indicating that a new Json PM Mesurement report is available is sent on +a Kafka topic to be picked up by other components for further processing, + +.. image:: ./Architecture.png + :width: 500pt + + + +This product is a part of :doc:`NONRTRIC `. + + + +********************* +Output PM Measurement +********************* + +The Json format of the PM mesaurememt follows the same structure as the input XML format (defined by 3GPP). + +Here follows an example: + +.. code-block:: javascript + + { + "event":{ + "commonEventHeader":{ + "domain":"perf3gpp", + "eventId":"9efa1210-f285-455f-9c6a-3a659b1f1882", + "eventName":"perf3gpp_gnb-Ericsson_pmMeasResult", + "sourceName":"O-DU-1122", + "reportingEntityName":"", + "startEpochMicrosec":951912000000, + "lastEpochMicrosec":951912900000, + "timeZoneOffset":"+00:00" + }, + "perf3gppFields":{ + "perf3gppFieldsVersion":"1.0", + "measDataCollection":{ + "granularityPeriod":900, + "measuredEntityUserName":"RNC Telecomville", + "measuredEntityDn":"SubNetwork=CountryNN,MeContext=MEC-Gbg-1,ManagedElement=RNC-Gbg-1", + "measuredEntitySoftwareVersion":"", + "measInfoList":[ + { + "measInfoId":{ + "sMeasInfoId":"PM=1,PmGroup=NRCellDU_GNBDU" + }, + "measTypes":{ + "sMeasTypesList":[ + "succImmediateAssignProcs" + ] + }, + "measValuesList":[ + { + "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-997", + "suspectFlag":"false", + "measResults":[ + { + "p":1, + "sValue":"1113" + } + ] + }, + { + "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-998", + "suspectFlag":"false", + "measResults":[ + { + "p":1, + "sValue":"234" + } + ] + }, + { + "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-999", + "suspectFlag":"true", + "measResults":[ + { + "p":1, + "sValue":"789" + } + ] + } + ] + } + ] + } + } + } + } + + +************************** +Output File Ready Message +************************** + +Here follows an example of the sent object indicating that a new Json file is available. +It only contains the name of the stored file. The name of the bucket and the minio endpoint +must be known by the event receiver. + +.. code-block:: javascript + + { + "filename": "xyz.json.gzip" + } + + + + diff --git a/kafka-pm-producer/docs/requirements-docs.txt b/kafka-pm-producer/docs/requirements-docs.txt new file mode 100644 index 0000000..f266a10 --- /dev/null +++ b/kafka-pm-producer/docs/requirements-docs.txt @@ -0,0 +1,12 @@ +tox +Sphinx +doc8 +docutils < 0.17 +setuptools +six +sphinx_rtd_theme +sphinxcontrib-needs +sphinxcontrib-swaggerdoc +sphinx_bootstrap_theme +sphinxcontrib-redoc +lfdocs-conf \ No newline at end of file diff --git a/kafka-pm-producer/tox.ini b/kafka-pm-producer/tox.ini new file mode 100644 index 0000000..52803ed --- /dev/null +++ b/kafka-pm-producer/tox.ini @@ -0,0 +1,37 @@ +# ================================================================================== +# Copyright (c) 2023 Nordix +# +# 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. +# ================================================================================== + +# documentation only +[tox] +minversion = 4.0 +envlist = + docs, + docs-linkcheck, +skipsdist = true + +[testenv:docs] +basepython = python3 +deps = -r{toxinidir}/docs/requirements-docs.txt + +commands = + sphinx-build -W -b html -n -d {envtmpdir}/docs/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +allowlist_externals = echo + +[testenv:docs-linkcheck] +basepython = python3 +deps = -r{toxinidir}/docs/requirements-docs.txt +commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck diff --git a/pmproducer/tox.ini b/pmproducer/tox.ini index bdc407f..52803ed 100644 --- a/pmproducer/tox.ini +++ b/pmproducer/tox.ini @@ -16,7 +16,7 @@ # documentation only [tox] -minversion = 2.0 +minversion = 4.0 envlist = docs, docs-linkcheck, diff --git a/tox.ini b/tox.ini index 82366e5..e014a22 100644 --- a/tox.ini +++ b/tox.ini @@ -15,7 +15,7 @@ # ================================================================================== [tox] -minversion = 2.0 +minversion = 4.0 envlist = docs, docs-linkcheck, @@ -24,22 +24,24 @@ skipsdist = true [testenv:docs] basepython = python3 -deps = - -r{toxinidir}/docs/requirements-docs.txt - -r{toxinidir}/datafilecollector/docs/requirements-docs.txt - -r{toxinidir}/influxlogger/docs/requirements-docs.txt - -r{toxinidir}/pmproducer/docs/requirements-docs.txt - +deps = + -r{toxinidir}/docs/requirements-docs.txt + -r{toxinidir}/datafilecollector/docs/requirements-docs.txt + -r{toxinidir}/influxlogger/docs/requirements-docs.txt + -r{toxinidir}/pmproducer/docs/requirements-docs.txt + -r{toxinidir}/kafka-pm-producer/docs/requirements-docs.txt + commands = sphinx-build -W -b html --keep-going -n -d {envtmpdir}/datafilecollector/doctrees ./datafilecollector/docs/ {toxinidir}/docs/_build/html/datafilecollector sphinx-build -W -b html --keep-going -n -d {envtmpdir}/influxlogger/doctrees ./influxlogger/docs/ {toxinidir}/docs/_build/html/influxlogger sphinx-build -W -b html --keep-going -n -d {envtmpdir}/pmproducer/doctrees ./pmproducer/docs/ {toxinidir}/docs/_build/html/pmproducer + sphinx-build -W -b html --keep-going -n -d {envtmpdir}/kafka-pm-producer/doctrees ./kafka-pm-producer/docs/ {toxinidir}/docs/_build/html/kafka-pm-producer sphinx-build -W -b html --keep-going -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html [testenv:docs-linkcheck] basepython = python3 deps = -r{toxinidir}/docs/requirements-docs.txt -commands = +commands = sphinx-build -W -b linkcheck -d {envtmpdir}/datafilecollector/doctrees ./datafilecollector/docs/ {toxinidir}/docs/_build/linkcheck/datafilecollector sphinx-build -W -b linkcheck -d {envtmpdir}/influxlogger/doctrees ./influxlogger/docs/ {toxinidir}/docs/_build/linkcheck/influxlogger sphinx-build -W -b linkcheck -d {envtmpdir}/pmproducer/doctrees ./pmproducer/docs/ {toxinidir}/docs/_build/linkcheck/pmproducer