pg_test_timing

Run the default timing test (3 seconds)

$ pg_test_timing

$ pg_test_timing [[-d|--duration]] [seconds]

pg_test_timing [-r N | --runs=N] [-t N | --time=N] [-p N | --precision=N] [-w N | --warmup=N] [-h | --help]

-r N, --runs=N
    number of timing runs (default: 100000)

-t N, --time=N
    duration of test run in seconds (default: 1.0); overrides -r if both specified

-p N, --precision=N
    report precision in microseconds per timing call (default: auto-detect)

-w N, --warmup=N
    number of warmup runs before measurement (default: 1000)

-h, --help
    show help message and exit

pg_test_timing is a utility from the PostgreSQL source distribution designed to precisely measure the overhead of the system's low-level timing functions, such as gettimeofday() on Unix-like systems or QueryPerformanceCounter() on Windows.

This overhead is subtracted from timing measurements in PostgreSQL's performance instrumentation, including EXPLAIN ANALYZE, pg_stat_statements, and log timings, ensuring accurate reporting of query execution times.

The tool executes a tight loop of timing calls, performs warmup iterations to stabilize caches, and computes the average time per call. It supports running for a fixed number of iterations or duration, with automatic or manual precision settings for output.

Primarily used during PostgreSQL builds, regression tests, or by developers tuning performance on specific hardware/OS combinations. Results help calibrate constants like TimingOverhead in PostgreSQL's backend code.

Output example: average timing overhead = 0.123 usec/timing. Variability depends on CPU, kernel, and system load.

Results are hardware/OS-specific and affected by system load; run multiple times for averages. Not for production use; intended for PostgreSQL development/builds. No installation on binary packages.

Prints lines like:
did NNNN timing calls in X.XXX sec
average timing overhead = Y.YYY usec/timing

pg_test_timing -t 5 -w 5000
Runs for 5 seconds after 5000 warmups.

Introduced in PostgreSQL 7.3 (2002) as part of the test suite; evolved for cross-platform timing calibration, with Windows support added in 8.1 (2005). Key for accurate instr_time.h overhead constants.

pg_test_fsync(1), pgbench(1), postgres(1)