proxysql/doc/tsdb/embedded_tsdb_architecture.md

# TSDB Architecture

## Runtime Components

- `ProxySQL_Admin` main loop triggers three TSDB schedulers:
  - sampler (`tsdb_sampler_loop`)
  - downsampler (`tsdb_downsample_metrics`)
  - backend monitor (`tsdb_monitor_loop`)
- Data is stored in `statsdb_disk` SQLite tables.

## Data Path

1. Sampler collects all metric families from `GloVars.prometheus_registry->Collect()`.
2. Samples are normalized and inserted into `tsdb_metrics`.
3. Hourly job aggregates into `tsdb_metrics_hour`.
4. Backend monitor probes servers from `runtime_mysql_servers` and stores in `tsdb_backend_health`.
5. Retention cleanup removes old raw/probe data using configured days.

## Metric Family Handling

- Counter/Gauge/Untyped/Info: one sample per metric point.
- Summary: quantiles plus `_sum` and `_count` companion metrics.
- Histogram: `_bucket{le=...}` plus `_sum` and `_count` companion metrics.

## Storage Schema

- `tsdb_metrics`: PK `(timestamp, metric_name, labels)`
- `tsdb_metrics_hour`: PK `(bucket, metric_name, labels)`
- `tsdb_backend_health`: PK `(timestamp, hostgroup, hostname, port)`

## Configuration Lifecycle

TSDB configuration is handled via standard global variables with the `tsdb-` prefix. Changes are applied and persisted using the following dedicated administrative commands:

- `LOAD TSDB VARIABLES TO RUNTIME`
- `SAVE TSDB VARIABLES TO DISK`

These commands function similarly to their `MYSQL` and `PGSQL` counterparts, moving configuration between memory and disk storage.