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
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.
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.
34 TSDR has the following major components:
36 - Data Collection Service
38 - Data Storage Service
40 - TSDR Persistence Layer with data stores as plugins
46 - Grafana integration for time series data visualization
48 - Data Aggregation Service
50 - Data Purging Service
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.
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.
76 Configuring TSDR Data Stores
77 ----------------------------
79 To Configure HSQLDB Data Store
80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
89 To Configure HBase Data Store
90 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
97 Optionally, the user can configure TSDR HBase Data Store following HBase
98 Data Store Configuration Procedure.
100 - HBase Data Store Configuration Steps
102 - Open the file etc/tsdr-persistence-hbase.peroperties under karaf
103 distribution directory.
105 - Edit the following parameters:
111 - HBase client connection pool size
113 - HBase client write buffer size
115 After the configuration of HBase Data Store is complete, proceed with
116 the installation of HBase Data Store from Karaf console.
118 - HBase Data Store Installation Steps
120 - Start Karaf Console
122 - Run the following commands from Karaf Console: feature:install
125 To Configure Cassandra Data Store
126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128 Currently, there’s no configuration needed for Cassandra Data Store. The
129 user can use Cassandra data store directly after installing the feature
132 Additionally separate commands have been implemented to install various
135 Administering or Managing TSDR Data Stores
136 ------------------------------------------
138 To Administer HSQLDB Data Store
139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
147 tsdr:list <metric-category> <starttimestamp> <endtimestamp>
151 - <metric-category> = any one of the following categories
152 FlowGroupStats, FlowMeterStats, FlowStats, FlowTableStats, PortStats,
155 - <starttimestamp> = to filter the list of metrics starting this
158 - <endtimestamp> = to filter the list of metrics ending this timestamp
160 - <starttimestamp> and <endtimestamp> are optional.
162 - Maximum 1000 records will be displayed.
164 To Administer HBase Data Store
165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167 - Using Karaf Command to retrieve data from HBase Data Store
169 The user first need to install hbase data store from karaf console:
171 feature:install odl-tsdr-hbase
173 The user can retrieve the data from HBase data store using the following
174 commands from Karaf console:
179 tsdr:list <CategoryName> <StartTime> <EndTime>
181 Typing tab will get the context prompt of the arguments when typeing the
182 command in Karaf console.
184 To Administer Cassandra Data Store
185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187 The user first needs to install Cassandra data store from Karaf console:
191 feature:install odl-tsdr-cassandra
193 Then the user can retrieve the data from Cassandra data store using the
194 following commands from Karaf console:
199 tsdr:list <CategoryName> <StartTime> <EndTime>
201 Typing tab will get the context prompt of the arguments when typeing the
202 command in Karaf console.
204 Installing TSDR Data Collectors
205 -------------------------------
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.
217 The following is the list of supported TSDR data collectors with the
218 associated feature install commands:
220 - OpenFlow Data Collector
224 feature:install odl-tsdr-openflow-statistics-collector
226 - NetFlow Data Collector
230 feature:install odl-tsdr-netflow-statistics-collector
232 - sFlow Data Collector
236 feature:install odl-tsdr-sflow-statistics-colletor
238 - SNMP Data Collector
242 feature:install odl-tsdr-snmp-data-collector
244 - Syslog Data Collector
248 feature:install odl-tsdr-syslog-collector
250 - Controller Metrics Collector
254 feature:install odl-tsdr-controller-metrics-collector
256 - Web Activity Collector
260 feature:install odl-tsdr-restconf-collector
263 In order to use controller metrics collector, the user needs to install
266 The following is the instructions for installing Sigar library on
269 - Install back end library by "sudo apt-get install
270 libhyperic-sigar-java"
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
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"
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
284 Configuring TSDR Data Collectors
285 --------------------------------
287 - SNMP Data Collector Device Credential Configuration
289 After installing SNMP Data Collector, a configuration file under etc/
290 directory of ODL distribution is generated: etc/tsdr.snmp.cfg is
293 The following is a sample tsdr.snmp.cfg file:
295 credentials=[192.168.0.2,public],[192.168.0.3,public]
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.
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
305 Polling interval configuration for SNMP Collector and OpenFlow Stats Collector
306 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
313 - Retrieve Polling Interval API for SNMP Collector
316 http://localhost:8181/restconf/config/tsdr-snmp-data-collector:TSDRSnmpDataCollectorConfig
320 - Update Polling Interval API for SNMP Collector
323 http://localhost:8181/restconf/operations/tsdr-snmp-data-collector:setPollingInterval
327 - Content Type: application/json
339 - Retrieve Polling Interval API for OpenFlowStats Collector
342 http://localhost:8181/restconf/config/tsdr-openflow-statistics-collector:TSDROSCConfig
346 - Update Polling Interval API for OpenFlowStats Collector
349 http://localhost:8181/restconf/operations/tsdr-openflow-statistics-collector:setPollingInterval
353 - Content Type: application/json
365 Querying TSDR from REST APIs
366 ----------------------------
368 TSDR provides two REST APIs for querying data stored in TSDR data
371 - Query of TSDR Metrics
373 - URL: http://localhost:8181/tsdr/metrics/query
379 - tsdrkey=[NID=][DC=][MN=][RK=]
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.
391 - from=<time\_in\_seconds>
393 - until=<time\_in\_seconds>
395 The following is an example curl command for querying metric data from
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
403 - Query of TSDR Log type of data
405 - URL:http://localhost:8181/tsdr/logs/query
411 - tsdrkey=tsdrkey=[NID=][DC=][RK=]
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.
420 - from=<time\_in\_seconds>
422 - until=<time\_in\_seconds>
424 The following is an example curl command for querying log type of data
425 from TSDR data store:
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
432 Grafana integration with TSDR
433 -----------------------------
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.
439 For the detailed instruction about how to install and configure Grafana
440 to work with TSDR, please refer to the following link:
442 https://wiki.opendaylight.org/view/Grafana_Integration_with_TSDR_Step-by-Step
444 Purging Service configuration
445 -----------------------------
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
452 The following is the sample default content of the tsdr.data.purge.cfg
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
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.
464 How to use TSDR to collect, store, and view OpenFlow Interface Statistics
465 -------------------------------------------------------------------------
470 This tutorial describes an example of using TSDR to collect, store, and
471 view one type of time series data in OpenDaylight environment.
476 You would need to have the following as prerequisits:
478 - One or multiple OpenFlow enabled switches. Alternatively, you can use
479 mininet to simulate such a switch.
481 - Successfully installed OpenDaylight Controller.
483 - Successfully installed HBase Data Store following TSDR HBase Data
484 Store Installation Guide.
486 - Connect the OpenFlow enabled switch(es) to OpenDaylight Controller.
491 HBase data store is only supported in Linux operation system.
496 - Start OpenDaylight.
498 - Connect OpenFlow enabled switch(es) to the controller.
500 - If using mininet, run the following commands from mininet command
503 - mn --topo single,3 --controller
504 *remote,ip=172.17.252.210,port=6653* --switch
505 ovsk,protocols=OpenFlow13
507 - Install TSDR hbase feature from Karaf:
509 - feature:install odl-tsdr-hbase
511 - Install OpenFlow Statistics Collector from Karaf:
513 - feature:install odl-tsdr-openflow-statistics-collector
515 - run the following command from Karaf console:
517 - tsdr:list PORTSTATS
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.
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).
528 .. include:: tsdr-elastic-search.rst
537 All TSDR features and components write logging information including
538 information messages, warnings, errors and debug messages into
541 HBase and Cassandra logs
542 ~~~~~~~~~~~~~~~~~~~~~~~~
544 For HBase and Cassandra data stores, the database level logs are written
545 into HBase log and Cassandra logs.
549 - HBase log is under <HBase-installation-directory>/logs/.
553 - Cassandra log is under {cassandra.logdir}/system.log. The default
554 {cassandra.logdir} is /var/log/cassandra/.
559 TSDR gets the data from a variety of sources, which can be secured in
564 - The OpenFlow data can be configured with Transport Layer Security
565 (TLS) since the OpenFlow Plugin that TSDR depends on provides this
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.
576 - NetFlow, which cannot be configured with security so we recommend
577 making sure it flows only over a secured management network.
581 - Syslog, which cannot be configured with security so we recommend
582 making sure it flows only over a secured management network.
584 Support multiple data stores simultaneously at runtime
585 ------------------------------------------------------
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.
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.
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
603 metric-persistency=true
605 binary-persistency=true
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.
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:
618 - tsdr-persistence-hbase.properties
622 metric-persistency=false
624 binary-persistency=true
626 - tsdr-persistence-cassandra.properties
630 metric-psersistency=true
631 log-persistency=false
632 binary-persistency=false