docs/user-guide/tsdr-user-guide.rst

   1 .. _tsdr-user-guide:
   2
   3 TSDR User Guide
   4 ===============
   5
   6 This document describes how to use HSQLDB, HBase, and Cassandra data
   7 stores to capture time series data using Time Series Data Repository
   8 (TSDR) features in OpenDaylight.  This document contains configuration,
   9 administration, management, usage, and troubleshooting sections for these
  10 features.
  11
  12 Overview
  13 --------
  14
  15 The Time Series Data Repository (TSDR) project in OpenDaylight (ODL)
  16 creates a framework for collecting, storing, querying, and maintaining
  17 time series data.  TSDR provides the framework for plugging in
  18 data collectors to collect various time series data and store the data
  19 into TSDR Data Stores. With a common data model and generic TSDR data
  20 persistence APIs, the user can choose various data stores to be plugged
  21 into the TSDR persistence framework. Currently, three types of data
  22 stores are supported: HSQLDB relational database (default installed),
  23 HBase NoSQL database and Cassandra NoSQL database.
  24
  25 With the capabilities of data collection, storage, query, aggregation,
  26 and purging provided by TSDR, network administrators can leverage
  27 various data driven applications built on top of TSDR for security risk
  28 detection, performance analysis, operational configuration optimization,
  29 traffic engineering and network analytics with automated intelligence.
  30
  31 TSDR Architecture
  32 -----------------
  33
  34 TSDR has the following major components:
  35
  36 -  Data Collection Service
  37
  38 -  Data Storage Service
  39
  40 -  TSDR Persistence Layer with data stores as plugins
  41
  42 -  TSDR Data Stores
  43
  44 -  Data Query Service
  45
  46 -  Grafana integration for time series data visualization
  47
  48 -  Data Aggregation Service
  49
  50 -  Data Purging Service
  51
  52 The Data Collection Service handles the collection of time series data
  53 into TSDR and hands it over to the Data Storage Service. The Data
  54 Storage Service stores the data into TSDR through the TSDR Persistence
  55 Layer. The TSDR Persistence Layer provides generic Service APIs allowing
  56 various data stores to be plugged in. The Data Aggregation Service
  57 aggregates time series fine-grained raw data into course-grained roll-up
  58 data to control the size of the data. The Data Purging Service
  59 periodically purges both fine-grained raw data and course-grained
  60 aggregated data according to user-defined schedules.
  61
  62 TSDR provides component-based services on a common data model. These
  63 services include the data collection service, data storage service and
  64 data query service.  The TSDR data storage service supports HSQLDB
  65 (the default datastore), HBASE and Cassandra datastores.  Between these
  66 services and components, time series data is communicated using a common
  67 TSDR data model.  This data model is designed around the abstraction of
  68 time series data commonalities. With these services, TSDR is able
  69 to collect the data from the data sources and store them into one of
  70 the TSDR data stores; HSQLDB, HBase and Cassandra datastores.  Data can
  71 be retrieved with the Data Query service using the default OpenDaylight
  72 RestConf interface or its ODL API interface.  TSDR also has integrated
  73 support for ElasticSearch capabilities.  TSDR data can also be viewed
  74 directly with Grafana for time series visualization or various chart formats.
  75
  76 Configuring TSDR Data Stores
  77 ----------------------------
  78
  79 To Configure HSQLDB Data Store
  80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  81
  82 The HSQLDB based storage files get stored automatically in <karaf
  83 install folder>/tsdr/ directory. If you want to change the default
  84 storage location, the configuration file to change can be found in
  85 <karaf install folder>/etc directory. The filename is
  86 org.ops4j.datasource-metric.cfg. Change the last portion of the
  87 url=jdbc:hsqldb:./tsdr/metric to point to different directory.
  88
  89 To Configure HBase Data Store
  90 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  91
  92 After installing HBase Server on the same machine as OpenDaylight, if
  93 the user accepts the default configuration of the HBase Data Store, the
  94 user can directly proceed with the installation of HBase Data Store from
  95 Karaf console.
  96
  97 Optionally, the user can configure TSDR HBase Data Store following HBase
  98 Data Store Configuration Procedure.
  99
 100 -  HBase Data Store Configuration Steps
 101
 102    -  Open the file etc/tsdr-persistence-hbase.peroperties under karaf
 103       distribution directory.
 104
 105    -  Edit the following parameters:
 106
 107       -  HBase server name
 108
 109       -  HBase server port
 110
 111       -  HBase client connection pool size
 112
 113       -  HBase client write buffer size
 114
 115 After the configuration of HBase Data Store is complete, proceed with
 116 the installation of HBase Data Store from Karaf console.
 117
 118 -  HBase Data Store Installation Steps
 119
 120    -  Start Karaf Console
 121
 122    -  Run the following commands from Karaf Console: feature:install
 123       odl-tsdr-hbase
 124
 125 To Configure Cassandra Data Store
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 127
 128 Currently, there’s no configuration needed for Cassandra Data Store. The
 129 user can use Cassandra data store directly after installing the feature
 130 from Karaf console.
 131
 132 Additionally separate commands have been implemented to install various
 133 data collectors.
 134
 135 Administering or Managing TSDR Data Stores
 136 ------------------------------------------
 137
 138 To Administer HSQLDB Data Store
 139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 140
 141 Once the TSDR default datastore feature (odl-tsdr-hsqldb-all) is
 142 enabled, the TSDR captured OpenFlow statistics metrics can be accessed
 143 from Karaf Console by executing the command
 144
 145 ::
 146
 147     tsdr:list <metric-category> <starttimestamp> <endtimestamp>
 148
 149 wherein
 150
 151 -  <metric-category> = any one of the following categories
 152    FlowGroupStats, FlowMeterStats, FlowStats, FlowTableStats, PortStats,
 153    QueueStats
 154
 155 -  <starttimestamp> = to filter the list of metrics starting this
 156    timestamp
 157
 158 -  <endtimestamp> = to filter the list of metrics ending this timestamp
 159
 160 -  <starttimestamp> and <endtimestamp> are optional.
 161
 162 -  Maximum 1000 records will be displayed.
 163
 164 To Administer HBase Data Store
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166
 167 -  Using Karaf Command to retrieve data from HBase Data Store
 168
 169 The user first need to install hbase data store from karaf console:
 170
 171 feature:install odl-tsdr-hbase
 172
 173 The user can retrieve the data from HBase data store using the following
 174 commands from Karaf console:
 175
 176 ::
 177
 178     tsdr:list
 179     tsdr:list <CategoryName> <StartTime> <EndTime>
 180
 181 Typing tab will get the context prompt of the arguments when typeing the
 182 command in Karaf console.
 183
 184 To Administer Cassandra Data Store
 185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186
 187 The user first needs to install Cassandra data store from Karaf console:
 188
 189 ::
 190
 191     feature:install odl-tsdr-cassandra
 192
 193 Then the user can retrieve the data from Cassandra data store using the
 194 following commands from Karaf console:
 195
 196 ::
 197
 198     tsdr:list
 199     tsdr:list <CategoryName> <StartTime> <EndTime>
 200
 201 Typing tab will get the context prompt of the arguments when typeing the
 202 command in Karaf console.
 203
 204 Installing TSDR Data Collectors
 205 -------------------------------
 206
 207 When the user uses HSQLDB data store and installed "odl-tsdr-hsqldb-all"
 208 feature from Karaf console, besides the HSQLDB data store, OpenFlow data
 209 collector is also installed with this command. However, if the user
 210 needs to use other collectors, such as NetFlow Collector, Syslog
 211 Collector, SNMP Collector, and Controller Metrics Collector, the user
 212 needs to install them with separate commands. If the user uses HBase or
 213 Cassandra data store, no collectors will be installed when the data
 214 store is installed. Instead, the user needs to install each collector
 215 separately using feature install command from Karaf console.
 216
 217 The following is the list of supported TSDR data collectors with the
 218 associated feature install commands:
 219
 220 -  OpenFlow Data Collector
 221
 222    ::
 223
 224        feature:install odl-tsdr-openflow-statistics-collector
 225
 226 -  NetFlow Data Collector
 227
 228    ::
 229
 230        feature:install odl-tsdr-netflow-statistics-collector
 231
 232 -  sFlow Data Collector
 233
 234    ::
 235
 236        feature:install odl-tsdr-sflow-statistics-colletor
 237
 238 -  SNMP Data Collector
 239
 240    ::
 241
 242        feature:install odl-tsdr-snmp-data-collector
 243
 244 -  Syslog Data Collector
 245
 246    ::
 247
 248        feature:install odl-tsdr-syslog-collector
 249
 250 -  Controller Metrics Collector
 251
 252    ::
 253
 254        feature:install odl-tsdr-controller-metrics-collector
 255
 256 -  Web Activity Collector
 257
 258    ::
 259
 260        feature:install odl-tsdr-restconf-collector
 261
 262
 263 In order to use controller metrics collector, the user needs to install
 264 Sigar library.
 265
 266 The following is the instructions for installing Sigar library on
 267 Ubuntu:
 268
 269 -  Install back end library by "sudo apt-get install
 270    libhyperic-sigar-java"
 271
 272 -  Execute "export
 273    LD\_LIBRARY\_PATH=/usr/lib/jni/:/usr/lib:/usr/local/lib" to set the
 274    path of the JNI (you can add this to the ".bashrc" in your home
 275    directory)
 276
 277 -  Download the file "sigar-1.6.4.jar". It might be also in your ".m2"
 278    directory under "~/.m2/resources/org/fusesource/sigar/1.6.4"
 279
 280 -  Create the directory "org/fusesource/sigar/1.6.4" under the "system"
 281    directory in your controller home directory and place the
 282    "sigar-1.6.4.jar" there
 283
 284 Configuring TSDR Data Collectors
 285 --------------------------------
 286
 287 -  SNMP Data Collector Device Credential Configuration
 288
 289 After installing SNMP Data Collector, a configuration file under etc/
 290 directory of ODL distribution is generated: etc/tsdr.snmp.cfg is
 291 created.
 292
 293 The following is a sample tsdr.snmp.cfg file:
 294
 295 credentials=[192.168.0.2,public],[192.168.0.3,public]
 296
 297 The above credentials indicate that TSDR SNMP Collector is going to
 298 connect to two devices. The IPAddress and Read community string of these
 299 two devices are (192.168.0.2, public), and (192.168.0.3) respectively.
 300
 301 The user can make changes to this configuration file any time during
 302 runtime. The configuration will be picked up by TSDR in the next cycle
 303 of data collection.
 304
 305 Polling interval configuration for SNMP Collector and OpenFlow Stats Collector
 306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 307
 308 The default polling interval of SNMP Collector and OpenFlow Stats
 309 Collector is 30 seconds and 15 seconds respectively. The user can change
 310 the polling interval through restconf APIs at any time. The new polling
 311 interval will be picked up by TSDR in the next collection cycle.
 312
 313 -  Retrieve Polling Interval API for SNMP Collector
 314
 315    -  URL:
 316       http://localhost:8181/restconf/config/tsdr-snmp-data-collector:TSDRSnmpDataCollectorConfig
 317
 318    -  Verb: GET
 319
 320 -  Update Polling Interval API for SNMP Collector
 321
 322    -  URL:
 323       http://localhost:8181/restconf/operations/tsdr-snmp-data-collector:setPollingInterval
 324
 325    -  Verb: POST
 326
 327    -  Content Type: application/json
 328
 329    -  Input Payload:
 330
 331       ::
 332
 333           {
 334              "input": {
 335                  "interval": "15000"
 336              }
 337           }
 338
 339 -  Retrieve Polling Interval API for OpenFlowStats Collector
 340
 341    -  URL:
 342       http://localhost:8181/restconf/config/tsdr-openflow-statistics-collector:TSDROSCConfig
 343
 344    -  Verb: GET
 345
 346 -  Update Polling Interval API for OpenFlowStats Collector
 347
 348    -  URL:
 349       http://localhost:8181/restconf/operations/tsdr-openflow-statistics-collector:setPollingInterval
 350
 351    -  Verb: POST
 352
 353    -  Content Type: application/json
 354
 355    -  Input Payload:
 356
 357       ::
 358
 359           {
 360              "input": {
 361                  "interval": "15000"
 362              }
 363           }
 364
 365 Querying TSDR from REST APIs
 366 ----------------------------
 367
 368 TSDR provides two REST APIs for querying data stored in TSDR data
 369 stores.
 370
 371 -  Query of TSDR Metrics
 372
 373    -  URL: http://localhost:8181/tsdr/metrics/query
 374
 375    -  Verb: GET
 376
 377    -  Parameters:
 378
 379       -  tsdrkey=[NID=][DC=][MN=][RK=]
 380
 381          ::
 382
 383              The TSDRKey format indicates the NodeID(NID), DataCategory(DC), MetricName(MN), and RecordKey(RK) of the monitored objects.
 384              For example, the following is a valid tsdrkey:
 385              [NID=openflow:1][DC=FLOWSTATS][MN=PacketCount][RK=Node:openflow:1,Table:0,Flow:3]
 386              The following is also a valid tsdrkey:
 387              tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]
 388              In the case when the sections in the tsdrkey is empty, the query will return all the records in the TSDR data store that matches the filled tsdrkey. In the above example, the query will return all the data in FLOWSTATS data category.
 389              The query will return only the first 1000 records that match the query criteria.
 390
 391       -  from=<time\_in\_seconds>
 392
 393       -  until=<time\_in\_seconds>
 394
 395 The following is an example curl command for querying metric data from
 396 TSDR data store:
 397
 398 curl -G -v -H "Accept: application/json" -H "Content-Type:
 399 application/json" "http://localhost:8181/tsdr/metrics/query"
 400 --data-urlencode "tsdrkey=[NID=][DC=FLOWSTATS][MN=][RK=]"
 401 --data-urlencode "from=0" --data-urlencode "until=240000000000"\|more
 402
 403 -  Query of TSDR Log type of data
 404
 405    -  URL:http://localhost:8181/tsdr/logs/query
 406
 407    -  Verb: GET
 408
 409    -  Parameters:
 410
 411       -  tsdrkey=tsdrkey=[NID=][DC=][RK=]
 412
 413          ::
 414
 415              The TSDRKey format indicates the NodeID(NID), DataCategory(DC), and RecordKey(RK) of the monitored objects.
 416              For example, the following is a valid tsdrkey:
 417              [NID=openflow:1][DC=NETFLOW][RK]
 418              The query will return only the first 1000 records that match the query criteria.
 419
 420       -  from=<time\_in\_seconds>
 421
 422       -  until=<time\_in\_seconds>
 423
 424 The following is an example curl command for querying log type of data
 425 from TSDR data store:
 426
 427 curl -G -v -H "Accept: application/json" -H "Content-Type:
 428 application/json" "http://localhost:8181/tsdr/logs/query"
 429 --data-urlencode "tsdrkey=[NID=][DC=NETFLOW][RK=]" --data-urlencode
 430 "from=0" --data-urlencode "until=240000000000"\|more
 431
 432 Grafana integration with TSDR
 433 -----------------------------
 434
 435 TSDR provides northbound integration with Grafana time series data
 436 visualization tool. All the metric type of data stored in TSDR data
 437 store can be visualized using Grafana.
 438
 439 For the detailed instruction about how to install and configure Grafana
 440 to work with TSDR, please refer to the following link:
 441
 442 https://wiki.opendaylight.org/view/Grafana_Integration_with_TSDR_Step-by-Step
 443
 444 Purging Service configuration
 445 -----------------------------
 446
 447 After the data stores are installed from Karaf console, the purging
 448 service will be installed as well. A configuration file called
 449 tsdr.data.purge.cfg will be generated under etc/ directory of ODL
 450 distribution.
 451
 452 The following is the sample default content of the tsdr.data.purge.cfg
 453 file:
 454
 455 host=127.0.0.1 data\_purge\_enabled=true data\_purge\_time=23:59:59
 456 data\_purge\_interval\_in\_minutes=1440 retention\_time\_in\_hours=168
 457
 458 The host indicates the IPAddress of the data store. In the case when the
 459 data store is together with ODL controller, 127.0.0.1 should be the
 460 right value for the host IP. The other attributes are self-explained.
 461 The user can change those attributes at any time. The configuration
 462 change will be picked up right away by TSDR Purging service at runtime.
 463
 464 How to use TSDR to collect, store, and view OpenFlow Interface Statistics
 465 -------------------------------------------------------------------------
 466
 467 Overview
 468 ~~~~~~~~
 469
 470 This tutorial describes an example of using TSDR to collect, store, and
 471 view one type of time series data in OpenDaylight environment.
 472
 473 Prerequisites
 474 ~~~~~~~~~~~~~
 475
 476 You would need to have the following as prerequisits:
 477
 478 -  One or multiple OpenFlow enabled switches. Alternatively, you can use
 479    mininet to simulate such a switch.
 480
 481 -  Successfully installed OpenDaylight Controller.
 482
 483 -  Successfully installed HBase Data Store following TSDR HBase Data
 484    Store Installation Guide.
 485
 486 -  Connect the OpenFlow enabled switch(es) to OpenDaylight Controller.
 487
 488 Target Environment
 489 ~~~~~~~~~~~~~~~~~~
 490
 491 HBase data store is only supported in Linux operation system.
 492
 493 Instructions
 494 ~~~~~~~~~~~~
 495
 496 -  Start OpenDaylight.
 497
 498 -  Connect OpenFlow enabled switch(es) to the controller.
 499
 500    -  If using mininet, run the following commands from mininet command
 501       line:
 502
 503       -  mn --topo single,3 --controller
 504          *remote,ip=172.17.252.210,port=6653* --switch
 505          ovsk,protocols=OpenFlow13
 506
 507 -  Install TSDR hbase feature from Karaf:
 508
 509    -  feature:install odl-tsdr-hbase
 510
 511 -  Install OpenFlow Statistics Collector from Karaf:
 512
 513    -  feature:install odl-tsdr-openflow-statistics-collector
 514
 515 -  run the following command from Karaf console:
 516
 517    -  tsdr:list PORTSTATS
 518
 519 You should be able to see the interface statistics of the switch(es)
 520 from the HBase Data Store. If there are too many rows, you can use
 521 "tsdr:list InterfaceStats\|more" to view it page by page.
 522
 523 By tabbing after "tsdr:list", you will see all the supported data
 524 categories. For example, "tsdr:list FlowStats" will output the Flow
 525 statistics data collected from the switch(es).
 526
 527
 528 .. include:: tsdr-elastic-search.rst
 529
 530
 531 Troubleshooting
 532 ---------------
 533
 534 Karaf logs
 535 ~~~~~~~~~~
 536
 537 All TSDR features and components write logging information including
 538 information messages, warnings, errors and debug messages into
 539 karaf.log.
 540
 541 HBase and Cassandra logs
 542 ~~~~~~~~~~~~~~~~~~~~~~~~
 543
 544 For HBase and Cassandra data stores, the database level logs are written
 545 into HBase log and Cassandra logs.
 546
 547 -  HBase log
 548
 549    -  HBase log is under <HBase-installation-directory>/logs/.
 550
 551 -  Cassandra log
 552
 553    -  Cassandra log is under {cassandra.logdir}/system.log. The default
 554       {cassandra.logdir} is /var/log/cassandra/.
 555
 556 Security
 557 --------
 558
 559 TSDR gets the data from a variety of sources, which can be secured in
 560 different ways.
 561
 562 -  OpenFlow Security
 563
 564    -  The OpenFlow data can be configured with Transport Layer Security
 565       (TLS) since the OpenFlow Plugin that TSDR depends on provides this
 566       security support.
 567
 568 -  SNMP Security
 569
 570    -  The SNMP version3 has security support. However, since ODL SNMP
 571       Plugin that TSDR depends on does not support version 3, we (TSDR)
 572       will not have security support at this moment.
 573
 574 -  NetFlow Security
 575
 576    -  NetFlow, which cannot be configured with security so we recommend
 577       making sure it flows only over a secured management network.
 578
 579 -  Syslog Security
 580
 581    -  Syslog, which cannot be configured with security so we recommend
 582       making sure it flows only over a secured management network.
 583
 584 Support multiple data stores simultaneously at runtime
 585 ------------------------------------------------------
 586
 587 TSDR supports running multiple data stores simultaneously at runtim. For
 588 example, it is possible to configure TSDR to push log type of data into
 589 Cassandra data store, while pushing metrics type of data into HBase.
 590
 591 When you install one TSDR data store from karaf console, such as using
 592 feature:install odl-tsdr-hsqldb, a properties file will be generated
 593 under <Karaf-distribution-directory>/etc/. For example, when you install
 594 hsqldb, a file called tsdr-persistence-hsqldb.properties is generated
 595 under that directory.
 596
 597 By default, all the types of data are supported in the data store. For
 598 example, the default content of tsdr-persistence-hsqldb.properties is as
 599 follows:
 600
 601 ::
 602
 603     metric-persistency=true
 604     log-persistency=true
 605     binary-persistency=true
 606
 607 When the user would like to use different data stores to support
 608 different types of data, he/she could enable or disable a particular
 609 type of data persistence in the data stores by configuring the
 610 properties file accordingly.
 611
 612 For example, if the user would like to store the log type of data in
 613 HBase, and store the metric and binary type of data in Cassandra, he/she
 614 needs to install both hbase and cassandra data stores from Karaf
 615 console. Then the user needs to modify the properties file under
 616 <Karaf-distribution-directory>/etc as follows:
 617
 618 -  tsdr-persistence-hbase.properties
 619
 620    ::
 621
 622        metric-persistency=false
 623        log-persistency=true
 624        binary-persistency=true
 625
 626 -  tsdr-persistence-cassandra.properties
 627
 628    ::
 629
 630        metric-psersistency=true
 631        log-persistency=false
 632        binary-persistency=false