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

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