/api/rollup

This endpoint allows for storing rolled up and/or pre-aggregated data in OpenTSDB over HTTP. For details on rollups and pre-aggs, please see the user guide: ../../user_guide/rollups.

Also see the /api/put documentation for notes and common parameters that are shared with the /api/rollup endpoint. This page lays out the differences between the two.

Verbs

  • POST

Requests

Rollup and pre-aggregate values are extensions of the put object with three additional fields. For completeness, all fields are listed below:

Name

Data Type

Required

Description

Default

QS

RW

Example

metric

String

Required

The name of the metric you are storing

W

sys.cpu.nice

timestamp

Integer

Required

A Unix epoch style timestamp in seconds or milliseconds. The timestamp must not contain non-numeric characters.

W

1365465600

value

Integer, Float, String

Required

The value to record for this data point. It may be quoted or not quoted and must conform to the OpenTSDB value rules: ../../user_guide/writing

W

42.5

tags

Map

Required

A map of tag name/tag value pairs. At least one pair must be supplied.

W

{“host”:”web01”}

interval

String

Optional*

A time interval reflecting what timespan the rollup value represents. The interval consists of <amount><unit> similar to a downsampler or relative query timestamp. E.g. 6h for 5 hours of data, 30m for 30 minutes of data.

W

1h

aggregator

String

Optional*

An aggregation function used to generate the rollup value. Must match a supplied TSDB aggregator.

W

SUM

groupByAggregator

String

Optional*

An aggregation function used to generate the pre-aggregate value. Must match a supplied TSDB aggregator.

W

COUNT

While the aggregators and interval are marked as optional above, at least one of the combinations documented below must be satisfied for data to be recorded.

interval

aggregator

groupByAggregator

Description

Set

Set

Empty

Data represents a raw or non-pre-aggregated rollup over the interval.

Empty

Empty

Set

Data represents a raw pre-aggregated value that has not been rolled up over time.

Set

Set

Set

Data represents a rolled up pre-aggregated value.

Example Single Data Point Put

You can supply a single data point in a request:

{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "tags": {
       "host": "web01",
       "dc": "lga"
    },
    "interval": "1h",
    "aggregator": "SUM",
    "groupByAggregator": "SUM"
}

Example Multiple Data Point Put

Multiple data points must be encased in an array:

[
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 18,
        "tags": {
           "host": "web01",
           "dc": "lga"
        },
        "interval": "1h",
        "aggregator": "SUM",
        "groupByAggregator": "SUM"
    },
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 9,
        "tags": {
           "host": "web02",
           "dc": "lga"
        },
        "interval": "1h",
        "aggregator": "SUM",
        "groupByAggregator": "SUM"
    }
]

Response

Responses are handled in the same was as for the /api/put endpoint.