pg_track_optimizer
Track planning decisions in comparison with execution reality
Repository
danolivo/pg_track_optimizer
https://github.com/danolivo/pg_track_optimizer
Source
pg_track_optimizer-0.9.1.tar.gz
pg_track_optimizer-0.9.1.tar.gz
Overview
| Package | Version | Category | License | Language |
|---|---|---|---|---|
pg_track_optimizer | 0.9.1 | STAT | MIT | C |
| ID | Extension | Bin | Lib | Load | Create | Trust | Reloc | Schema |
|---|---|---|---|---|---|---|---|---|
| 6270 | pg_track_optimizer | No | Yes | Yes | Yes | No | Yes | - |
| Related | pg_track_settings pg_show_plans powa pg_stat_statements pg_store_plans auto_explain pg_stat_kcache pg_qualstats |
|---|
Version
| Type | Repo | Version | PG Ver | Package | Deps |
|---|---|---|---|---|---|
| EXT | PIGSTY | 0.9.1 | 1817161514 | pg_track_optimizer | - |
| RPM | PIGSTY | 0.9.1 | 1817161514 | pg_track_optimizer_$v | - |
| DEB | PIGSTY | 0.9.1 | 1817161514 | postgresql-$v-pg-track-optimizer | - |
| OS / PG | PG18 | PG17 | PG16 | PG15 | PG14 |
|---|---|---|---|---|---|
| el8.x86_64 | PIGSTY 0.9.1 el8.x86_64.pg18 : pg_track_optimizer_18 pg_track_optimizer_18-0.9.1-1PIGSTY.el8.x86_64.rpm
| PIGSTY 0.9.1 el8.x86_64.pg17 : pg_track_optimizer_17 pg_track_optimizer_17-0.9.1-1PIGSTY.el8.x86_64.rpm
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| el8.aarch64 | PIGSTY 0.9.1 el8.aarch64.pg18 : pg_track_optimizer_18 pg_track_optimizer_18-0.9.1-1PIGSTY.el8.aarch64.rpm
| PIGSTY 0.9.1 el8.aarch64.pg17 : pg_track_optimizer_17 pg_track_optimizer_17-0.9.1-1PIGSTY.el8.aarch64.rpm
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| el9.x86_64 | PIGSTY 0.9.1 el9.x86_64.pg18 : pg_track_optimizer_18 pg_track_optimizer_18-0.9.1-1PIGSTY.el9.x86_64.rpm
| PIGSTY 0.9.1 el9.x86_64.pg17 : pg_track_optimizer_17 pg_track_optimizer_17-0.9.1-1PIGSTY.el9.x86_64.rpm
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| el9.aarch64 | PIGSTY 0.9.1 el9.aarch64.pg18 : pg_track_optimizer_18 pg_track_optimizer_18-0.9.1-1PIGSTY.el9.aarch64.rpm
| PIGSTY 0.9.1 el9.aarch64.pg17 : pg_track_optimizer_17 pg_track_optimizer_17-0.9.1-1PIGSTY.el9.aarch64.rpm
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| el10.x86_64 | PIGSTY 0.9.1 el10.x86_64.pg18 : pg_track_optimizer_18 pg_track_optimizer_18-0.9.1-1PIGSTY.el10.x86_64.rpm
| PIGSTY 0.9.1 el10.x86_64.pg17 : pg_track_optimizer_17 pg_track_optimizer_17-0.9.1-1PIGSTY.el10.x86_64.rpm
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| el10.aarch64 | PIGSTY 0.9.1 el10.aarch64.pg18 : pg_track_optimizer_18 pg_track_optimizer_18-0.9.1-1PIGSTY.el10.aarch64.rpm
| PIGSTY 0.9.1 el10.aarch64.pg17 : pg_track_optimizer_17 pg_track_optimizer_17-0.9.1-1PIGSTY.el10.aarch64.rpm
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| d12.x86_64 | PIGSTY 0.9.1 d12.x86_64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~bookworm_amd64.deb
| PIGSTY 0.9.1 d12.x86_64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~bookworm_amd64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| d12.aarch64 | PIGSTY 0.9.1 d12.aarch64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~bookworm_arm64.deb
| PIGSTY 0.9.1 d12.aarch64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~bookworm_arm64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| d13.x86_64 | PIGSTY 0.9.1 d13.x86_64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~trixie_amd64.deb
| PIGSTY 0.9.1 d13.x86_64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~trixie_amd64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| d13.aarch64 | PIGSTY 0.9.1 d13.aarch64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~trixie_arm64.deb
| PIGSTY 0.9.1 d13.aarch64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~trixie_arm64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| u22.x86_64 | PIGSTY 0.9.1 u22.x86_64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~jammy_amd64.deb
| PIGSTY 0.9.1 u22.x86_64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~jammy_amd64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| u22.aarch64 | PIGSTY 0.9.1 u22.aarch64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~jammy_arm64.deb
| PIGSTY 0.9.1 u22.aarch64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~jammy_arm64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| u24.x86_64 | PIGSTY 0.9.1 u24.x86_64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~noble_amd64.deb
| PIGSTY 0.9.1 u24.x86_64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~noble_amd64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
| u24.aarch64 | PIGSTY 0.9.1 u24.aarch64.pg18 : postgresql-18-pg-track-optimizer postgresql-18-pg-track-optimizer_0.9.1-1PIGSTY~noble_arm64.deb
| PIGSTY 0.9.1 u24.aarch64.pg17 : postgresql-17-pg-track-optimizer postgresql-17-pg-track-optimizer_0.9.1-1PIGSTY~noble_arm64.deb
| PIGSTY MISS | PIGSTY MISS | PIGSTY MISS |
Build
You can build the RPM / DEB packages for pg_track_optimizer using pig build:
pig build pkg pg_track_optimizer # build RPM / DEB packages
Install
You can install pg_track_optimizer directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:
pig repo add pgsql -u # Add repo and update cache
Install the extension using pig or apt/yum/dnf:
pig install pg_track_optimizer; # Install for current active PG version
pig ext install -y pg_track_optimizer -v 18 # PG 18
pig ext install -y pg_track_optimizer -v 17 # PG 17
dnf install -y pg_track_optimizer_18 # PG 18
dnf install -y pg_track_optimizer_17 # PG 17
apt install -y postgresql-18-pg-track-optimizer # PG 18
apt install -y postgresql-17-pg-track-optimizer # PG 17
Preload:
shared_preload_libraries = 'pg_track_optimizer';
Create Extension:
CREATE EXTENSION pg_track_optimizer;
Usage
pg_track_optimizer: detect suboptimal query plans via cardinality estimation errors
pg_track_optimizer automatically detects queries with poor cardinality estimates by comparing planner predictions to actual execution results. It calculates multiple error metrics using logarithmic scale.
Enable Tracking
-- Track only problematic queries in production
SET pg_track_optimizer.mode = 'normal';
-- Track all queries during debugging
SET pg_track_optimizer.mode = 'forced';
-- Log EXPLAIN for queries exceeding error threshold
SET pg_track_optimizer.log_min_error = 2.0;
Viewing Tracked Queries
SELECT queryid, query,
avg_avg, avg_min, avg_max,
rms_avg, rms_min, rms_max,
time_avg, blks_avg, nexecs
FROM pg_track_optimizer
ORDER BY avg_avg DESC
LIMIT 10;
-- Using the RStats type directly
SELECT queryid, query,
wca_error -> 'mean' AS avg_wca_error,
blks_accessed -> 'mean' AS avg_blocks
FROM pg_track_optimizer()
WHERE blks_accessed -> 'mean' > 1000
ORDER BY wca_error -> 'mean' DESC;
Error Metrics
| Metric | Description |
|---|---|
avg_error | Simple average of log-scale errors across plan nodes |
rms_error | Root Mean Square, emphasizes large errors |
twa_error | Time-Weighted Average, highlights slow nodes |
wca_error | Cost-Weighted Average, highlights high-cost nodes |
f_join_filter | JOIN filtering overhead factor |
f_scan_filter | Scan filtering overhead factor |
Managing Statistics
-- Save statistics to disk
SELECT pg_track_optimizer_flush();
-- Clear all tracked statistics
SELECT pg_track_optimizer_reset();
-- Check extension status
SELECT * FROM pg_track_optimizer_status;
Configuration
| Parameter | Default | Description |
|---|---|---|
pg_track_optimizer.mode | disabled | disabled, normal, forced |
pg_track_optimizer.log_min_error | (none) | Error threshold for logging EXPLAIN |
pg_track_optimizer.hash_mem | (default) | Shared memory limit in KB |
pg_track_optimizer.auto_flush | on | Auto-save stats on backend shutdown |
Feedback
Was this page helpful?
Thanks for the feedback! Please let us know how we can improve.
Sorry to hear that. Please let us know how we can improve.