From 04e6661d43a9ad7c548b7fd947144fe0ae524b73 Mon Sep 17 00:00:00 2001
From: Marcus Gartner <marcus@lob.com>
Date: Mon, 21 Oct 2019 19:35:20 -0700
Subject: [PATCH] Document usage and background

---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 7d4cae6..0e2a06b 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,34 @@
 # pg_flame
+
+A flamegraph generator for Postgres `EXPLAIN ANALYZE` output.
+
+## Usage
+
+Generate an annotated query plan in JSON.
+
+```
+psql lob_local -qAtc 'EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT id FROM bears' > plan.json
+```
+
+Generate the flamegraph.
+
+```
+cat plans.json | ./pg_flame > flamegraph.html
+```
+
+Open `flamegraph.html` in a browser of your choice.
+
+## Background
+
+[Flamegraphs](http://www.brendangregg.com/flamegraphs.html) were invented by
+Brendan Gregg to visualize CPU consumption of profiled code-paths of software.
+They are useful visualization tools in many types of performance
+investigations.
+
+Luca Canali has previously shown the benefits of using flamegraph
+visualizations of Oracle query plans for debugging slow database queries.
+Pg_flame is in extension of that work for Postgres.
+
+This tool relies on the
+[`d3-flame-graph`](https://github.com/spiermar/d3-flame-graph) plugin to
+generate the flamegraph.