Skip to content

gh-141004: Document PyDTrace* #141856

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

gh-141004: Document PyDTrace* #141856

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43819a9
Document DTrace helpers
ZeroIntensity Nov 22, 2025
6068587
Remove stray change.
ZeroIntensity Nov 22, 2025
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
78 changes: 78 additions & 0 deletions Doc/howto/instrumentation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,6 +341,84 @@ Available static markers
.. versionadded:: 3.8


C Entry Points
^^^^^^^^^^^^^^

To simplify triggering of DTrace markers, Python's C API comes with a number
of helper functions that mirror each static marker. On builds of Python without
DTrace enabled, these do nothing.

In general, it is not necessary to call these yourself, as Python will do
it for you.

.. list-table::
:widths: 50 25 25
:header-rows: 1

* * C API Function
* Static Marker
* Notes
* * .. c:function:: void PyDTrace_LINE(const char *arg0, const char *arg1, int arg2)
* :c:func:`!line`
*
* * .. c:function:: void PyDTrace_FUNCTION_ENTRY(const char *arg0, const char *arg1, int arg2)
* :c:func:`!function__entry`
*
* * .. c:function:: void PyDTrace_FUNCTION_RETURN(const char *arg0, const char *arg1, int arg2)
* :c:func:`!function__return`
*
* * .. c:function:: void PyDTrace_GC_START(int arg0)
* :c:func:`!gc__start`
*
* * .. c:function:: void PyDTrace_GC_DONE(Py_ssize_t arg0)
* :c:func:`!gc__done`
*
* * .. c:function:: void PyDTrace_INSTANCE_NEW_START(int arg0)
* :c:func:`!instance__new__start`
* Not used by Python
* * .. c:function:: void PyDTrace_INSTANCE_NEW_DONE(int arg0)
* :c:func:`!instance__new__done`
* Not used by Python
* * .. c:function:: void PyDTrace_INSTANCE_DELETE_START(int arg0)
* :c:func:`!instance__delete__start`
* Not used by Python
* * .. c:function:: void PyDTrace_INSTANCE_DELETE_DONE(int arg0)
* :c:func:`!instance__delete__done`
* Not used by Python
* * .. c:function:: void PyDTrace_IMPORT_FIND_LOAD_START(const char *arg0)
* :c:func:`!import__find__load__start`
*
* * .. c:function:: void PyDTrace_IMPORT_FIND_LOAD_DONE(const char *arg0, int arg1)
* :c:func:`!import__find__load__done`
*
* * .. c:function:: void PyDTrace_AUDIT(const char *arg0, void *arg1)
* :c:func:`!audit`
*


C Probing Checks
^^^^^^^^^^^^^^^^

.. c:function:: int PyDTrace_LINE_ENABLED(void)
.. c:function:: int PyDTrace_FUNCTION_ENTRY_ENABLED(void)
.. c:function:: int PyDTrace_FUNCTION_RETURN_ENABLED(void)
.. c:function:: int PyDTrace_GC_START_ENABLED(void)
.. c:function:: int PyDTrace_GC_DONE_ENABLED(void)
.. c:function:: int PyDTrace_INSTANCE_NEW_START_ENABLED(void)
.. c:function:: int PyDTrace_INSTANCE_NEW_DONE_ENABLED(void)
.. c:function:: int PyDTrace_INSTANCE_DELETE_START_ENABLED(void)
.. c:function:: int PyDTrace_INSTANCE_DELETE_DONE_ENABLED(void)
.. c:function:: int PyDTrace_IMPORT_FIND_LOAD_START_ENABLED(void)
.. c:function:: int PyDTrace_IMPORT_FIND_LOAD_DONE_ENABLED(void)
.. c:function:: int PyDTrace_AUDIT_ENABLED(void)

All calls to ``PyDTrace`` functions must be guarded by a call to one
of these functions. This allows Python to minimize performance impact
when probing is disabled.

On builds without DTrace enabled, these functions do nothing and return
``0``.

SystemTap Tapsets
-----------------

Expand Down
Loading