mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Issue #21590: Merge from 3.6

Browse source
This commit is contained in:
Berker Peksag 2016-11-06 21:45:45 +03:00
commit 5fce4b464a
1 changed files with 23 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

49
Doc/howto/instrumentation.rst
View file

@ -1,3 +1,5 @@
.. highlight:: shell-session
.. _instrumentation: .. _instrumentation:
=============================================== ===============================================
@ -20,9 +22,6 @@ known as "probes", that can be observed by a DTrace or SystemTap script,
making it easier to monitor what the CPython processes on a system are making it easier to monitor what the CPython processes on a system are
doing. doing.
.. I'm using ".. code-block:: c" for SystemTap scripts, as "c" is syntactically
the closest match that Sphinx supports
.. impl-detail:: .. impl-detail::
DTrace markers are implementation details of the CPython interpreter. DTrace markers are implementation details of the CPython interpreter.
@ -40,14 +39,16 @@ development tools must be installed.
On a Linux machine, this can be done via:: On a Linux machine, this can be done via::
yum install systemtap-sdt-devel $ yum install systemtap-sdt-devel
or:: or::
sudo apt-get install systemtap-sdt-dev $ sudo apt-get install systemtap-sdt-dev
CPython must then be configured `--with-dtrace`:: CPython must then be configured ``--with-dtrace``:
.. code-block:: none
checking for --with-dtrace... yes checking for --with-dtrace... yes
@ -71,22 +72,18 @@ Python provider::
On Linux, you can verify if the SystemTap static markers are present in On Linux, you can verify if the SystemTap static markers are present in
the built binary by seeing if it contains a ".note.stapsdt" section. the built binary by seeing if it contains a ".note.stapsdt" section.
.. code-block:: bash ::
$ readelf -S ./python | grep .note.stapsdt $ readelf -S ./python | grep .note.stapsdt
[30] .note.stapsdt NOTE 0000000000000000 00308d78 [30] .note.stapsdt NOTE 0000000000000000 00308d78
If you've built Python as a shared library (with --enable-shared), you If you've built Python as a shared library (with --enable-shared), you
need to look instead within the shared library. For example: need to look instead within the shared library. For example::
.. code-block:: bash
$ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt $ readelf -S libpython3.3dm.so.1.0 | grep .note.stapsdt
[29] .note.stapsdt NOTE 0000000000000000 00365b68 [29] .note.stapsdt NOTE 0000000000000000 00365b68
Sufficiently modern readelf can print the metadata: Sufficiently modern readelf can print the metadata::
.. code-block:: bash
$ readelf -n ./python $ readelf -n ./python
@ -136,7 +133,7 @@ hierarchy of a Python script, only tracing within the invocation of
a function called "start". In other words, import-time function a function called "start". In other words, import-time function
invocations are not going to be listed: invocations are not going to be listed:
.. code-block:: c .. code-block:: none
self int indent; self int indent;
@ -170,13 +167,13 @@ invocations are not going to be listed:
self->trace = 0; self->trace = 0;
} }
It can be invoked like this: It can be invoked like this::
.. code-block:: bash
$ sudo dtrace -q -s call_stack.d -c "python3.6 script.py" $ sudo dtrace -q -s call_stack.d -c "python3.6 script.py"
The output looks like this:: The output looks like this:
.. code-block:: none
156641360502280 function-entry:call_stack.py:start:23 156641360502280 function-entry:call_stack.py:start:23
156641360518804 function-entry: call_stack.py:function_1:1 156641360518804 function-entry: call_stack.py:function_1:1
@ -208,7 +205,7 @@ containing them.
For example, this SystemTap script can be used to show the call/return For example, this SystemTap script can be used to show the call/return
hierarchy of a Python script: hierarchy of a Python script:
.. code-block:: c .. code-block:: none
probe process("python").mark("function__entry") { probe process("python").mark("function__entry") {
filename = user_string($arg1); filename = user_string($arg1);
@ -228,15 +225,15 @@ hierarchy of a Python script:
thread_indent(-1), funcname, filename, lineno); thread_indent(-1), funcname, filename, lineno);
} }
It can be invoked like this: It can be invoked like this::
.. code-block:: bash
$ stap \ $ stap \
show-call-hierarchy.stp \ show-call-hierarchy.stp \
-c "./python test.py" -c "./python test.py"
The output looks like this:: The output looks like this:
.. code-block:: none
11408 python(8274): => __contains__ in Lib/_abcoll.py:362 11408 python(8274): => __contains__ in Lib/_abcoll.py:362
11414 python(8274): => __getitem__ in Lib/os.py:425 11414 python(8274): => __getitem__ in Lib/os.py:425
@ -325,7 +322,7 @@ details of the static markers.
Here is a tapset file, based on a non-shared build of CPython: Here is a tapset file, based on a non-shared build of CPython:
.. code-block:: c .. code-block:: none
/* /*
Provide a higher-level wrapping around the function__entry and Provide a higher-level wrapping around the function__entry and
@ -369,7 +366,7 @@ This SystemTap script uses the tapset above to more cleanly implement the
example given above of tracing the Python function-call hierarchy, without example given above of tracing the Python function-call hierarchy, without
needing to directly name the static markers: needing to directly name the static markers:
.. code-block:: c .. code-block:: none
probe python.function.entry probe python.function.entry
{ {
@ -388,7 +385,7 @@ The following script uses the tapset above to provide a top-like view of all
running CPython code, showing the top 20 most frequently-entered bytecode running CPython code, showing the top 20 most frequently-entered bytecode
frames, each second, across the whole system: frames, each second, across the whole system:
.. code-block:: c .. code-block:: none
global fn_calls; global fn_calls;