Skip to content
A flamegraph generator for Postgres EXPLAIN ANALYZE output.
Go Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
pkg Fix html tests Oct 29, 2019
.gitignore
.go-version Add basic flamegraph generation Oct 22, 2019
.goreleaser.yml
.travis.yml
Dockerfile Add Dockerfile (#4) Nov 6, 2019
LICENSE
README.md Re-add version badge to README Nov 6, 2019
go.mod Add basic flamegraph generation Oct 22, 2019
go.sum
main.go v1.1 Oct 29, 2019

README.md

pg_flame Version Build Status

A flamegraph generator for Postgres EXPLAIN ANALYZE output.

Demo

Try the demo here.

Installation

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.

$ git clone https://github.com/mgartner/pg_flame.git
$ cd pg_flame
$ docker build --tag '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.

You can’t perform that action at this time.