pg_track_optimizer

Track planning decisions in comparison with execution reality

Overview

PackageVersionCategoryLicenseLanguage
pg_track_optimizer0.9.1STATMITC
IDExtensionBinLibLoadCreateTrustRelocSchema
6270pg_track_optimizerNoYesYesYesNoYes-
Relatedpg_track_settings pg_show_plans powa pg_stat_statements pg_store_plans auto_explain pg_stat_kcache pg_qualstats

Version

TypeRepoVersionPG VerPackageDeps
EXTPIGSTY0.9.11817161514pg_track_optimizer-
RPMPIGSTY0.9.11817161514pg_track_optimizer_$v-
DEBPIGSTY0.9.11817161514postgresql-$v-pg-track-optimizer-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
el8.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
el9.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
el9.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
el10.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
el10.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
d12.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
d12.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
d13.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
d13.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
u22.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
u22.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
u24.x86_64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY MISS
u24.aarch64
PIGSTY 0.9.1
PIGSTY 0.9.1
PIGSTY MISSPIGSTY MISSPIGSTY 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

MetricDescription
avg_errorSimple average of log-scale errors across plan nodes
rms_errorRoot Mean Square, emphasizes large errors
twa_errorTime-Weighted Average, highlights slow nodes
wca_errorCost-Weighted Average, highlights high-cost nodes
f_join_filterJOIN filtering overhead factor
f_scan_filterScan 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

ParameterDefaultDescription
pg_track_optimizer.modedisableddisabled, 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_flushonAuto-save stats on backend shutdown

Last Modified 2026-03-12: add pg extension catalog (95749bf)