KairosDB

KairosDB is a Java-based time-series metrics API that leverages Cassandra as its underlying distributed database. This page shows how it can be integrated with YugabyteDB's Cassandra-compatible YCQL API.

Prerequisites

Before you start using the KairosDB plugin, ensure that you have:

Java version 1.8 or later.
The latest version of KairosDB.
The latest version of YugabyteDB plugin for KairosDB; read the README for details about the plugin.
A YugabyteDB cluster. Refer to YugabyteDB Quick start guide to install and start a local cluster.
Postman API Platform.
(Optional) YugabyteDB cassandra-driver-core-3.10.3-yb-2.jar, for better performance.

Start KairosDB

Copy the YugabyteDB plugin for KairosDB jar to the lib folder of your downloaded kairosdb directory.
(Optional) For better performance, replace the cassandra-driver-core-3.10.2.jar with the YugabyteDB cassandra-driver-core-3.10.3-yb-2.jar in the kairosdb/lib directory.
Add YugabyteDB datastore as the service.datastore entry in your kairosdb/conf/kairosdb.conf file.

#Configure the datastore

#service.datastore: "org.kairosdb.datastore.h2.H2Module"
#service.datastore: "org.kairosdb.datastore.cassandra.CassandraModule"
service.datastore: "com.yugabyte.kairosdb.datastore.yugabytedb.YugabyteDBModule"

Start KairosDB in the foreground.

$ ./bin/kairosdb.sh run

18:34:01.094 [main] INFO  [AbstractConnector.java:338] - Started SelectChannelConnector@0.0.0.0:8080
18:34:01.098 [main] INFO  [Main.java:522] - Starting service class org.kairosdb.core.telnet.TelnetServer
18:34:01.144 [main] INFO  [Main.java:378] - ------------------------------------------
18:34:01.144 [main] INFO  [Main.java:379] -      KairosDB service started
18:34:01.145 [main] INFO  [Main.java:380] - ------------------------------------------

The KairosDB API server should be available at localhost:8080.

Verify the integration using ycqlsh

Run ycqlsh to connect to your database using the YCQL API.

$ ./bin/ycqlsh localhost

Connected to local cluster at 127.0.0.1:9042.
[ycqlsh 5.0.1 | Cassandra 3.9-SNAPSHOT | CQL spec 3.4.2 | Native protocol v4]
Use HELP for help.
ycqlsh>

Run the following YCQL commands, and connect to the kairosdb keyspace to verify it is working:

ycqlsh> describe keyspaces;

kairosdb  system_schema  system_auth  system

ycqlsh> use kairosdb;

ycqlsh:kairosdb> describe tables;

tag_indexed_row_keys  row_key_index  service_index  row_key_time_index
row_keys              data_points    string_index   spec

Test KairosDB

Launch Postman via the app or web and create a new workspace from the homepage.

kairosdb workspace

Select the workspace and click the + button to create an HTTP request.

kairosdb request

Push data

Select the POST API request in the dropdown as follows:

kairosdb request type

Add the following URL in the Enter request URL box:

http://localhost:8080/api/v1/datapoints

In the body of the request, add the following JSON, then click Send.

[
  {
      "name": "archive_file_tracked",
      "datapoints": [[1359788400000, 123], [1359788300000, 13.2], [1359788410000, 23.1]],
      "tags": {
          "host": "server1",
          "data_center": "DC1"
      },
      "ttl": 300.0
  },
  {
      "name": "archive_file_search",
      "timestamp": 1359786400000,
      "value": 321,
      "tags": {
          "host": "server2"
      }
  }
]

Your request should look like:

kairosdb POST request

Your response should return a status code of 204 with no body.

kairosdb response

Query the data

To query the data you inserted using the POST API, enter the following URL in the Enter request URL box:

http://localhost:8080/api/v1/datapoints/query

In the body of the request, add the following JSON, and send it.

{
  "start_absolute":1359788400000,
  "metrics":[
    {
      "tags":{
        "host":"server1",
        "data_center":"DC1"
      },
      "name":"archive_file_tracked"
    }
  ]
}

Your request should look like:

kairosdb3

Your response should return a status code of 200, with the following output:

{
   "queries": [
       {
           "sample_size": 2,
           "results": [
               {
                   "name": "archive_file_tracked",
                   "group_by": [
                       {
                           "name": "type",
                           "type": "number"
                       }
                   ],
                   "tags": {
                       "data_center": [
                           "DC1"
                       ],
                       "host": [
                           "server1"
                       ]
                   },
                   "values": [
                       [
                           1359788400000,
                           123
                       ],
                       [
                           1359788410000,
                           23.1
                       ]
                   ]
               }
           ]
       }
   ]
}