/ Charts

A flamegraph generator for Postgres EXPLAIN ANALYZE output

A flamegraph generator for Postgres EXPLAIN ANALYZE output

pg_flame

A flamegraph generator for Postgres EXPLAIN ANALYZE output.

Installation

Homebrew

You can install via Homebrew with the follow command:

$ brew install mgartner/tap/pg_flame

Download pre-compiled binary

Download one of the compiled binaries in the releases
tab
. Once downloaded, move
pg_flame into your $PATH.

Docker

Alternatively, if you'd like to use Docker to build the program, you can.

$ docker pull mgartner/pg_flame

Build from source

If you'd like to build a binary from the source code, run the following
commands. Note that compiling requires Go version 1.13+.

$ git clone https://github.com/mgartner/pg_flame.git
$ cd pg_flame
$ go build

A pg_flame binary will be created that you can place in your $PATH.

Usage

The pg_flame program reads a JSON query plan from standard input and writes
the flamegraph HTML to standard ouput. Therefore you can pipe and direct input
and output however you desire.

Example: One-step

$ psql dbname -qAtc 'EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT id FROM users' \
    | pg_flame \
    > flamegraph.html \
    && open flamegraph.html

Example: Multi-step with SQL file

Create a SQL file with the EXPLAIN ANALYZE query.

-- query.sql
EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
SELECT id
FROM users

Then run the query and save the JSON to a file.

$ psql dbname -qAtf query.sql > plan.json

Finally, generate the flamegraph HTML.

$ cat plan.json | pg_flame > flamegraph.html

Example: Docker

If you've followed the Docker installation steps above, you can pipe query plan
JSON to a container and save the output HTML.

$ psql dbname -qAtc 'EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT id FROM users' \
    | docker run -i pg_flame \
    > flamegraph.html

Background

Flamegraphs were invented by
Brendan Gregg to visualize CPU consumption per code-path of profiled software.
They are useful visualization tools in many types of performance
investigations. Flamegraphs have been used to visualize Oracle database
query
plans

and query
executions

, proving useful for debugging slow database queries.

Pg_flame is in extension of that work for Postgres query plans. It generates a
visual hierarchy of query plans. This visualization identifies the relative
time of each part of a query plan.

This tool relies on the
spiermar/d3-flame-graph plugin to
generate the flamegraph.

GitHub

Comments