From 02835ddf951e1a180e8d77df5d5d2b3022ced1d5 Mon Sep 17 00:00:00 2001
From: Benoit Daloze <benoit.daloze@oracle.com>
Date: Thu, 28 Jul 2022 16:12:53 +0200
Subject: [PATCH] [GR-19691] Update documentation about flamegraphs

---
 doc/contributor/profiling.md | 59 +++++-------------------------------
 1 file changed, 8 insertions(+), 51 deletions(-)

diff --git a/doc/contributor/profiling.md b/doc/contributor/profiling.md
index e9e9cc34a03b..2055bfd38f61 100644
--- a/doc/contributor/profiling.md
+++ b/doc/contributor/profiling.md
@@ -13,65 +13,22 @@ the most useful information from the tools, assuming basic knowledge of their us
 
 ### Creating a Flame Graph
 
-#### The Easy Way
-
-The easiest way to generate a flame graph from a profile is to accept the default profiling
-options configured in _jt_. In this case, simply run `jt profile` like you would `jt ruby`
-and your application or inline script will be profiled and an SVG written to your
-TruffleRuby source directory, named _profiles/flamegraph\_\<timestamp\>.svg_.
-
-To make things even easier, `jt profile` will automatically open up the flame graph for
-you in whatever application you have configured as your default for SVG files. This is
-handled by the `open` command on macOS and the `xdg-open` command on Linux.
-
-To illustrate, here's a command for profiling and inline script.
-
-```bash
-jt profile -e "x = 'abc'; 100_000.times { x.upcase }"
-```
-
-Here's a command for profiling the `gem list` command:
-
+Use the [CPUSampler](https://www.graalvm.org/dev/tools/profiling/) ([blog post](https://medium.com/graalvm/where-has-all-my-run-time-gone-245f0ccde853)) in flamegraph mode, like this:
 ```bash
-jt profile -S gem list
+ruby --cpusampler=flamegraph ...
 ```
 
-#### The Less Easy Way
+This will create a `flamegraph.svg`, which you can open in a web browser
+(Chromium-based browsers seem faster for rendering the flamegraph).
 
-The histogram output from the Truffle profiler can be quite large, making it difficult to
-analyze. Additionally, as a flat format it isn't possible to analyze a call graph as that
-information simply isn't encoded in the output. A flame graph shows the entire call graph
-and its structure makes it considerably simpler to see where the application time is being
-spent.
-
-Creating the flame graph is a multi-stage process. First, we need to profile the application
-with the JSON formatter:
 
+There is also `jt profile` which does the same but uses a unique filename, prints the wall-clock time and open the SVG for you:
+Here are some examples:
 ```bash
-jt ruby --cpusampler --cpusampler.Output=json -e 'p :hello' > simple-app.json
-```
-
-The JSON profiler formatter encodes call graph information that isn't available in the
-histogram format. To make a flame graph out of this output, however, we need to transform
-it into a format that folds the call stack samples into single lines. This can be done
-using [stackcollapse-graalvm.rb](https://github.com/eregon/FlameGraph/blob/graalvm/stackcollapse-graalvm.rb)
-from Benoit's fork of FlameGraph.
-
-If you haven't yet, you should clone Benoit's [fork of FlameGraph](https://github.com/eregon/FlameGraph/tree/graalvm)
-into TruffleRuby's parent directory. Now you can run the script to transform the output and
-pipe it into the script that will generate the SVG data:
-
-```bash
-../FlameGraph/stackcollapse-graalvm.rb simple-app.json | ../FlameGraph/flamegraph.pl > simple-app.svg
+jt profile -e "x = 'abc'; 100_000.times { x.upcase }"
+jt profile -S gem list
 ```
 
-At this point, you should open the SVG file in a Chromium-based web browser. Your system
-might have a different image manipulation application configured as the default application
-for SVG files. While loading the file in such an application make render a graph, it likely
-will not handle the interactive components of the flame graph. Firefox may work as well,
-but Chromium-based browsers seem to have better support and performance for the flame graph
-files as of this writing (Dec. 2018).
-
 ### Require Profiling
 The `--metrics-profile-require` option can be used to profile the time used for searching, parsing, translating and loading files during require.