Profiler Comparison

docs/conf.py

@@ -15,7 +15,8 @@ author = 'Felix Geisendörfer, Nick Ripley'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx_rtd_theme', 'sphinxemoji.sphinxemoji']
+extensions = ['sphinx_rtd_theme', 'sphinxemoji.sphinxemoji', 'sphinx.ext.autosectionlabel']
+autosectionlabel_prefix_document = True
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

docs/index.rst

@@ -26,10 +26,15 @@ Support this project by giving it a |:star:| on GitHub |ico1|
 
 .. toctree::
    :maxdepth: 1
-   :caption: Profilers
+   :caption: Profiling
 
+   profiling/profiler-comparison
    profiling/cpu-profiler
    profiling/memory-profiler
+   profiling/block-profiler
+   profiling/mutex-profiler
+   profiling/goroutine-profiler
+   profiling/thread-create-profiler
 
 .. toctree::
    :maxdepth: 1

docs/profiling/block-profiler.rst

@@ -0,0 +1,2 @@
+Block Profiler
+==============

docs/profiling/cpu-profiler.rst

@@ -81,8 +81,8 @@ How It Works
 
 The CPU profiler captures this data by asking the operating system to monitor the CPU usage of the application and sends it a ``SIGPROF`` signal for every ``10ms`` of CPU time it consumes. The OS also includes time consumed by the kernel on behalf of the application in this monitoring. Since the signal deliver rate depends on CPU consumption, it’s dynamic and can be up to ``N * 100`` where ``N`` is the number of logical CPU cores on the system and ``100`` is the default sampling rate per CPU second. When a ``SIGPROF`` signal arrives, Go’s signal handler captures a stack trace of the currently active goroutine, and increments the corresponding values in the profile. The ``cpu/nanoseconds`` value is currently directly derived from the sample count, so it is redundant, but convenient.
 
-CPU Profiler Labels
--------------------
+Profiler Labels
+---------------
 
 A cool feature of Go’s CPU profiler is that you can attach arbitrary key value pairs to a goroutine. These labels will be inherited by any goroutine spawned from that goroutine and show up in the resulting profile.
 

docs/profiling/goroutine-profiler.rst

@@ -0,0 +1,2 @@
+Goroutine Profiler
+==================

docs/profiling/index.rst

@@ -1,8 +1,13 @@
-Profilers
+Profiling
 =========
 
 .. toctree::
    :maxdepth: 1
 
+   profiler-comparison
    cpu-profiler
    memory-profiler
+   block-profiler
+   mutex-profiler
+   goroutine-profiler
+   thread-create-profiler

docs/profiling/mutex-profiler.rst

@@ -0,0 +1,2 @@
+Mutex Profiler
+==============

docs/profiling/profiler-comparison.rst

@@ -0,0 +1,47 @@
+Profiler Comparison
+===================
+
+Here is an overview of the profilers built into the Go runtime.
+
+.. list-table::
+   :header-rows: 1
+
+   * -
+     - :doc:`CPU <cpu-profiler>`
+     - :doc:`Memory <memory-profiler>`
+     - :doc:`Block <block-profiler>`
+     - :doc:`Mutex <mutex-profiler>`
+     - :doc:`Goroutine <goroutine-profiler>`
+   * - Production Safety
+     - |:white_check_mark:|
+     - |:white_check_mark:|
+     - |:warning:| [#foot-block]_
+     - |:white_check_mark:|
+     - |:white_check_mark:| [#foot-goroutine]_
+   * - Safe Rate
+     - default
+     - default
+     - |:x:| [#foot-block]_
+     - ``100``
+     - ``1000`` |nbsp| goroutines
+   * - Max Stack Depth
+     - ``64``
+     - ``32``
+     - ``32``
+     - ``32``
+     - ``32`` |nbsp| - |nbsp| ``100`` |nbsp| [#foot-goroutine-api]_
+   * - :ref:`profiling/cpu-profiler:profiler labels`
+     - |:white_check_mark:|
+     - |:x:|
+     - |:x:|
+     - |:x:|
+     - |:white_check_mark:| [#foot-goroutine-api]_
+
+The :doc:`thread-create-profiler` is not listed because it's broken.
+
+.. [#foot-block] The block profiler can cause 5% or more CPU overhead, even when using a high rate value.
+.. [#foot-goroutine] Before Go 1.19, this profile caused O(N) stop-the-world pauses where N is the number of goroutines. Expect ~1-10µsec pause per goroutine.
+.. [#foot-goroutine-api] Depends on API.
+
+.. |nbsp| unicode:: 0xA0 
+   :trim:

docs/profiling/thread-create-profiler.rst

@@ -0,0 +1,6 @@
+ThreadCreate Profiler
+=====================
+
+
+|:lady_beetle:| The threadcreate profile is intended to show stack traces that led to the creation of new OS threads. However, it's been [broken since 2013](https://github.com/golang/go/issues/6104), so you should stay away from it.
+