Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mgartner/pg_flame
A flamegraph generator for Postgres EXPLAIN ANALYZE output.
https://github.com/mgartner/pg_flame
database flamegraph performance performance-visualization postgres postgresql postgresql-tool
Last synced: 2 days ago
JSON representation
A flamegraph generator for Postgres EXPLAIN ANALYZE output.
- Host: GitHub
- URL: https://github.com/mgartner/pg_flame
- Owner: mgartner
- License: apache-2.0
- Created: 2019-10-16T22:27:00.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-01-13T23:28:06.000Z (about 5 years ago)
- Last Synced: 2024-10-12T02:46:18.555Z (3 months ago)
- Topics: database, flamegraph, performance, performance-visualization, postgres, postgresql, postgresql-tool
- Language: Go
- Homepage:
- Size: 71.3 KB
- Stars: 1,569
- Watchers: 20
- Forks: 35
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pg_flame [](https://github.com/mgartner/pg_flame/releases) [](https://travis-ci.com/mgartner/pg_flame)
A flamegraph generator for Postgres `EXPLAIN ANALYZE` output.
## Demo
Try the demo [here](https://mgartner.github.io/pg_flame/flamegraph.html).
## 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](https://github.com/mgartner/pg_flame/releases). 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
```bash
$ 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.
```sql
-- query.sql
EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
SELECT id
FROM users
```
Then run the query and save the JSON to a file.
```bash
$ 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](http://www.brendangregg.com/flamegraphs.html) 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](https://blog.tanelpoder.com/posts/visualizing-sql-plan-execution-time-with-flamegraphs/)
and [query
executions](https://externaltable.blogspot.com/2014/05/flame-graphs-for-oracle.html)
, 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`](https://github.com/spiermar/d3-flame-graph) plugin to
generate the flamegraph.