pmproducer/docs/overview.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. Copyright (C) 2023 Nordix
   4
   5
   6 PM Producer
   7 ~~~~~~~~~~~~~
   8
   9 ************
  10 Introduction
  11 ************
  12
  13 The task of the PM Producer is to process PM reports and to distribute requested information to subscribers.
  14 The main use case is:
  15
  16 * The PM Producer receives a Json object from Kafka which notifies that a new PM report is fetched and is available to processed.
  17
  18 * The actual PM report is in a file, which is stored in an S3 Object store bucket or in the file system (in a mounted volume). The file has the same structure as 3GPP TS 32.432/3GPP TS 32.435, but is converted to json and is extended to contain the information that is encoded the 3GPP measurement report xml file name.
  19
  20 * The PM Producer loads the file and distribute the contents to the subscribers over Kafka according to their subscription parameters. These subscription parameters defines wanted measurement types from given parts of of the network.
  21
  22 The PM Producer registers itself as an information producer of PM measurement data in Information Coordination Service (ICS).
  23
  24 A data consumer can create an information job (data subscription) using the ICS consumer API (for rApps) or the A1-EI (Enrichment Information) API (for NearRT-RICs).
  25 The PM Producer will get notified when information jobs of type 'PM measurements' are created.
  26
  27 The service is implemented in Java Spring Boot.
  28
  29 .. image:: ./Architecture.png
  30    :width: 500pt
  31
  32 This product is a part of :doc:`NONRTRIC <nonrtric:index>`.
  33
  34 **************
  35 Delivered data
  36 **************
  37 When a data consumer (e.g an rApp) creates an Information Job, a Kafka Topic is given as output for the job.
  38 After filtering, the data will be delivered to the output topic.
  39
  40 The format of the delivered PM measurement is the same as the input format (which in turn is a Json mapping done from
  41 3GPP TS 32.432/3GPP TS 32.435).
  42
  43 The result of the PM filtering preserves the structure of a 3GPP PM report.
  44 Here follows an example of a resulting delivered PM report.
  45
  46 .. code-block:: javascript
  47
  48    {
  49       "event":{
  50          "commonEventHeader":{
  51             "domain":"perf3gpp",
  52             "eventId":"9efa1210-f285-455f-9c6a-3a659b1f1882",
  53             "eventName":"perf3gpp_gnb-Ericsson_pmMeasResult",
  54             "sourceName":"O-DU-1122",
  55             "reportingEntityName":"",
  56             "startEpochMicrosec":951912000000,
  57             "lastEpochMicrosec":951912900000,
  58             "timeZoneOffset":"+00:00"
  59          },
  60          "perf3gppFields":{
  61             "perf3gppFieldsVersion":"1.0",
  62             "measDataCollection":{
  63                "granularityPeriod":900,
  64                "measuredEntityUserName":"RNC Telecomville",
  65                "measuredEntityDn":"SubNetwork=CountryNN,MeContext=MEC-Gbg-1,ManagedElement=RNC-Gbg-1",
  66                "measuredEntitySoftwareVersion":"",
  67                "measInfoList":[
  68                   {
  69                      "measInfoId":{
  70                         "sMeasInfoId":""
  71                      },
  72                      "measTypes":{
  73                         "map":{
  74                            "succImmediateAssignProcs":1
  75                         },
  76                         "sMeasTypesList":[
  77                            "succImmediateAssignProcs"
  78                         ]
  79                      },
  80                      "measValuesList":[
  81                         {
  82                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-997",
  83                            "suspectFlag":"false",
  84                            "measResults":[
  85                               {
  86                                  "p":1,
  87                                  "sValue":"1113"
  88                               }
  89                            ]
  90                         },
  91                         {
  92                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-998",
  93                            "suspectFlag":"false",
  94                            "measResults":[
  95                               {
  96                                  "p":1,
  97                                  "sValue":"234"
  98                               }
  99                            ]
 100                         },
 101                         {
 102                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-999",
 103                            "suspectFlag":"true",
 104                            "measResults":[
 105                               {
 106                                  "p":1,
 107                                  "sValue":"789"
 108                               }
 109                            ]
 110                         }
 111                      ]
 112                   }
 113                ]
 114             }
 115          }
 116       }
 117    }
 118
 119 ==================
 120 Sent Kafka headers
 121 ==================
 122
 123 For each filtered result sent to a Kafka topic, there will the following proerties in the Kafa header:
 124
 125 * type-id, this propery is used to indicate the ID of the information type. The value is a string.
 126 * gzip, if this property exists the object is gzipped (otherwise not). The property has no value.
 127 * source-name, the name of the source traffical element for the measurements.
 128
 129
 130 ******************
 131 Configuration File
 132 ******************
 133
 134 The configuration file defines Kafka topics that should be listened to and registered as subscribeable information types.
 135 There is an example configuration file in config/application_configuration.json
 136
 137 Each entry will be registered as a subscribe information type in ICS. The following attributes can be used in each entry:
 138
 139 * id, the information type identifier.
 140
 141 * kafkaInputTopic, a Kafka topic to listen to for new file events.
 142
 143 * inputJobType, the information type for new file events subscription.
 144
 145 * inputJobDefinition, the parameters for the new file events subscription.
 146
 147 The last two parameters are used to create the subscription for the input to this component (subscription of file ready events).
 148
 149
 150 Below follows an example of a configuration file.
 151
 152 .. code-block:: javascript
 153
 154  {
 155    "types": [
 156       {
 157          "id": "PmDataOverKafka",
 158          "kafkaInputTopic": "FileReadyEvent",
 159          "inputJobType": "xml-file-data-to-filestore",
 160          "inputJobDefinition": {
 161             "kafkaOutputTopic": "FileReadyEvent",
 162             "filestore-output-bucket": "pm-files-json",
 163             "filterType": "pmdata",
 164             "filter": {
 165                "inputCompression": "xml.gz",
 166                "outputCompression": "none"
 167             }
 168          }
 169       }
 170    ]
 171  }
 172
 173 **************************
 174 Information Job Parameters
 175 **************************
 176
 177 The schema for the parameters for PM measurements subscription is defined in file src/main/resources/typeSchemaPmData.json.
 178
 179 =====================
 180 typeSchemaPmData.json
 181 =====================
 182
 183 The type specific json schema for the subscription of PM measurement:
 184
 185 .. code-block:: javascript
 186
 187    {
 188    "$schema": "http://json-schema.org/draft-04/schema#",
 189    "type": "object",
 190    "additionalProperties": false,
 191    "properties": {
 192       "filter": {
 193          "type": "object",
 194          "additionalProperties": false,
 195          "properties": {
 196             "sourceNames": {
 197                "type": "array",
 198                "items": [
 199                   {
 200                      "type": "string"
 201                   }
 202                ]
 203             },
 204             "measObjInstIds": {
 205                "type": "array",
 206                "items": [
 207                   {
 208                      "type": "string"
 209                   }
 210                ]
 211             },
 212             "measTypeSpecs": {
 213                "type": "array",
 214                "items": [
 215                   {
 216                      "type": "object",
 217                      "properties": {
 218                         "measuredObjClass": {
 219                            "type": "string"
 220                         },
 221                         "measTypes": {
 222                            "type": "array",
 223                            "items": [
 224                               {
 225                                  "type": "string"
 226                               }
 227                            ]
 228                         }
 229                      },
 230                      "required": [
 231                         "measuredObjClass"
 232                      ]
 233                   }
 234                ]
 235             },
 236             "measuredEntityDns": {
 237                "type": "array",
 238                "items": [
 239                   {
 240                      "type": "string"
 241                   }
 242                ]
 243             },
 244             "pmRopStartTime": {
 245                "type": "string"
 246             },
 247             "pmRopEndTime": {
 248                "type": "string"
 249             }
 250          }
 251       },
 252       "deliveryInfo": {
 253          "type": "object",
 254          "additionalProperties": false,
 255          "properties": {
 256             "topic": {
 257                "type": "string"
 258             },
 259             "bootStrapServers": {
 260                "type": "string"
 261             }
 262          },
 263          "required": [
 264             "topic"
 265          ]
 266       }
 267    },
 268    "required": [
 269       "filter", "deliveryInfo"
 270    ]
 271    }
 272
 273
 274 The following properties are defined:
 275
 276 * filter, the value of the filter expression. This selects which data to subscribe for. All fields are optional and excluding a field means that everything is selected.
 277
 278    * sourceNames, section of the names of the reporting traffical nodes
 279    * measObjInstIds, selection of the measured resources. This is the Relative Distingusished Name of the MO that
 280      has the counter.
 281      If a given value is contained in the filter definition, it will match (partial matching).
 282      For instance a value like "NRCellCU" will match "ManagedElement=seliitdus00487,GNBCUCPFunction=1,NRCellCU=32".
 283    * measTypeSpecs, selection of measurement types (counters). This consists of:
 284
 285       * measuredObjClass, the name of the class of the measured resources.
 286       * measTypes, the name of the measurement type (counter). The measurement type name is only
 287         unique in the scope of an MO class (measured resource).
 288
 289    * measuredEntityDns, selection of DNs for the traffical elements.
 290
 291    * pmRopStartTime, if this parameter is specified already collected PM measurements files will be scanned to retrieve historical data.
 292      The start file is the time from when the information shall be returned.
 293      In this case, the query is only done for files from the given "sourceNames".
 294      If this parameter is excluded, only "new" reports will be delivered as they are collected from the traffical nodes.
 295
 296    * pmRopEndTime, for querying already collected PM measurements. Only relevant if pmRopStartTime.
 297      If this parameters is given, no reports will be sent as new files are collected.
 298
 299 * deliveryInfo, defines where the subscribed PM measurements shall be sent.
 300
 301   * topic, the name of the kafka topic
 302   * bootStrapServers, reference to the kafka bus to used. This is optional, if this is omitted the default configured kafka bus is used (which is configured in the application.yaml file).
 303
 304
 305
 306 Below follows examples of some filters.
 307
 308 .. code-block:: javascript
 309
 310     {
 311       "filter":{
 312         "sourceNames":[
 313            "O-DU-1122"
 314         ],
 315         "measObjInstIds":[
 316            "UtranCell=Gbg-997"
 317         ],
 318         "measTypeSpecs":[
 319            {
 320               "measuredObjClass":"UtranCell",
 321               "measTypes":[
 322                  "succImmediateAssignProcs"
 323               ]
 324             {
 325         ]
 326       }
 327    }
 328
 329 Here follows an example of a filter that will
 330 match two counters from all cells in two traffical nodes.
 331
 332 .. code-block:: javascript
 333
 334     {
 335       "filterType":"pmdata",
 336       "filter": {
 337         "sourceNames":[
 338            "O-DU-1122", "O-DU-1123"
 339         ],
 340         "measTypeSpecs":[
 341              {
 342                 "measuredObjClass":"NRCellCU",
 343                 "measTypes":[
 344                    "pmCounterNumber0", "pmCounterNumber1"
 345                 ]
 346              }
 347           ],
 348
 349       }
 350     }
 351
 352
 353 ****************************
 354 PM measurements subscription
 355 ****************************
 356
 357 The sequence is that a "new file event" is received (from a Kafka topic).
 358 The file is read from local storage (file storage or S3 object store). For each Job, the specified PM filter is applied to the data
 359 and the result is sent to the Kafka topic specified by the Job (by the data consumer).
 360
 361 .. image:: ./dedicatedTopics.png
 362    :width: 500pt
 363
 364 If several jobs publish to the same Kafka topic (shared topic), the resulting filtered output will be an aggregate of all matching filters.
 365 So, each consumer will then get more data than requested.
 366
 367 .. image:: ./sharedTopics.png
 368    :width: 500pt
 369