Package: pgtracer
PGTracerPGTracer is a collection of tools to trace queries, execution plans and more in
PostgreSQL®, using eBPF.OverviewPGTracer offers a way to instrument PostgreSQL, using the Linux eBPF facility.
As it does advanced memory access, it needs the PostgreSQL debug symbols to
resolve symbols and offsets in structs.FeaturesAttach to a running PostgreSQL backend, and dump every executed query along
with it's search pathOptionally turn on instrumentation (just like EXPLAIN ANALYZE does) to gather
more informationPlanned features:Gather information about individual execution nodes to print query plansGather system information and link them to individual nodes (think syscalls,
IO, memory allocation...)Build a TUI to explore the dataAllow to follow a transactionInstallYou will need a running PostgreSQL install, and it's debug symbols.For pgtracer itself you will need:libunwind installed on the systemtheBPF Compiler Collectionseveral python packages as dependencies:psutilpyelftoolsSupport will vary depending on your Linux distribution, kernel version, and
library versions, as well as how PostgreSQL was compiled.Please file a bug if it doesn't work as expected.UbuntuTo install the debug symbols, install thepostgresql-version-dbgsympackage. You may have to enable additional repositories though.To run pgtracer you will need some python packages as well as packages only available from the repos.apt install python3-bpfcc python3-pip libunwind-devThen upgrade pip using pip:pip install pip --upgradeAnd you are now ready to install the pgtracer package itself:git clone https://github.com/aiven/pgtracer.git
cd pgtracer
pip install .FedoraTo install the debugging symbols:yum install dnf-utils
debuginfo-install postgresql-serverFor the dependencies:yum install python3-bcc libunwind  python3-pip libunwind-develThen install pgtracer itself:git clone https://github.com/aiven/pgtracer.git
cd pgtracer
pip install pip --upgrade
pip install .Arch LinuxTo install PostgreSQL debug symbols, as root:pacman -S debuginfod
export DEBUGINFOD_URLS="https://debuginfod.archlinux.org/"
debuginfod-find debuginfo /usr/bin/postgresTo install the required packages:pacman -S python-bcc libunwind python-pipThen install the pgtracer package itself:git clone https://github.com/aiven/pgtracer.git
cd pgtracer
pip install .UsageCurrently, only one script comes with pgtracer:pgtrace_queries.
Since pgtracer uses eBPF, it needs to be run as root.usage: pgtrace_queries [-h] [--instrument [{TIMER,BUFFERS,ROWS,WAL,ALL} ...]] [--nodes-collection] pid

Dump a running backend execution plan

positional arguments:
  pid                   PID to connect to

options:
  -h, --help            show this help message and exit
  --instrument [{TIMER,BUFFERS,ROWS,WAL,ALL} ...], -I [{TIMER,BUFFERS,ROWS,WAL,ALL} ...]
                        Instrument flags to set. (warning: writes into backends memory!)
  --nodes-collection, -n
                        Collect information about individual execution nodesDepending on the way the PostgreSQL binary have been compiled, you may need a
more recent pyelftools version than what is packaged with your distribution:
DWARF5 support is quite recent and continuously improving.Licensepgtracer is licensed under the PostgreSQL license. Full license text is available in theLICENSEfile.Please note that the project explicitly does not require a CLA (Contributor License Agreement) from its contributors.ContactBug reports and patches are very welcome, please post them as GitHub issues and pull requests athttps://github.com/aiven/pgtracer.
To report any possible vulnerabilities or other serious issues please see oursecuritypolicy.TrademarksThe terms Postgres and PostgreSQL are registered trademarks of the PostgreSQL Community Association of Canada.