FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-141004: Document `PyDTrace*` by ZeroIntensity · Pull Request #141856 · python/cpython · GitHub

/ cpython Public

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

Merged
ZeroIntensity merged 4 commits into from
Mar 15, 2026
Conversation 8 Commits 4 Checks 34 Files changed
Merged

gh-141004: Document PyDTrace* #141856

Changes from all commits
Commits
Show all changes
4 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
cec3b18
Merge branch 'main' into document-dtrace
ZeroIntensity Dec 4, 2025
649beb5
Merge branch 'main' into document-dtrace
ZeroIntensity Mar 15, 2026
File filter

Filter by extension

Filter by extension .rst  (1) All 1 file type selected
Viewed files
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Unified
Split
Hide whitespace
Diff view
Unified
Split
Hide whitespace
78 changes: 78 additions & 0 deletions Doc/howto/instrumentation.rst
Show comments
View file
Open in desktop
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
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
Back | FazBrowse Home | New Git URL