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 Non-RT RIC 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 The data can be delivered in gzipped format or in cleartext (indicated by an element in the Kafka header).
  43
  44 The result of the PM filtering preserves the structure of a 3GPP PM report.
  45 Here follows an example of a resulting delivered PM report.
  46
  47 .. code-block:: javascript
  48
  49    {
  50       "event":{
  51          "commonEventHeader":{
  52             "domain":"perf3gpp",
  53             "eventId":"9efa1210-f285-455f-9c6a-3a659b1f1882",
  54             "eventName":"perf3gpp_gnb-Ericsson_pmMeasResult",
  55             "sourceName":"O-DU-1122",
  56             "reportingEntityName":"",
  57             "startEpochMicrosec":951912000000,
  58             "lastEpochMicrosec":951912900000,
  59             "timeZoneOffset":"+00:00"
  60          },
  61          "perf3gppFields":{
  62             "perf3gppFieldsVersion":"1.0",
  63             "measDataCollection":{
  64                "granularityPeriod":900,
  65                "measuredEntityUserName":"RNC Telecomville",
  66                "measuredEntityDn":"SubNetwork=CountryNN,MeContext=MEC-Gbg-1,ManagedElement=RNC-Gbg-1",
  67                "measuredEntitySoftwareVersion":"",
  68                "measInfoList":[
  69                   {
  70                      "measInfoId":{
  71                         "sMeasInfoId":"PM=1,PmGroup=NRCellDU_GNBDU"
  72                      },
  73                      "measTypes":{
  74                         "sMeasTypesList":[
  75                            "succImmediateAssignProcs"
  76                         ]
  77                      },
  78                      "measValuesList":[
  79                         {
  80                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-997",
  81                            "suspectFlag":"false",
  82                            "measResults":[
  83                               {
  84                                  "p":1,
  85                                  "sValue":"1113"
  86                               }
  87                            ]
  88                         },
  89                         {
  90                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-998",
  91                            "suspectFlag":"false",
  92                            "measResults":[
  93                               {
  94                                  "p":1,
  95                                  "sValue":"234"
  96                               }
  97                            ]
  98                         },
  99                         {
 100                            "measObjInstId":"RncFunction=RF-1,UtranCell=Gbg-999",
 101                            "suspectFlag":"true",
 102                            "measResults":[
 103                               {
 104                                  "p":1,
 105                                  "sValue":"789"
 106                               }
 107                            ]
 108                         }
 109                      ]
 110                   }
 111                ]
 112             }
 113          }
 114       }
 115    }
 116
 117 ==================
 118 Sent Kafka headers
 119 ==================
 120
 121 For each filtered result sent to a Kafka topic, there will the following properties in the Kafka header:
 122
 123 * type-id, this property is used to indicate the ID of the information type. The value is a string.
 124 * gzip, if this property exists the object is gzip'ed (otherwise not). The property has no value.
 125 * source-name, the name of the source RAN traffic-handling element from which the measurements originate.
 126
 127
 128 *************
 129 Configuration
 130 *************
 131
 132 The component is configured by a configuration file and by the normal spring boot configuration file (application.yaml).
 133
 134 ==================
 135 Configuration file
 136 ==================
 137
 138 The configuration file defines Kafka topics that should be listened to and registered as information types which can be subscribed to.
 139 There is an example configuration file in config/application_configuration.json
 140
 141 Each entry will be registered as a subscribe information type in ICS. The following attributes can be used in each entry:
 142
 143 * id, the information type identifier.
 144
 145 * kafkaInputTopic, a Kafka topic to listen to for new file events.
 146
 147 * inputJobType, the information type for new file events subscription.
 148
 149 * inputJobDefinition, the parameters for the new file events subscription.
 150
 151 The last two parameters are used to create the subscription for the input to this component (subscription of file ready events).
 152
 153
 154 Below follows an example of a configuration file.
 155
 156 .. code-block:: javascript
 157
 158  {
 159    "types": [
 160       {
 161          "id": "PmDataOverKafka",
 162          "kafkaInputTopic": "FileReadyEvent",
 163          "inputJobType": "xml-file-data-to-filestore",
 164          "inputJobDefinition": {
 165             "kafkaOutputTopic": "FileReadyEvent",
 166             "filestore-output-bucket": "pm-files-json",
 167             "filterType": "pmdata",
 168             "filter": {
 169                "inputCompression": "xml.gz",
 170                "outputCompression": "none"
 171             }
 172          }
 173       }
 174    ]
 175  }
 176
 177
 178
 179 ================
 180 application.yaml
 181 ================
 182 As any springboot application, this is component configured via an application.yaml file.
 183
 184 An example application.yaml configuration file: ":download:`link <../config/application.yaml>`"
 185
 186
 187 **************************
 188 Information Job Parameters
 189 **************************
 190
 191 The schema for the parameters for PM measurements subscription is defined in file src/main/resources/typeSchemaPmData.json.
 192
 193 =====================
 194 typeSchemaPmData.json
 195 =====================
 196
 197 The type specific json schema for the subscription of PM measurement:
 198
 199 .. code-block:: javascript
 200
 201    {
 202    "$schema": "http://json-schema.org/draft-04/schema#",
 203    "type": "object",
 204    "additionalProperties": false,
 205    "properties": {
 206       "filter": {
 207          "type": "object",
 208          "additionalProperties": false,
 209          "properties": {
 210             "sourceNames": {
 211                "type": "array",
 212                "items": [
 213                   {
 214                      "type": "string"
 215                   }
 216                ]
 217             },
 218             "measObjInstIds": {
 219                "type": "array",
 220                "items": [
 221                   {
 222                      "type": "string"
 223                   }
 224                ]
 225             },
 226             "measTypeSpecs": {
 227                "type": "array",
 228                "items": [
 229                   {
 230                      "type": "object",
 231                      "properties": {
 232                         "measuredObjClass": {
 233                            "type": "string"
 234                         },
 235                         "measTypes": {
 236                            "type": "array",
 237                            "items": [
 238                               {
 239                                  "type": "string"
 240                               }
 241                            ]
 242                         }
 243                      },
 244                      "required": [
 245                         "measuredObjClass"
 246                      ]
 247                   }
 248                ]
 249             },
 250             "measuredEntityDns": {
 251                "type": "array",
 252                "items": [
 253                   {
 254                      "type": "string"
 255                   }
 256                ]
 257             },
 258             "pmRopStartTime": {
 259                "type": "string"
 260             },
 261             "pmRopEndTime": {
 262                "type": "string"
 263             }
 264          }
 265       },
 266       "deliveryInfo": {
 267          "type": "object",
 268          "additionalProperties": false,
 269          "properties": {
 270             "topic": {
 271                "type": "string"
 272             },
 273             "bootStrapServers": {
 274                "type": "string"
 275             }
 276          },
 277          "required": [
 278             "topic"
 279          ]
 280       }
 281    },
 282    "required": [
 283       "filter", "deliveryInfo"
 284    ]
 285    }
 286
 287
 288 The following properties are defined:
 289
 290 * 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.
 291
 292    * sourceNames, section of the names of the reporting RAN traffic-handling nodes
 293    * measObjInstIds, selection of the measured resources. This is the Relative Distinguished Name (RDN) of the MO that
 294      has the counter.
 295      If a given value is contained in the filter definition, it will match (partial matching).
 296      For instance a value like "NRCellCU" will match "ManagedElement=seliitdus00487,GNBCUCPFunction=1,NRCellCU=32".
 297    * measTypeSpecs, selection of measurement types (counters). This consists of:
 298
 299       * measuredObjClass, the name of the class of the measured resources.
 300       * measTypes, the name of the measurement type (counter). The measurement type name is only
 301         unique in the scope of an MO class (measured resource).
 302
 303    * measuredEntityDns, selection of DNs for the RAN traffic-handling elements.
 304
 305    * pmRopStartTime, if this parameter is specified already collected PM measurements files will be scanned to retrieve historical data.
 306      This is the time from when the information shall be returned.
 307      In this case, the query is only done for files from the given "sourceNames".
 308      If this parameter is excluded, only "new" reports will be delivered as they are collected from the RAN traffic-handling nodes.
 309      How old information that can be retrieved depends on the retention time for the storage (if minio it used, it is a S3 bucket).
 310      A best effort is done, so that the stored files that are in time range are scanned even if the
 311      specified time is too long back in time.
 312
 313    * pmRopEndTime, for querying already collected PM measurements. Only relevant if pmRopStartTime.
 314      If this parameters is given, no reports will be sent as new files are collected.
 315
 316 * deliveryInfo, defines where the subscribed PM measurements shall be sent.
 317
 318   * topic, the name of the kafka topic
 319   * 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).
 320
 321
 322
 323 Below follows examples of some filters.
 324
 325 .. code-block:: javascript
 326
 327     {
 328       "filter":{
 329         "sourceNames":[
 330            "O-DU-1122"
 331         ],
 332         "measObjInstIds":[
 333            "UtranCell=Gbg-997"
 334         ],
 335         "measTypeSpecs":[
 336            {
 337               "measuredObjClass":"UtranCell",
 338               "measTypes":[
 339                  "succImmediateAssignProcs"
 340               ]
 341             {
 342         ]
 343       }
 344    }
 345
 346 Here follows an example of a filter that will
 347 match two counters from all cells in two RAN traffic-handling nodes.
 348
 349 .. code-block:: javascript
 350
 351     {
 352       "filterType":"pmdata",
 353       "filter": {
 354         "sourceNames":[
 355            "O-DU-1122", "O-DU-1123"
 356         ],
 357         "measTypeSpecs":[
 358              {
 359                 "measuredObjClass":"NRCellCU",
 360                 "measTypes":[
 361                    "pmCounterNumber0", "pmCounterNumber1"
 362                 ]
 363              }
 364           ],
 365
 366       }
 367     }
 368
 369
 370 ****************************
 371 PM measurements subscription
 372 ****************************
 373
 374 The sequence is that a "new file event" is received (from a Kafka topic).
 375 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
 376 and the result is sent to the Kafka topic specified by the Job (by the data consumer).
 377
 378 .. image:: ./dedicatedTopics.png
 379    :width: 500pt
 380
 381 =========================================
 382 Several Jobs sharing the same Kafka topic
 383 =========================================
 384
 385 If several jobs publish to the same Kafka topic (shared topic), the resulting filtered output will be an aggregate of all matching filters.
 386 So, each consumer will then get more data than requested.
 387
 388 .. image:: ./sharedTopics.png
 389    :width: 500pt
 390