From 23be8282eff8b7524665f1714720b18adc8d9c1e Mon Sep 17 00:00:00 2001
From: Pierre Chambart <pierre.chambart@ocamlpro.com>
Date: Tue, 6 Feb 2018 15:22:07 +0100
Subject: [PATCH] Docs: tutorial about profiling the node

---
 docs/index.rst                     |  3 +-
 docs/introduction/contributing.rst |  2 +-
 docs/tutorials/profiling.rst       | 79 ++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 docs/tutorials/profiling.rst

diff --git a/docs/index.rst b/docs/index.rst
index 7bedcac77..a70e116aa 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -31,13 +31,14 @@ Welcome to Tezos's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Tutorials:
+   :caption: Developer Tutorials:
 
    tutorials/data_encoding
    tutorials/error_monad
    tutorials/michelson_anti_patterns
    tutorials/entering_alpha
    tutorials/protocol_environment
+   tutorials/profiling
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/introduction/contributing.rst b/docs/introduction/contributing.rst
index aacd187bc..ea58020d8 100644
--- a/docs/introduction/contributing.rst
+++ b/docs/introduction/contributing.rst
@@ -42,7 +42,7 @@ documentations for the various parts.
 Our git workflow
 ----------------
 
-First, the repository is http://gitlab.com/tezos/tezos, the github one
+First, the repository is https://gitlab.com/tezos/tezos, the github one
 is just a clone that exists for historical reasons. So if you want to
 contribute, simply create an account there.
 
diff --git a/docs/tutorials/profiling.rst b/docs/tutorials/profiling.rst
new file mode 100644
index 000000000..7a1def54f
--- /dev/null
+++ b/docs/tutorials/profiling.rst
@@ -0,0 +1,79 @@
+Profiling the Tezos node
+========================
+
+Memory profiling the OCaml heap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Install an OCaml switch with the statmemprof patch:
+
+  ``4.04.2+statistical-memprof`` or ``4.06.0+statistical-memprof``
+
+- Install ``statmemprof-emacs``.
+
+- Enable loading statmemprof into the node.
+
+  Add the ``statmemprof-emacs`` package as a dependency to the main package, and add
+  ``let () = Statmemprof_emacs.start 1E-4 30 5`` to the ``node_main.ml`` file.
+
+  Arguments:
+
+  - ``sampling_rate`` is the sampling rate of the profiler. Good value: ``1e-4``.
+  - ``callstack_size`` is the size of the fragment of the call stack which is captured for each sampled allocation.
+  - ``min_sample_print`` is the minimum number of samples under which the location of an allocation is not displayed.
+
+- Load sturgeon into emacs, by adding this to your ``.emacs``:
+
+::
+
+    (let ((opam-share (ignore-errors (car (process-lines "opam" "config" "var" "share")))))
+     (when (and opam-share (file-directory-p opam-share))
+      (add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share))))
+
+    (require 'sturgeon)
+
+- Launch the node then connect to it with sturgeon.
+
+  If the process is launched with pid ``1234`` then
+
+::
+
+    M-x sturgeon-connect
+    tezos-nodememprof.1234.sturgeon
+
+  (tab-completion works for finding the socket name)
+
+Memory profiling the C heap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Install ``valgrind`` and ``massif-visualizer``
+
+::
+
+    valgrind --tool=massif tezos-node run ...
+
+- Stop with `Ctrl-C` then display with
+
+::
+
+    massif-visualizer massif.out.pid
+
+
+Performance profiling
+~~~~~~~~~~~~~~~~~~~~~
+
+- Install perf (The ``linux-perf`` package for debian.
+
+  If the package does not exist for your current kernel, a previous
+  version can be used. substitute the ``perf`` command to ``perf_4.9``
+  if your kernel is 4.9).
+
+- Run the node, find the pid.
+
+- Attach perf with ``perf record -p pid --call-stack dwarf``.
+
+  Then stop capturing with ``Ctrl-C``. This can represent a lot of
+  data. Don't do that for too long. If this is too much you can remove
+  the ``--call-stack dwarf`` to get something more manageable, but
+  interpreting the information can be harder.
+
+- display the result with ``perf report``