Pushing data

You can submit data either with the telnet protocol on port 4242 or the rest protocol on port 8080 (ports can be changed in the kairosdb.properties file). Other mechanisms exist for getting data into KairosDB. A list of plugins and external projects can be found on the external projects page.

Note: Of the two default protocols only the rest protocol handles custom data types.

A great client for testing data in and out is [http://code.google.com/p/rest-client/]

Submitting data via telnet

The format of the data is

put <metric name> <time stamp> <value> <tag> <tag>... \n

Metric name must be one word and is limited to alpha numerics with “-_.”.

Time stamp can either be in milliseconds or in seconds since Jan 1, 1970 (unix epoch) - seconds are for backwards compatibility with the original opentsdb. The Cassandra datastore supports milliseconds.

Note: The REST API only supports a timestamp in milliseconds.

Value can either be a long or double value.

Tag is in the form of key=value.

Be aware that the data sent must be followed by a line feed character.

Here is a simple shell script that inserts data using netcat.


# Current time in milliseconds
now=$(($(date +%s%N)/1000000))

echo "put $metric $now $value host=A" | nc -w 30 $host 4242

Submitting data via rest

The url for submitting data is http://localhost:8080/api/v1/datapoints

    "name": "archive.file.tracked",
    "timestamp": 1349109376,
    "type": "long",
    "value": 123,
    "name": "archive.file.search",
    "timestamp": 999,
    "type": "double",
    "value": 32.1,

In the case of the rest api the timestamp is always treated as milliseconds since Jan 1, 1970. If you are writing to HBase it is truncated off to the second.

See the REST API documentation for more details

Graphite protocol

KairosDB now supports the Graphite plaintext and pickle protocol as explained here. This lets you integrate KairosDB with existing applications that push data to Graphite. Please see the external projects page for a link to the plugin.