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":"PM=1,PmGroup=NRCellDU_GNBDU"
  71                      },
  72                      "measTypes":{
  73                         "sMeasTypesList":[
  74                            "succImmediateAssignProcs"
  75                         ]
  76                      },
  77                      "measValuesList":[
  78                         {
  79                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-997",
  80                            "suspectFlag":"false",
  81                            "measResults":[
  82                               {
  83                                  "p":1,
  84                                  "sValue":"1113"
  85                               }
  86                            ]
  87                         },
  88                         {
  89                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-998",
  90                            "suspectFlag":"false",
  91                            "measResults":[
  92                               {
  93                                  "p":1,
  94                                  "sValue":"234"
  95                               }
  96                            ]
  97                         },
  98                         {
  99                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-999",
 100                            "suspectFlag":"true",
 101                            "measResults":[
 102                               {
 103                                  "p":1,
 104                                  "sValue":"789"
 105                               }
 106                            ]
 107                         }
 108                      ]
 109                   }
 110                ]
 111             }
 112          }
 113       }
 114    }
 115
 116 ==================
 117 Sent Kafka headers
 118 ==================
 119
 120 For each filtered result sent to a Kafka topic, there will the following proerties in the Kafa header:
 121
 122 * type-id, this propery is used to indicate the ID of the information type. The value is a string.
 123 * gzip, if this property exists the object is gzipped (otherwise not). The property has no value.
 124 * source-name, the name of the source traffical element for the measurements.
 125
 126
 127 ******************
 128 Configuration File
 129 ******************
 130
 131 The configuration file defines Kafka topics that should be listened to and registered as subscribeable information types.
 132 There is an example configuration file in config/application_configuration.json
 133
 134 Each entry will be registered as a subscribe information type in ICS. The following attributes can be used in each entry:
 135
 136 * id, the information type identifier.
 137
 138 * kafkaInputTopic, a Kafka topic to listen to for new file events.
 139
 140 * inputJobType, the information type for new file events subscription.
 141
 142 * inputJobDefinition, the parameters for the new file events subscription.
 143
 144 The last two parameters are used to create the subscription for the input to this component (subscription of file ready events).
 145
 146
 147 Below follows an example of a configuration file.
 148
 149 .. code-block:: javascript
 150
 151  {
 152    "types": [
 153       {
 154          "id": "PmDataOverKafka",
 155          "kafkaInputTopic": "FileReadyEvent",
 156          "inputJobType": "xml-file-data-to-filestore",
 157          "inputJobDefinition": {
 158             "kafkaOutputTopic": "FileReadyEvent",
 159             "filestore-output-bucket": "pm-files-json",
 160             "filterType": "pmdata",
 161             "filter": {
 162                "inputCompression": "xml.gz",
 163                "outputCompression": "none"
 164             }
 165          }
 166       }
 167    ]
 168  }
 169
 170 **************************
 171 Information Job Parameters
 172 **************************
 173
 174 The schema for the parameters for PM measurements subscription is defined in file src/main/resources/typeSchemaPmData.json.
 175
 176 =====================
 177 typeSchemaPmData.json
 178 =====================
 179
 180 The type specific json schema for the subscription of PM measurement:
 181
 182 .. code-block:: javascript
 183
 184    {
 185    "$schema": "http://json-schema.org/draft-04/schema#",
 186    "type": "object",
 187    "additionalProperties": false,
 188    "properties": {
 189       "filter": {
 190          "type": "object",
 191          "additionalProperties": false,
 192          "properties": {
 193             "sourceNames": {
 194                "type": "array",
 195                "items": [
 196                   {
 197                      "type": "string"
 198                   }
 199                ]
 200             },
 201             "measObjInstIds": {
 202                "type": "array",
 203                "items": [
 204                   {
 205                      "type": "string"
 206                   }
 207                ]
 208             },
 209             "measTypeSpecs": {
 210                "type": "array",
 211                "items": [
 212                   {
 213                      "type": "object",
 214                      "properties": {
 215                         "measuredObjClass": {
 216                            "type": "string"
 217                         },
 218                         "measTypes": {
 219                            "type": "array",
 220                            "items": [
 221                               {
 222                                  "type": "string"
 223                               }
 224                            ]
 225                         }
 226                      },
 227                      "required": [
 228                         "measuredObjClass"
 229                      ]
 230                   }
 231                ]
 232             },
 233             "measuredEntityDns": {
 234                "type": "array",
 235                "items": [
 236                   {
 237                      "type": "string"
 238                   }
 239                ]
 240             },
 241             "pmRopStartTime": {
 242                "type": "string"
 243             },
 244             "pmRopEndTime": {
 245                "type": "string"
 246             }
 247          }
 248       },
 249       "deliveryInfo": {
 250          "type": "object",
 251          "additionalProperties": false,
 252          "properties": {
 253             "topic": {
 254                "type": "string"
 255             },
 256             "bootStrapServers": {
 257                "type": "string"
 258             }
 259          },
 260          "required": [
 261             "topic"
 262          ]
 263       }
 264    },
 265    "required": [
 266       "filter", "deliveryInfo"
 267    ]
 268    }
 269
 270
 271 The following properties are defined:
 272
 273 * 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.
 274
 275    * sourceNames, section of the names of the reporting traffical nodes
 276    * measObjInstIds, selection of the measured resources. This is the Relative Distingusished Name of the MO that
 277      has the counter.
 278      If a given value is contained in the filter definition, it will match (partial matching).
 279      For instance a value like "NRCellCU" will match "ManagedElement=seliitdus00487,GNBCUCPFunction=1,NRCellCU=32".
 280    * measTypeSpecs, selection of measurement types (counters). This consists of:
 281
 282       * measuredObjClass, the name of the class of the measured resources.
 283       * measTypes, the name of the measurement type (counter). The measurement type name is only
 284         unique in the scope of an MO class (measured resource).
 285
 286    * measuredEntityDns, selection of DNs for the traffical elements.
 287
 288    * pmRopStartTime, if this parameter is specified already collected PM measurements files will be scanned to retrieve historical data.
 289      The start file is the time from when the information shall be returned.
 290      In this case, the query is only done for files from the given "sourceNames".
 291      If this parameter is excluded, only "new" reports will be delivered as they are collected from the traffical nodes.
 292
 293    * pmRopEndTime, for querying already collected PM measurements. Only relevant if pmRopStartTime.
 294      If this parameters is given, no reports will be sent as new files are collected.
 295
 296 * deliveryInfo, defines where the subscribed PM measurements shall be sent.
 297
 298   * topic, the name of the kafka topic
 299   * 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).
 300
 301
 302
 303 Below follows examples of some filters.
 304
 305 .. code-block:: javascript
 306
 307     {
 308       "filter":{
 309         "sourceNames":[
 310            "O-DU-1122"
 311         ],
 312         "measObjInstIds":[
 313            "UtranCell=Gbg-997"
 314         ],
 315         "measTypeSpecs":[
 316            {
 317               "measuredObjClass":"UtranCell",
 318               "measTypes":[
 319                  "succImmediateAssignProcs"
 320               ]
 321             {
 322         ]
 323       }
 324    }
 325
 326 Here follows an example of a filter that will
 327 match two counters from all cells in two traffical nodes.
 328
 329 .. code-block:: javascript
 330
 331     {
 332       "filterType":"pmdata",
 333       "filter": {
 334         "sourceNames":[
 335            "O-DU-1122", "O-DU-1123"
 336         ],
 337         "measTypeSpecs":[
 338              {
 339                 "measuredObjClass":"NRCellCU",
 340                 "measTypes":[
 341                    "pmCounterNumber0", "pmCounterNumber1"
 342                 ]
 343              }
 344           ],
 345
 346       }
 347     }
 348
 349
 350 ****************************
 351 PM measurements subscription
 352 ****************************
 353
 354 The sequence is that a "new file event" is received (from a Kafka topic).
 355 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
 356 and the result is sent to the Kafka topic specified by the Job (by the data consumer).
 357
 358 .. image:: ./dedicatedTopics.png
 359    :width: 500pt
 360
 361 If several jobs publish to the same Kafka topic (shared topic), the resulting filtered output will be an aggregate of all matching filters.
 362 So, each consumer will then get more data than requested.
 363
 364 .. image:: ./sharedTopics.png
 365    :width: 500pt
 366