net.opentsdb.core
Class TSDB

java.lang.Object
  net.opentsdb.core.TSDB

public final class TSDB
extends Object

Thread-safe implementation of the TSDB client.

This class is the central class of OpenTSDB. You use it to add new data points or query the database.

Constructor Summary

TSDB(org.hbase.async.HBaseClient client, String timeseries_table, String uniqueids_table)
Constructor.

Method Summary

Deferred<Object>	addPoint(String metric, long timestamp, float value, Map<String,String> tags) Adds a single floating-point value data point in the TSDB.
Deferred<Object>	addPoint(String metric, long timestamp, long value, Map<String,String> tags) Adds a single integer value data point in the TSDB.
void	collectStats(StatsCollector collector) Collects the stats and metrics tracked by this instance.
Deferred<Object>	flush() Forces a flush of any un-committed in memory data.
Histogram	getPutLatencyHistogram() Returns a latency histogram for Put RPCs used to store data points.
Histogram	getScanLatencyHistogram() Returns a latency histogram for Scan RPCs used to fetch data points.
WritableDataPoints	newDataPoints() Returns a new WritableDataPoints instance suitable for this TSDB.
Query	newQuery() Returns a new Query instance suitable for this TSDB.
Deferred<Object>	shutdown() Gracefully shuts down this instance.
List<String>	suggestMetrics(String search) Given a prefix search, returns a few matching metric names.
List<String>	suggestTagNames(String search) Given a prefix search, returns a few matching tag names.
List<String>	suggestTagValues(String search) Given a prefix search, returns a few matching tag values.
int	uidCacheHits() Number of cache hits during lookups involving UIDs.
int	uidCacheMisses() Number of cache misses during lookups involving UIDs.
int	uidCacheSize() Number of cache entries currently in RAM for lookups involving UIDs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TSDB

public TSDB(org.hbase.async.HBaseClient client,
            String timeseries_table,
            String uniqueids_table)

Constructor.

Parameters:

client - The HBase client to use.

timeseries_table - The name of the HBase table where time series data is stored.

uniqueids_table - The name of the HBase table where the unique IDs are stored.

Method Detail

uidCacheHits

public int uidCacheHits()

Number of cache hits during lookups involving UIDs.

uidCacheMisses

public int uidCacheMisses()

Number of cache misses during lookups involving UIDs.

uidCacheSize

public int uidCacheSize()

Number of cache entries currently in RAM for lookups involving UIDs.

collectStats

public void collectStats(StatsCollector collector)

Collects the stats and metrics tracked by this instance.

Parameters:

collector - The collector to use.

getPutLatencyHistogram

public Histogram getPutLatencyHistogram()

Returns a latency histogram for Put RPCs used to store data points.

getScanLatencyHistogram

public Histogram getScanLatencyHistogram()

Returns a latency histogram for Scan RPCs used to fetch data points.

newQuery

public Query newQuery()

Returns a new Query instance suitable for this TSDB.

newDataPoints

public WritableDataPoints newDataPoints()

Returns a new WritableDataPoints instance suitable for this TSDB.

If you want to add a single data-point, consider using addPoint(java.lang.String, long, long, java.util.Map) instead.

addPoint

public Deferred<Object> addPoint(String metric,
                                 long timestamp,
                                 long value,
                                 Map<String,String> tags)

Adds a single integer value data point in the TSDB.

Parameters:

metric - A non-empty string.

timestamp - The timestamp associated with the value.

value - The value of the data point.

tags - The tags on this series. This map must be non-empty.

Returns:

A deferred object that indicates the completion of the request. The Object has not special meaning and can be null (think of it as Deferred<Void>). But you probably want to attach at least an errback to this Deferred to handle failures.

Throws:

IllegalArgumentException - if the timestamp is less than or equal to the previous timestamp added or 0 for the first timestamp, or if the difference with the previous timestamp is too large.

IllegalArgumentException - if the metric name is empty or contains illegal characters.

IllegalArgumentException - if the tags list is empty or one of the elements contains illegal characters.

org.hbase.async.HBaseException - (deferred) if there was a problem while persisting data.

addPoint

public Deferred<Object> addPoint(String metric,
                                 long timestamp,
                                 float value,
                                 Map<String,String> tags)

Adds a single floating-point value data point in the TSDB.

Parameters:

metric - A non-empty string.

timestamp - The timestamp associated with the value.

value - The value of the data point.

tags - The tags on this series. This map must be non-empty.

Returns:

A deferred object that indicates the completion of the request. The Object has not special meaning and can be null (think of it as Deferred<Void>). But you probably want to attach at least an errback to this Deferred to handle failures.

Throws:

IllegalArgumentException - if the timestamp is less than or equal to the previous timestamp added or 0 for the first timestamp, or if the difference with the previous timestamp is too large.

IllegalArgumentException - if the metric name is empty or contains illegal characters.

IllegalArgumentException - if the value is NaN or infinite.

IllegalArgumentException - if the tags list is empty or one of the elements contains illegal characters.

org.hbase.async.HBaseException - (deferred) if there was a problem while persisting data.

flush

public Deferred<Object> flush()
                       throws org.hbase.async.HBaseException

Forces a flush of any un-committed in memory data.

For instance, any data point not persisted will be sent to HBase.

Returns:

A Deferred that will be called once all the un-committed data has been successfully and durably stored. The value of the deferred object return is meaningless and unspecified, and can be null.

Throws:

org.hbase.async.HBaseException - (deferred) if there was a problem sending un-committed data to HBase. Please refer to the HBaseException hierarchy to handle the possible failures. Some of them are easily recoverable by retrying, some are not.

shutdown

public Deferred<Object> shutdown()

Gracefully shuts down this instance.

This does the same thing as flush() and also releases all other resources.

Returns:

A Deferred that will be called once all the un-committed data has been successfully and durably stored, and all resources used by this instance have been released. The value of the deferred object return is meaningless and unspecified, and can be null.

Throws:

org.hbase.async.HBaseException - (deferred) if there was a problem sending un-committed data to HBase. Please refer to the HBaseException hierarchy to handle the possible failures. Some of them are easily recoverable by retrying, some are not.

suggestMetrics

public List<String> suggestMetrics(String search)

Given a prefix search, returns a few matching metric names.

Parameters:

search - A prefix to search.

suggestTagNames

public List<String> suggestTagNames(String search)

Given a prefix search, returns a few matching tag names.

Parameters:

search - A prefix to search.

suggestTagValues

public List<String> suggestTagValues(String search)

Given a prefix search, returns a few matching tag values.

Parameters:

search - A prefix to search.