OpenTSDB Explained: Architecture and Use Cases

What OpenTSDB is, and who this article is for

OpenTSDB was written to store and graph metrics from large fleets of servers and network equipment, using HBase for scale. Its home page summarises the design as storing data exactly as given, at millisecond precision, keeping raw data forever, running on Hadoop and HBase, and adding capacity by adding nodes.

Licence. The repository README states: "OpenTSDB is free software and is available under both LGPLv2.1+ and GPLv3+." The repository carries the licence texts as COPYING (the GNU General Public License version 3) and COPYING.LESSER (the GNU Lesser General Public License version 2.1). The README does not say which parts fall under which licence, so read both texts and the file headers of the code you use. Not legal advice: this paragraph quotes the project's statements; take advice for your situation.

This article is for engineers who have inherited an OpenTSDB installation, are evaluating it because it already runs alongside a Hadoop estate, or see its protocol supported by other databases and want to know what it is. If you are choosing a store for a new building or plant project, read the time-series database overview and the maintenance section below first.

Maintenance status in October 2026

We checked the project's own site and repository on 27 October 2026:

• The home page offers 2.4.1 as the download, and its latest news item announces that release on 2 September 2021.
• The GitHub releases page lists 2.4.1 as the latest release and 2.5.0 RC1 as a pre-release, whose notes include dependency and security fixes such as a Logback update for CVE-2021-42550.
• The most recent commit on the master branch, "Cut the 2.5.0-RC1 Release", is dated 12 December 2024; no later commits were listed on that date.
• The 2.4 documentation links to OpenTSDB 3.0 documentation that it describes as work in progress.
• The installation page of the 2.4 documentation, as published on that date, still lists "Java Runtime Environment 1.6 or later" and "HBase 0.92 or later" as runtime requirements. These are the documented minimums, not versions we recommend; the documentation we checked does not say which current Java and HBase versions are supported, so confirm compatibility for your release before choosing versions.

Our editorial view: the project is not abandoned in the sense of being archived, but releases are infrequent and there was no stable release between September 2021 and the date of checking. Treat it as a mature system in maintenance mode: plan for running it on supported Java and HBase versions yourself, track CVEs in its dependencies, and weigh a migration path if you are starting a new platform.

Architecture: TSDs on HBase or Bigtable

An OpenTSDB deployment has two layers:

• Time Series Daemons (TSDs). Java processes that accept writes and queries. Each TSD is independent: there is no master and no shared state, so you run as many as the load needs behind a load balancer. One port serves the telnet-style protocol, the HTTP API and a simple built-in graphing UI; the TSD detects the protocol from the first bytes.
• Storage. Apache HBase (on HDFS and ZooKeeper) or Google Cloud Bigtable, which uses the same schema. The 2.4 documentation's "What's New" page lists Cassandra support under 2.3, described as "for running OpenTSDB on legacy Cassandra clusters", and the Cassandra page calls the AsyncCassandra shim a way of "trying out TSDB with an alternate backend": it relies on Cassandra's Thrift interface and the ByteOrderedPartitioner. We found no statement of current support status, so treat it as experimental and check whether your Cassandra version still offers those features. Users never access the storage directly; all reads and writes go through TSDs.

The cost of this design is the stack underneath. Running OpenTSDB well means running HBase well: region servers, HDFS, ZooKeeper, compactions and region splits. Our editorial view: organisations that already operate Hadoop clusters may find that natural, while for a team without that experience it is likely to be the largest operational burden of the system. Bigtable removes the HBase operations but ties storage to Google Cloud, and the documentation notes that the Bigtable client was still in beta.

Data model: metrics, tags and UIDs

A data point has a metric name, a Unix timestamp in seconds or milliseconds, a value (a 64-bit integer or a floating-point number; the overview also lists JSON events and histograms) and a set of tags. Every series must have at least one tag, and every combination of metric and tag values is a separate series. The overview recommends no more than six or seven tags per data point, because storage cost grows with the number of tags.

To keep row keys short, OpenTSDB assigns a numeric UID to every metric name, tag key and tag value the first time it sees it, stored in a tsdb-uid table. UIDs are 3 bytes by default, which allows 16,777,215 distinct values of each type. Changing the width requires starting with fresh tables. For buildings, that limit matters only if tag values include something unbounded, such as a reading ID; tags like building, floor, asset and point type stay far below it.

put bms.meter.kw 1793091600 182.0 site=hq meter=m-01
put bms.meter.kw 1793091900 190.5 site=hq meter=m-01
put bms.meter.kw 1793091660 95.0 site=hq meter=m-02

Storage layout: hourly rows and compaction

In HBase, the row key is an optional salt, the metric UID, a 4-byte base timestamp and the tag key and value UIDs. The base timestamp is normalised to the hour, so one row holds up to one hour of one series, and each data point is a column whose qualifier encodes its offset in seconds (or milliseconds) from that hour plus format flags. Because HBase sorts rows by key, all series of one metric for the same hour sit next to each other; the documentation says data for the same metric and time bucket "will be grouped together for efficient queries". Salting (from 2.2) spreads hot metrics across regions.

Optionally, a TSD compacts a row after its hour has passed: the separate columns are merged into one to save space, and the individual columns are deleted. The OpenTSDB compaction is separate from HBase's own compactions.

The hourly layout, illustrated in SQL

The arithmetic is easy to see in SQL. This query splits each timestamp into the hour-aligned base that would go into the row key and the seconds offset that would become the column, then computes the equivalent of a 1h-avg downsampler per meter. It ran on SQLite 3.39.2. It illustrates the layout; it is not how OpenTSDB is queried.

CREATE TABLE points (
    metric TEXT    NOT NULL,
    ts     INTEGER NOT NULL,  -- Unix seconds
    value  REAL    NOT NULL,
    meter  TEXT    NOT NULL,
    site   TEXT    NOT NULL
);

INSERT INTO points VALUES
    ('bms.meter.kw', 1793091600, 182.0, 'm-01', 'hq'),
    ('bms.meter.kw', 1793091900, 190.5, 'm-01', 'hq'),
    ('bms.meter.kw', 1793094900, 176.0, 'm-01', 'hq'),
    ('bms.meter.kw', 1793095500, 171.5, 'm-01', 'hq'),
    ('bms.meter.kw', 1793091660, 95.0,  'm-02', 'hq');

-- How OpenTSDB's HBase schema splits a point: an hour-aligned base time in the row key, a seconds offset in the column
SELECT metric, meter, ts,
       ts - (ts % 3600)                       AS row_base_hour,
       datetime(ts - (ts % 3600), 'unixepoch') AS row_base_utc,
       ts % 3600                              AS column_offset_s
FROM points
ORDER BY meter, ts;

-- The equivalent of a 1h-avg downsampler, per meter
SELECT datetime(ts - (ts % 3600), 'unixepoch') AS hour_utc, meter,
       round(avg(value), 2) AS avg_kw, count(*) AS points
FROM points
GROUP BY ts - (ts % 3600), meter
ORDER BY meter, hour_utc;

metric        meter  ts          row_base_hour  row_base_utc         column_offset_s
bms.meter.kw  m-01   1793091600  1793091600     2026-10-27 09:00:00  0
bms.meter.kw  m-01   1793091900  1793091600     2026-10-27 09:00:00  300
bms.meter.kw  m-01   1793094900  1793091600     2026-10-27 09:00:00  3300
bms.meter.kw  m-01   1793095500  1793095200     2026-10-27 10:00:00  300
bms.meter.kw  m-02   1793091660  1793091600     2026-10-27 09:00:00  60

hour_utc             meter  avg_kw  points
2026-10-27 09:00:00  m-01   182.83  3
2026-10-27 10:00:00  m-01   171.5   1
2026-10-27 09:00:00  m-02   95      1

Writing, duplicates and querying

• Writing. The telnet put command sends one point per line; the documentation discourages it because it cannot report which points failed, and recommends the HTTP /api/put endpoint, which accepts batches of JSON points. Collectors such as tcollector, collectd and StatsD have OpenTSDB outputs, and several newer databases accept the OpenTSDB put formats for migration.
• Timestamps. Second-resolution timestamps take less space than millisecond ones, and mixing the two for one series slows queries, so for BMS data polled every few seconds or more, second resolution is worth considering unless your sources need milliseconds.
• Duplicates. Rewriting the same point within the hour is generally harmless, but a duplicate written after a row has been compacted makes queries over that row fail with an exception, unless tsd.storage.fix_duplicates (from 2.1) is enabled for last-write-wins. Gateways that replay buffers after an outage need that setting or their own de-duplication.
• Querying. A query names an aggregator, an optional downsampler and a metric with tag filters, as in the documented example /api/query?start=1h-ago&m=sum:rate:proc.stat.cpu{host=foo,type=idle}. Aggregators merge series across tags; downsamplers reduce resolution over time with fill policies for gaps. There is no SQL.

The query string below is our own adaptation for building meters and is an untried combination, not an instruction: the documentation describes each element separately (the m= grammar with an optional downsampler, relative start times in the form 1h-ago, downsamplers in the form 1m-avg-zero), but we did not find this combination as a documented example and have not run it. Treat it as a placeholder and confirm it against the documentation and a test instance of your version before use.

# UNTRIED COMBINATION: not a documented example; confirm before use
GET /api/query?start=1d-ago&m=avg:1h-avg:bms.meter.kw{site=hq}

Retention, rollups, security and sizing

• Retention. The README states that OpenTSDB never deletes or downsamples data. Expiring old data is done in the storage layer: the 2.x release notes mention setting a TTL when the HBase table is created, which HBase then enforces during its compactions.
• Rollups. From 2.4 OpenTSDB can store and query rollup and pre-aggregated series, but the documentation is explicit that it does not calculate them itself; you produce them with a separate batch or streaming job and write them back.
• Security. The HTTP API documentation says OpenTSDB lacks authentication and access control, recommends network ACLs or firewalls, and advises against running it on a machine with a public IP address. Put TSDs on a private network and expose only a proxy that adds authentication if anything outside must reach them.
• Sizing. Capacity is mostly an HBase question: estimate rows (one per series per hour), bytes per point from the encoding rules, replication in HDFS, and space for compactions; then measure with a sample of your own data.

Example: where OpenTSDB still fits

A utility already runs a Hadoop and HBase platform for other workloads and has used OpenTSDB for years to hold meter and substation telemetry. Ingest arrives from an MQTT broker through a bridge service that converts messages into HTTP /api/put batches; Grafana reads through the TSDs; HBase TTL keeps three years of raw data (an illustrative retention for the example; the right period follows from regulatory, billing and reporting needs). Our editorial view: in that situation OpenTSDB can be a reasonable component to keep running, because the team has the HBase skills, the data volume suits HBase, and the integrations exist.

What would change if the same team started again: a supported engine with its own retention, downsampling and authentication would remove the HBase dependency. Planning such a migration means exporting by metric and time range, mapping tags to the new model (tags to labels in VictoriaMetrics, to tag columns in InfluxDB, or to columns in a SQL table in TimescaleDB), and running both systems in parallel until dashboards match. Several of these databases accept OpenTSDB put formats, which can make the cut-over at the collector simpler. Maintenance work orders stay in the CMMS throughout; OpenTSDB was not designed to hold them.

When not to use OpenTSDB

• New projects without an HBase estate. Our editorial view: for most teams the operational cost of HBase, HDFS and ZooKeeper is likely to outweigh the benefits, and the project has had no stable release since 2021.
• Anything that needs access control in the database. The documentation says OpenTSDB lacks an authentication and access control system.
• SQL users. Our editorial view: analysts who need joins with asset or CMMS data are usually better served by a SQL time-series database such as TimescaleDB or QuestDB.
• Automatic downsampling and retention. Both must be built outside OpenTSDB.
• Small or medium deployments. Our editorial view: a partitioned PostgreSQL table, as in How to Store IoT Sensor Data, has far fewer components to run.

For current options, see the guide to choosing a time-series database.

Frequently asked questions

Sources

• OpenTSDB home page
• OpenTSDB overview
• OpenTSDB 2.4 documentation index
• OpenTSDB documentation: Installation
• OpenTSDB documentation: Writing data
• OpenTSDB documentation: HBase schema
• OpenTSDB documentation: Bigtable
• OpenTSDB documentation: UIDs and TSUIDs
• OpenTSDB documentation: Querying
• OpenTSDB documentation: Downsampling
• OpenTSDB documentation: Rollups and pre-aggregates
• OpenTSDB documentation: HTTP API
• OpenTSDB documentation: /api/query
• OpenTSDB documentation: Dates and times
• OpenTSDB documentation: What's new
• OpenTSDB documentation: Cassandra
• OpenTSDB repository on GitHub (README)
• OpenTSDB releases on GitHub
• OpenTSDB commit history on GitHub
• OpenTSDB repository: COPYING (GNU GPL v3)
• OpenTSDB repository: COPYING.LESSER (GNU LGPL v2.1)

Checked 27 October 2026.

How we research these articles: our editorial method. Research-based from official documentation; SQL examples are run on a local database where the page says so. CodeWithSQL earns nothing from the vendors mentioned.