proxysql/doc/tsdb/embedded_tsdb_specs.md

# TSDB Technical Specifications

## Scope

Embedded time-series storage in SQLite for ProxySQL runtime metrics and backend probe health.

## Table Definitions

### `tsdb_metrics`

- Columns: `timestamp`, `metric_name`, `labels`, `value`
- PK: `(timestamp, metric_name, labels)`
- `labels` is JSON text, default `'{}'`

### `tsdb_metrics_hour`

- Columns: `bucket`, `metric_name`, `labels`, `avg_value`, `max_value`, `min_value`, `count`
- PK: `(bucket, metric_name, labels)`

### `tsdb_backend_health`

- Columns: `timestamp`, `hostgroup`, `hostname`, `port`, `probe_up`, `connect_ms`
- PK: `(timestamp, hostgroup, hostname, port)`

## Sampling and Rollup

- Sampler interval: `tsdb-sample_interval`
- Rollup interval: hourly
- Rollup SQL: `INSERT OR REPLACE ... GROUP BY bucket, metric_name, labels`

## Retention

- Raw metrics retention: `tsdb-retention_days`
- Backend probe retention: `tsdb-retention_days`
- Hourly rollup retention: 365 days

## Variable Semantics

- All TSDB variables are prefixed with `tsdb-`.
- Managed via `SET` commands and the dedicated command set:
  - `LOAD TSDB VARIABLES TO RUNTIME`
  - `SAVE TSDB VARIABLES TO DISK`
  - `SHOW TSDB VARIABLES`
  
  ## Current API Surface
  
  - C++ methods in `ProxySQL_Statistics` for insert, query, status, sampler/monitor loops.
  - SQL querying through `stats_history.tsdb_*` tables.
  - REST API endpoints:
    - `/api/tsdb/metrics`
    - `/api/tsdb/query`
    - `/api/tsdb/status`- Web Dashboard at `/tsdb`.