diff --git a/docs/conf.py b/docs/conf.py index 9117f20..83755d7 100644 --- a/docs/conf.py +++ b/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'] diff --git a/docs/index.rst b/docs/index.rst index 776aae4..e551798 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/profiling/block-profiler.rst b/docs/profiling/block-profiler.rst new file mode 100644 index 0000000..76e4522 --- /dev/null +++ b/docs/profiling/block-profiler.rst @@ -0,0 +1,2 @@ +Block Profiler +============== diff --git a/docs/profiling/cpu-profiler.rst b/docs/profiling/cpu-profiler.rst index 0194aba..8d7689b 100644 --- a/docs/profiling/cpu-profiler.rst +++ b/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. diff --git a/docs/profiling/goroutine-profiler.rst b/docs/profiling/goroutine-profiler.rst new file mode 100644 index 0000000..26ee26f --- /dev/null +++ b/docs/profiling/goroutine-profiler.rst @@ -0,0 +1,2 @@ +Goroutine Profiler +================== diff --git a/docs/profiling/index.rst b/docs/profiling/index.rst index bb72d78..f7a83c4 100644 --- a/docs/profiling/index.rst +++ b/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 diff --git a/docs/profiling/mutex-profiler.rst b/docs/profiling/mutex-profiler.rst new file mode 100644 index 0000000..1459c58 --- /dev/null +++ b/docs/profiling/mutex-profiler.rst @@ -0,0 +1,2 @@ +Mutex Profiler +============== diff --git a/docs/profiling/profiler-comparison.rst b/docs/profiling/profiler-comparison.rst new file mode 100644 index 0000000..e4a4095 --- /dev/null +++ b/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 ` + - :doc:`Memory ` + - :doc:`Block ` + - :doc:`Mutex ` + - :doc:`Goroutine ` + * - 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: diff --git a/docs/profiling/thread-create-profiler.rst b/docs/profiling/thread-create-profiler.rst new file mode 100644 index 0000000..186a3d4 --- /dev/null +++ b/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. +