proxysql/doc/tsdb/embedded_tsdb_reference.md

TSDB Reference Manual

Configuration Variables

The behavior of the TSDB subsystem is controlled by the following global variables:

Variable	Type	Default	Range	Description
tsdb-enabled	int	0	0/1	Master switch
tsdb-sample_interval	int	5	1..3600	Prometheus sampling interval (seconds)
tsdb-retention_days	int	7	1..3650	Raw/probe retention in days
tsdb-monitor_enabled	int	0	0/1	Backend probe switch
tsdb-monitor_interval	int	10	1..3600	Probe interval (seconds)

Apply Changes

SET tsdb-enabled=1;
LOAD TSDB VARIABLES TO RUNTIME;
SAVE TSDB VARIABLES TO DISK;

Tables

stats_history.tsdb_metrics

CREATE TABLE tsdb_metrics (
    timestamp INT NOT NULL,
    metric_name TEXT NOT NULL,
    labels TEXT NOT NULL DEFAULT '{}',
    value REAL,
    PRIMARY KEY (timestamp, metric_name, labels)
) WITHOUT ROWID;

stats_history.tsdb_metrics_hour

CREATE TABLE tsdb_metrics_hour (
    bucket INT NOT NULL,
    metric_name TEXT NOT NULL,
    labels TEXT NOT NULL DEFAULT '{}',
    avg_value REAL,
    max_value REAL,
    min_value REAL,
    count INT,
    PRIMARY KEY (bucket, metric_name, labels)
) WITHOUT ROWID;

stats_history.tsdb_backend_health

CREATE TABLE tsdb_backend_health (
    timestamp INT NOT NULL,
    hostgroup INT NOT NULL,
    hostname TEXT NOT NULL,
    port INT NOT NULL,
    probe_up INT NOT NULL,
    connect_ms INT,
    PRIMARY KEY (timestamp, hostgroup, hostname, port)
) WITHOUT ROWID;

Prometheus Ingestion Mapping

• Counter -> <name>
• Gauge -> <name>
• Untyped -> <name>
• Info -> <name>
• Summary -> <name>{quantile=...}, plus <name>_sum, <name>_count
• Histogram -> <name>_bucket{le=...}, plus <name>_sum, <name>_count

SQL Examples

SELECT metric_name, labels, value
FROM stats_history.tsdb_metrics
WHERE timestamp > unixepoch() - 300
ORDER BY timestamp DESC
LIMIT 50;

SELECT datetime(bucket, 'unixepoch') AS hour, metric_name, avg_value, max_value, min_value, count
FROM stats_history.tsdb_metrics_hour
WHERE bucket > unixepoch() - 86400
ORDER BY bucket;

SELECT datetime(timestamp, 'unixepoch') AS ts, hostgroup, hostname, port, probe_up, connect_ms
FROM stats_history.tsdb_backend_health
WHERE timestamp > unixepoch() - 3600
ORDER BY timestamp DESC;