What is Time-Series Database (TSDB)?
A database built to store and query timestamped measurements, such as metrics, grouped into series by name and labels.
Definition
A time-series database (TSDB) is a database optimised for data points that arrive in time order: a value plus a timestamp, recorded again and again for the same thing. In monitoring systems each series is identified by a metric name and a set of labels; Prometheus, for example, defines a time series by its metric name and optional key-value labels, and each sample is a float64 or native-histogram value with a millisecond timestamp, so api_http_requests_total{method="POST", handler="/messages"} is one series. Because writes are mostly appends of new samples and reads are mostly range scans over recent time, a TSDB can compress heavily, keep recent data in memory behind a write-ahead log, and drop old data by retention policy instead of row-by-row deletes. Prometheus documents an average of 1 to 2 bytes per sample and a 15-day default retention; VictoriaMetrics defaults to 31 days. Queries aggregate across series and time windows (rates, sums, percentiles) in languages such as PromQL. Changing any label value creates a new series, so cost and memory grow with the number of distinct label combinations.
When to Use Time-Series Database (TSDB)
Model labels for the questions you will ask, and keep their values bounded: status codes, regions and service names are fine, while user IDs, request IDs or full URLs create a new series per value and inflate memory and storage. Decide retention up front and size disk from your ingestion rate. A single-node TSDB such as Prometheus's local storage is not replicated, so long-term or highly available storage usually means remote write to a clustered system.
Time-Series Database (TSDB) in Practice
- Prometheus scrapes http_requests_total from every pod and stores each pod-and-status combination as its own series in its local TSDB.
- A team keeps 15 days in Prometheus and remote-writes every sample to VictoriaMetrics, which keeps a year of history for capacity planning.
- Sizing disk with Prometheus's formula: retention seconds × ingested samples per second × 1 to 2 bytes per sample.
Common Mistakes
- Putting unbounded values (user IDs, email addresses, request paths with IDs) into labels, causing a cardinality explosion.
- Using a metrics TSDB as an event log; it stores numeric samples well but is a poor fit for full log lines or per-request records.
- Assuming local TSDB storage is durable; Prometheus's own docs say it is not clustered or replicated.
- Comparing raw counter values instead of their rate or increase, which hides resets after restarts.