proxysql/doc/tsdb/embedded_tsdb_overview.md

# Embedded TSDB Overview

## What It Is

The ProxySQL TSDB is an embedded SQLite-based time-series store implemented in `ProxySQL_Statistics`.
It records Prometheus metrics and optional backend TCP probe health into `statsdb_disk`.

## What It Currently Implements

- Storage in SQLite tables:
  - `tsdb_metrics` (raw samples)
  - `tsdb_metrics_hour` (hourly rollups)
  - `tsdb_backend_health` (backend probes)
- Periodic sampling from the built-in Prometheus registry.
- Sampling of all Prometheus metric families:
  - Counter, Gauge, Summary, Histogram, Info, Untyped.
- Optional backend TCP probe loop for `runtime_mysql_servers`.
- Hourly downsampling and retention cleanup.
- Query access via SQL on `statsdb_disk.*` tables.

## Configuration Model

TSDB settings are standard global variables with the `tsdb-` prefix. They can be managed via standard `SET` commands or through the dedicated TSDB command set:

- `SET tsdb-...`
- `LOAD TSDB VARIABLES TO RUNTIME`
- `SAVE TSDB VARIABLES TO DISK`
- `SHOW TSDB VARIABLES`
- `SHOW TSDB STATUS`

## UI and REST API

A built-in dashboard is available at `/tsdb` on the ProxySQL HTTP Server (default port 6080).
It provides a simple visualization of collected metrics.

REST API endpoints are available under `/api/tsdb/` for external integrations.

## Variables

- `tsdb-enabled` (0/1)
- `tsdb-sample_interval` (1..3600 seconds)
- `tsdb-retention_days` (1..3650)
- `tsdb-monitor_enabled` (0/1)
- `tsdb-monitor_interval` (1..3600 seconds)

## Retention

- Raw metrics (`tsdb_metrics`): `tsdb-retention_days`
- Backend probes (`tsdb_backend_health`): `tsdb-retention_days`
- Hourly rollups (`tsdb_metrics_hour`): fixed 365 days