/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: Rollup And Pre-Aggregates.

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:


1. {
2. "metric": "sys.cpu.nice",
3. "timestamp": 1346846400,
4. "value": 18,
5. "tags": {
6. "host": "web01",
7. "dc": "lga"
8. },
9. "interval": "1h",
10. "aggregator": "SUM",
11. "groupByAggregator": "SUM"
12. }

Example Multiple Data Point Put

Multiple data points must be encased in an array:


1. [
2. {
3. "metric": "sys.cpu.nice",
4. "timestamp": 1346846400,
5. "value": 18,
6. "tags": {
7. "host": "web01",
8. "dc": "lga"
9. },
10. "interval": "1h",
11. "aggregator": "SUM",
12. "groupByAggregator": "SUM"
13. },
14. {
15. "metric": "sys.cpu.nice",
16. "timestamp": 1346846400,
17. "value": 9,
18. "tags": {
19. "host": "web02",
20. "dc": "lga"
21. },
22. "interval": "1h",
23. "aggregator": "SUM",
24. "groupByAggregator": "SUM"
25. }
26. ]

Response

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