query

The query command line tool is meant to be a quick debugging tool for extracting data from OpenTSDB. The HTTP API will usually be much quicker when querying data as it incorprates caches and open connections to storage. Results are printed to stdout in a text format with one data point per line.

Note that a query may return data points before and after the timespan requested. These are used in downsampling and graphing.

Parameters

query [Gnuplot opts] START-DATE [END-DATE] <aggregator> [rate] [counter,max,reset] [downsample N FUNC] <metric> [<tagk=tagv>] [...<tagk=tagv>] [...queries]

Name

Data Type

Description

Default

Example

Gnuplot opts

Strings

Optional values used to generate Gnuplot scripts and graphs. Note that the actual graph PNG will not be generated, only the files (written to the temp directory)

+wxh=1286x836

START-DATE

String or Integer

Starting time for the query. This may be an absolute or relative time. See Dates and Times for details

1h-ago

END-DATE

String or Integer

Optional end time for the query. If not provided, the current time is used. This may be an absolute or relative time. See Dates and Times for details

Current timestamp

2014/01/01-00:00:00

aggregator

String

A function to use when multiple timeseries are included in the results

sum

rate

String

The literal rate if the timeseries represents a counter and the results should be returned as delta per second

rate

counter

String

Optional literal counter that indicates the underlying data is a monotonically increasong counter that may roll over

counter

max

Integer

A positive integer representing the maximum value for the counter

Java Long.MaxValue

65535

resetValue

Integer

An optional value that, when exceeded, will cause the aggregator to return a 0 instead of the calculated rate. Useful when data sources are frequently reset to avoid spurious spikes.

65000

downsample N FUNC

String

Optional downsampling specifier to group data into larger time spans and reduce the amount of data returned. Format is the literal downsample followed by a timespan in milliseconds and an aggregation function name

downsample 300000 avg

metric

String

Required name of a metric to query for

sys.cpu.user

tagk=tagv

String

Optional pairs of tag names and tag values

host=web01

additional queries

String

Optional additional queries to execute. Each query must follow the same format starting with an aggregator. All queries share the same start and end times.

sum tsd.hbase.rpcs type=scan

For more details on querying, please see Querying or Reading Data.

Example:

query 1h-ago now sum tsd.hbase.rpcs type=put sum tsd.hbase.rpcs type=scan

Output Format

Data is printed to stdout with one data point per line. If one or more Gnuplot options were specified, then scripts and data files for each query will be written to the configured temporary directory.

<metric> <timestamp> <value> {<tagk=tagv>[,..<tagkN=tagvN>]}

Where:

  • metric Is the name of the metric queried

  • timestamp Is the absolute timestamp of the data point in seconds or milliseconds

  • value Is the data point value

  • tagk=tagv Is a list of common tag name and value pairs for all timeseries represented in the query

Example:

tsd.hbase.rpcs 1393376401000 28067146491 {type=put, fqdn=tsdb-data-1}
tsd.hbase.rpcs 1393376461000 28067526510 {type=put, fqdn=tsdb-data-1}
tsd.hbase.rpcs 1393376521000 28067826659 {type=put, fqdn=tsdb-data-1}
tsd.hbase.rpcs 1393376581000 28068126093 {type=put, fqdn=tsdb-data-1}