gh-141004: Document `PyDTrace*` (GH-141856)

diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index b3db1189e5dcbcd5983180e1700f14abb940e27d..06c1ae40da5e67e294be5f143a037bea1049b17d 100644 (file)
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -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
 -----------------