File 3951-system-Update-profiling-section-of-the-eff... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 3951-system-Update-profiling-section-of-the-efficiency-gu.patch of Package erlang

From cba589a49757391520f0a96a3a3cb9f7fc81d07f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20H=C3=B6gberg?= <john@erlang.org>
Date: Thu, 11 May 2023 14:59:28 +0200
Subject: [PATCH] system: Update profiling section of the efficiency guide

---
 erts/emulator/internal_doc/BeamAsm.md     | 48 +++++++++++++++++------
 system/doc/efficiency_guide/profiling.xml | 13 ++++++
 2 files changed, 50 insertions(+), 11 deletions(-)

diff --git a/erts/emulator/internal_doc/BeamAsm.md b/erts/emulator/internal_doc/BeamAsm.md
index 4df4634d2d..8417210be5 100644
--- a/erts/emulator/internal_doc/BeamAsm.md
+++ b/erts/emulator/internal_doc/BeamAsm.md
@@ -302,9 +302,11 @@ The files are:
 
 ## Linux perf support
 
-perf can also be instrumented using BeamAsm symbols to provide more information. As with
-gdb, only the currently executing function will show up in the stack trace, which means
-that perf provides functionality similar to that of [eprof](https://erlang.org/doc/man/eprof.html).
+The JIT can provide symbols to the Linux profiler `perf`, making it possible to
+profile Erlang code with it. Depending on the mode used, `perf` will provide
+functionality similar to [eprof](https://erlang.org/doc/man/eprof.html) or
+[fprof](https://erlang.org/doc/man/fprof.html) but with much lower (and
+configurable) overhead.
 
 You can run perf on BeamAsm like this:
 
@@ -319,9 +321,10 @@ and then look at the results using `perf report` as you normally would with
 perf.
 
 Frame pointers are enabled when the `+JPperf true` option is passed, so you can
-use `perf record --call-graph=fp` to get more context. This will give you
-accurate call graphs for pure Erlang code, but in rare cases it fails to track
-transitions from Erlang to C code and back. [`perf record --call-graph=lbr`](https://lwn.net/Articles/680985/)
+use `perf record --call-graph=fp` to get more context, making the results
+similar to that of `fprof`. This will give you accurate call graphs for pure
+Erlang code, but in rare cases it fails to track transitions from Erlang to C
+code and back. [`perf record --call-graph=lbr`](https://lwn.net/Articles/680985/)
 may work better in those cases, but it's worse at tracking in general.
 
 For example, you can run perf to analyze dialyzer building a PLT like this:
@@ -332,7 +335,8 @@ For example, you can run perf to analyze dialyzer building a PLT like this:
        sasl runtime_tools snmp ssl tftp wx xmerl tools
 
 The above code is run using `+S 1` to make the perf output easier to understand.
-If you then run `perf report -f --no-children` you may get something similar to this:
+If you then run `perf report -f --no-children` you may get something similar to
+this:
 
 ![Linux Perf report: dialyzer PLT build](figures/perf-beamasm.png)
 
@@ -430,6 +434,32 @@ compiler options to tell `perf` where to find the source code.
 > and in `~/.debug/tmp/`. So make sure to cleanup in those directories from time to
 > time or you may run out of inodes.
 
+### Inspecting perf data on another host
+
+Sometimes it's not possible or desirable to inspect a recording on the target
+machine, which gets a bit tricky because `perf report` relies on having all
+symbols available.
+
+To inspect recordings on another machine, you can use the `perf archive`
+command to bundle all the required symbols into an archive. This requires that
+the recording is made with the `-k mono` flag and that it has been processed
+with `perf inject --jit`:
+
+    perf inject --jit -i perf.data -o perf.jitted.data
+    perf archive perf.jitted.data
+
+Once you have the archive, move it together with the processed recording to
+the host you wish to inspect the recording on, and extract the archive to
+`~/.debug`. You can then use `perf report -i perf.jitted.data` as usual.
+
+If you get an error message along the lines of:
+
+   perf: 'archive' is not a perf-command. See 'perf --help'.
+
+Then your `perf` version is too old, and you should use
+[this bash script](https://github.com/torvalds/linux/blob/master/tools/perf/perf-archive.sh)
+instead.
+
 ### perf tips and tricks
 
 You can do a lot of neat things with `perf`. Below is a list of some of the options
@@ -439,10 +469,6 @@ we have found useful:
     Do not include the accumulation of all children in a call.
 * `perf report  --call-graph callee`
     Show the callee rather than the caller when expanding a function call.
-* `perf archive`
-    Create an archive with all the artifacts needed to inspect the data
-    on another host. In early version of perf this command does not work,
-    instead you can use [this bash script](https://github.com/torvalds/linux/blob/master/tools/perf/perf-archive.sh).
 * `perf report` gives "failed to process sample" and/or "failed to process type: 68"
     This probably means that you are running a bugged version of perf. We have
     seen this when running Ubuntu 18.04 with kernel version 4. If you update
diff --git a/system/doc/efficiency_guide/profiling.xml b/system/doc/efficiency_guide/profiling.xml
index 68f5ce1f71..716614464a 100644
--- a/system/doc/efficiency_guide/profiling.xml
+++ b/system/doc/efficiency_guide/profiling.xml
@@ -85,6 +85,19 @@
       is a collection of Erlang profiling and debugging tools.
       This tool comes with an accompanying E-book called
       <url href="https://www.erlang-in-anger.com/">Erlang in Anger</url>.</item>
+      <item>
+        <p><url href="https://perf.wiki.kernel.org/index.php/Main_Page">perf</url>
+          is a sampling profiler for Linux that provides functionality similar
+          to <c>fprof</c> but with much lower overhead. Profiling Erlang code
+          is possible when the emulator has been started with the
+          <c>+JPperf true</c> emulator flag, and is only available when the JIT
+          is enabled.
+        </p>
+        <p>For more details about how to run <c>perf</c> see the
+          <seeguide marker="erts:BeamAsm#linux-perf-support">perf support</seeguide>
+          section in the BeamAsm internal documentation.
+        </p>
+      </item>
     </list>
   </section>
 
-- 
2.35.3

Places

File 3951-system-Update-profiling-section-of-the-efficiency-gu.patch of Package erlang

Places