Skip to content

gh-96143: Improve perf profiler docs #96445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pablogsal merged 11 commits into from
Oct 27, 2022
Merged

gh-96143: Improve perf profiler docs #96445

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
41bab32
gh-96143: Improve perf profiler docs
erlend-aasland Aug 29, 2022
574b39a
you => your
Aug 30, 2022
9388964
Fixup What's New entry
Aug 30, 2022
31c0eb8
Address review: add links to perf wiki, and use bullet points
erlend-aasland Aug 30, 2022
9c72023
Address Victor's review
erlend-aasland Aug 31, 2022
3756252
https
gpshead Aug 31, 2022
cbe8b16
Address reviews
erlend-aasland Sep 4, 2022
9ce60ea
Merge branch 'main' into perf-docs
erlend-aasland Sep 4, 2022
db4aaa2
Apply suggestions from code review
Oct 4, 2022
d68c77e
Merge branch 'main' into perf-docs
erlend-aasland Oct 4, 2022
0d41b95
Merge branch 'main' into perf-docs
erlend-aasland Oct 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Address Victor's review
  • Loading branch information
@erlend-aasland
erlend-aasland committed Aug 31, 2022
commit 9c720233f0c61a748276efbac295702627edfdf3
12 changes: 6 additions & 6 deletions Doc/howto/perf_profiling.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ As you can see here, the Python functions are not shown in the output, only ``_P
functions use the same C function to evaluate bytecode so we cannot know which Python function corresponds to which
bytecode-evaluating function.

Instead, if we run the same experiment with ``perf`` support activated we get:
Instead, if we run the same experiment with ``perf`` support enabled we get:

.. code-block:: shell-session

Expand Down Expand Up @@ -148,10 +148,10 @@ Instead, if we run the same experiment with ``perf`` support activated we get:



How to enable the ``perf`` profiling mode
-----------------------------------------
How to enable ``perf`` profiling support
----------------------------------------

There are three ways to activate the ``perf`` profiling mode:
There are three ways to enable ``perf`` profiling support:

* using the :option:`-Xperf <-X>` command-line option
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
* using the :envvar:`PYTHONPERFSUPPORT` environment variable
Expand All @@ -163,11 +163,11 @@ use the :option:`-Xperf <-X>` option::

$ python -Xperf my_script.py

If you need to activate the ``perf`` profiling mode globally,
If you need to enable ``perf`` profiling support globally,
set the environment variable :envvar:`PYTHONPERFSUPPORT`
to a nonzero value.

If you need to dynamically activate and deactivate the ``perf`` profiling mode
If you need to dynamically enable and disable ``perf`` profiling
in response to a signal or other communication mechanisms with your process,
use the :func:`sys.activate_stack_trampoline` and
:func:`sys.deactivate_stack_trampoline` APIs:
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
Comment thread
erlend-aasland marked this conversation as resolved.
Outdated
Expand Down
19 changes: 8 additions & 11 deletions Doc/using/cmdline.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -535,13 +535,11 @@ Miscellaneous options
development (running from the source tree) then the default is "off".
Note that the "importlib_bootstrap" and "importlib_bootstrap_external"
frozen modules are always used, even if this flag is set to "off".
* ``-X perf`` activates compatibility mode with the ``perf`` profiler.
When this option is activated, the Linux ``perf`` profiler will be able to
* ``-X perf`` enables support for the Linux ``perf`` profiler.
When this option is provided, the ``perf`` profiler will be able to
report Python calls. This option is only available on some platforms and
will do nothing if is not supported on the current system. The default value
is "off". See :ref:`perf_profiling` for more details.
This option is equivalent to setting the environment variable
:envvar:`PYTHONPERFSUPPORT` to ``1``.
is "off". See also :envvar:`PYTHONPERFSUPPORT` and :ref:`perf_profiling`.

It also allows passing arbitrary values and retrieving them through the
:data:`sys._xoptions` dictionary.
Expand Down Expand Up @@ -1036,14 +1034,13 @@ conflict.

.. envvar:: PYTHONPERFSUPPORT

If this variable is set to a nonzero value, it activates compatibility mode
with the ``perf`` profiler so Python calls can be detected by it.
This is exactly equivalent to setting :option:`-X perf <-X>`
on the command line.
If this variable is set to a nonzero value, it enables support for
the Linux ``perf`` profiler so Python calls can be detected by it.

If set to ``0``, disable ``perf`` profiler support.
If set to ``0``, disable Linux ``perf`` profiler support.

See :ref:`perf_profiling` for more details.
See also the :option:`-X perf <-X>` command-line option
and :ref:`perf_profiling`.

.. versionadded:: 3.12

Expand Down