diff options
Diffstat (limited to 'datacollector/README.md')
| -rw-r--r-- | datacollector/README.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/datacollector/README.md b/datacollector/README.md new file mode 100644 index 0000000..ecd7878 --- /dev/null +++ b/datacollector/README.md @@ -0,0 +1,214 @@ +# DataCollector R-APP + +DataCollector R-APP is a Java SpringBoot application for consuming PM VES data from DMaaP and store it into DB. Also +DataCollector R-APP provides API to query aggregated metrics from PM VES data and User Equipment info. + +## Use of DataCollector R-APP + +### Configuration + +DataCollector R-APP needs several parameters to be defined before start. All parameters are passed through environment +variables + +To customize DB connection you need to create database schema. To do this use `init.sql` script under **src/main/docker/**. +Additionally, you can use `start.sh` after you build DataCollector R-APP (please see **Build DataCollector R-APP** chapter). Those actions will create database schema and run the application. +Also, you will need to set the following environment variables: + +- DATABASE_URL +- DATABASE_USERNAME +- DATABASE_PASSWORD + +To customize VES connectivity you need to set the following: + +- DMAAP_HOST +- DMAAP_POR +- DMAAP_MEASUREMENTS_TOPIC + +Example configuration in environment variables in application.yml: + +``` +server: + port: 8087 +dmaap: + prtocol: "http" + host: "localhost" + port: 8181 + measurements-topic: "measurements" +database: + host: mariadb-host + port: 3306 + name: "ves" + username: ves + driver-class-name: "org.mariadb.jdbc.Driver" +logging: + level: + org: + springframework: DEBUG + logging.file.name: logs/rapp-datacollector.log + pattern: + console: "%d %-5level %logger : %msg%n" + file: "%d %-5level [%thread] %logger : %msg%n" +spring: + autoconfigure: + exclude: + - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration + main: + allow-bean-definition-overriding: true + +``` + +After startup DataCollector R-APP is ready to read VES Events from DMaaP and stores them in database if they are flowing +into DMaaP. + +VES Event example + +```json +{ + "event": { + "commonEventHeader": { + "version": "4.0.1", + "vesEventListenerVersion": "7.0.1", + "sourceId": "de305d54-75b4-431b-adb2-eb6b9e546014", + "reportingEntityName": "ibcx0001vm002oam001", + "startEpochMicrosec": 1603293000000000, + "eventId": "measurement0000259", + "lastEpochMicrosec": 1603292917149000, + "priority": "Normal", + "sequence": 3, + "sourceName": "ibcx0001vm002ssc001", + "domain": "measurement", + "eventName": "Measurement_vIsbcMmc", + "reportingEntityId": "cc305d54-75b4-431b-adb2-eb6b9e541234", + "nfcNamingCode": "ssc", + "nfNamingCode": "ibcx" + }, + "measurementFields": { + "measurementInterval": 5, + "measurementFieldsVersion": "4.0", + "additionalMeasurements": [ + { + "name": "latency", + "hashMap": { + "value": "86" + } + }, + { + "name": "throughput", + "hashMap": { + "value": "25" + } + }, + { + "name": "identifier", + "hashMap": { + "value": "Cell1" + } + }, + { + "name": "trafficModel", + "hashMap": { + "mobile_samsung_s10_01": "10" + } + } + ] + } + } +} +``` + +Information about performance is situated in "additionalMeasurements" section, consisting of latency and throughput +parameters of performance, identifier of event producer and trafficModel with user equipment information. DataCollector +R-APP provides two endpoints to access data of stored VES Events: + +1. `{datacollectorhost}/v1/pm/ues` + +Returns list of user equipments from VES Events stored into database: + +```json +{ + "ues": [ + "mobile_samsung_s10_01" + ] +} +``` + +2. `{datacollectorhost}/v1/pm/events/aggregatedmetrics` + +To call the endpoint you have to define 3 query parameters: + +1.Slot - aggregation period (in seconds) for which an average performance metrics are calculated + +2.Count - number of aggregated performance metrics that should be returned by the method, one aggergated performance +metric per each slot. The first performance metrics is average metrics for (startTime, startTime +slot) + +3.startTime - ISO 8601 time format as string (e.g., 2020-10-26T06:52:54.01+00:00) for which aggregated performance +metrics are calculated with the pm ves data starting from startTime. "+" and "." signs must be properly encoded in url + +Example +URL: `{{datacollectorhost}}/v1/pm/events/aggregatedmetrics?slot=10&count=12&startTime=2021-03-31T15%3A00%3A00.0Z` +This request will return aggregated metrics from two minutes starting from 2021.03.31-15:30:00.0 + +Aggregated Metrics response example: + +```json +{ + "pm": [ + { + "cellId": "Cell1", + "performance": [ + { + "latency": 50, + "throughput": 80 + }, + { + "latency": 50, + "throughput": 80 + }, + { + "latency": 50, + "throughput": 80 + } + ] + } + ], + "itemsLength": 1 +} +``` + +# API + +The API is documented by the Swagger tool. + +## Swagger + +JSON file that can be imported to Swagger GUI can be found in *doc/swagger*. Those files are regenerated in each maven +build, so to generate this file please see **Build DataCollector R-APP** chapter. + +# Developer Guide + +## Build DataCollector R-APP + +Following mvn command (in the current directory) will build DataCollector R-APP: + +```bash +mvn clean install +``` + +## Run DataCollector R-APP + +Following command will run DataCollector R-APP: + +```bash +java -jar datacollector-0.0.1-SNAPSHOT.jar org.onap.rapp.DataCollectorApplication +``` + +## Logging + +The log file will be created in the /log path. Parameters of logging are in application.yml file. +After DataCollector R-APP starts successfully, log/rapp-datacollector.log should start to contain the logs: + +``` +. +└──log + └── rapp-datacollector.log +``` |