Package: pg-statviz
pg_statvizpg_statvizis a minimalist extension and utility pair for time series analysis and visualization
of PostgreSQL internal statistics.Created for snapshotting PostgreSQL's cumulative and dynamic statistics and performing time series
analysis on them. The accompanying utility can produce visualizations for selected time ranges on
the stored stats snapshots, enabling the user to track PostgreSQL performance over time and
potentially perform tuning or troubleshooting.Design PhilosophyDesigned with theK.I.S.S.andUNIXphilosophies in mind,pg_statvizaims to be
a modular, minimal and unobtrusive tool that does only what it's meant for: create snapshots
of PostgreSQL statistics for visualization and analysis. To this end, a utility is provided for
retrieving the stored snapshots and creating with them simple visualizations usingMatplotlib.Installing the extensionRed Hat Enterprise Linux (v8.0+) / Fedora (37+)Configure the PostgreSQL Yum repository for your Linux distribution, asexplained here.Usednforyumto install the extension for your PostgreSQL version:sudo dnf install pg_statviz_extension-<pg_version>
 OR
 sudo yum install pg_statviz_extension-<pg_version>PGXN (PostgreSQL Extension Network)The extension is available onPGXN.To install from PGXN, either download the zip file and install manually or use thePGXN Clientto install:pgxn install pg_statvizManual installationTo install manually, clone this repository locally:git clone https://github.com/vyruss/pg_statviz.gitThis will install the extension in the appropriate location for your system ($SHAREDIR/extension):cd pg_statviz
sudo make installEnabling the extensionThe extension can now be enabled inside the appropriate database like this, e.g. frompsql:\c mydatabase
CREATE EXTENSION pg_statviz;This will create the needed tables and functions under schemapgstatviz(note the lack of
underscore in the schema name).Installing the utilityThe visualization utility can also be installed fromPyPi:pip install pg_statvizThe utility is also available in thePostgreSQL Yum Repositoryand can be installed
usingdnforyum:sudo dnf install pg_statviz
OR 
sudo yum install pg_statvizRequirementsPython 3.9+ is required for the visualization utility.UsageThe extension can be used by superusers, or any user that haspg_monitorrole privileges. To take
a snapshot, e.g. frompsql:SELECT pgstatviz.snapshot();NOTICE:  created pg_statviz snapshot
           snapshot
-------------------------------

 2023-01-27 11:04:58.055453+00

(1 row)Older snapshots and their associated data can be removed using any time expression. For example, to
remove data more than 90 days old:DELETE FROM pgstatviz.snapshots
WHERE snapshot_tstamp < CURRENT_DATE - 90;Or all snapshots can be removed like this:SELECT pgstatviz.delete_snapshots();NOTICE:  truncating table "snapshots"
NOTICE:  truncate cascades to table "conf"
NOTICE:  truncate cascades to table "buf"
NOTICE:  truncate cascades to table "conn"     
NOTICE:  truncate cascades to table "lock"
NOTICE:  truncate cascades to table "wait"                
NOTICE:  truncate cascades to table "wal"
NOTICE:  truncate cascades to table "db"
 delete_snapshots 
------------------

(1 row)Thepg_monitorrole can be assigned to any user:GRANT pg_monitor TO myuser;SchedulingPeriodic snapshots can be set up with any job scheduler. For example withcron:crontab -e -u postgresInside thepostgresuser's crontab, add this line to take a snapshot every 15 minutes:*/15 * * * * psql -c "SELECT pgstatviz.snapshot()" >/dev/null 2>&1VisualizationThe visualization utility can be called like a PostgreSQL command line tool:pg_statviz --helpusage: pg_statviz [--help] [--version] [-d DBNAME] [-h HOSTNAME] [-p PORT] [-U USERNAME] [-W]
                  [-D FROM TO] [-O OUTPUTDIR]
                  {analyze,buf,cache,checkp,conn,lock,tuple,wait,wal,xact} ...

run all analysis modules

positional arguments:
  {analyze,buf,cache,checkp,conn,tuple,wait,wal,xact}
    analyze             run all analysis modules
    buf                 run buffers written analysis module
    cache               run cache hit ratio analysis module
    checkp              run checkpoint analysis module
    conn                run connection count analysis module
    lock                run locks analysis module
    tuple               run tuple count analysis module
    wait                run wait events analysis module
    wal                 run WAL generation analysis module
    xact                run transaction count analysis module

options:
  --help
  --version             show program's version number and exit
  -d DBNAME, --dbname DBNAME
                        database name to analyze (default: 'myuser')
  -h HOSTNAME, --host HOSTNAME
                        database server host or socket directory (default: '/var/run/postgresql')
  -p PORT, --port PORT  database server port (default: '5432')
  -U USERNAME, --username USERNAME
                        database user name (default: 'myuser')
  -W, --password        force password prompt (should happen automatically) (default: False)
  -D FROM TO, --daterange FROM TO
                        date range to be analyzed in ISO 8601 format e.g. 2023-01-01T00:00
                        2023-01-01T23:59 (default: [])
  -O OUTPUTDIR, --outputdir OUTPUTDIR
                        output directory (default: -)Specific module usagepg_statviz conn --helpusage: pg_statviz conn [-h] [-d DBNAME] [--host HOSTNAME] [-p PORT] [-U USERNAME] [-W]
                       [-D FROM TO] [-O OUTPUTDIR] [-u [USERS ...]]

run connection count analysis module

options:
  -h, --help            show this help message and exit
  -d DBNAME, --dbname DBNAME
                        database name to analyze (default: 'myuser')
  --host HOSTNAME       database server host or socket directory (default: '/var/run/postgresql')
  -p PORT, --port PORT  database server port (default: '5432')
  -U USERNAME, --username USERNAME
                        database user name (default: 'myuser')
  -W, --password        force password prompt (should happen automatically) (default: False)
  -D FROM TO, --daterange FROM TO
                        date range to be analyzed in ISO 8601 format e.g. 2023-01-01T00:00
                        2023-01-01T23:59 (default: [])
  -O OUTPUTDIR, --outputdir OUTPUTDIR
                        output directory (default: -)
  -u [USERS ...], --users [USERS ...]
                        user name(s) to plot in analysis (default: [])Example:pg_statviz buf --host localhost -d postgres -U postgres -D 2023-01-24T23:00 2023-01-26Produces:SchemaThepg_statvizextension stores its data in the following tables:TableDescriptionpgstatviz.snapshotsTimestamped snapshotspgstatviz.bufBuffer, checkpointer and background writer datapgstatviz.confPostgreSQL server configuration datapgstatviz.connConnection datapgstatviz.dbPostgreSQL server and database statisticspgstatviz.lockLocks datapgstatviz.waitWait events datapgstatviz.walWAL generation dataExport dataTo dump the captured data, e.g. for analysis on a different machine, run:pg_dump -a -O -t pgstatviz.* > pg_statviz_data.dumpLoad it like this on the target database (which should havepg_statvizinstalled) :psql -f pg_statviz_data.dump -d <dbname>Alternatively,pg_statvizinternal tables can also be exported to a tab separated values (TSV) file
for use by other tools:psql -c "COPY pgstatviz.conn TO STDOUT CSV HEADER DELIMITER E'\t'" > conn.tsvThese can be loaded into another database like this (provided the tables exist):psql -c "COPY pgstatviz.conn FROM STDIN CSV HEADER DELIMITER E'\t'" -d <dbname> < conn.tsv