Exceptions

Author: pablogsal

Doc/library/profiling.sampling.rst

@@ -426,9 +426,10 @@ which you can use to judge whether the data is sufficient for your analysis.
 Profiling modes
 ===============
 
-The sampling profiler supports three modes that control which samples are
+The sampling profiler supports five modes that control which samples are
 recorded. The mode determines what the profile measures: total elapsed time,
-CPU execution time, or time spent holding the global interpreter lock.
+CPU execution time, time spent holding the global interpreter lock, exception
+handling, or critical section activity.
 
 
 Wall-clock mode
@@ -509,6 +510,85 @@ single-threaded programs to distinguish Python execution time from time spent
 in C extensions or I/O.
 
 
+Exception mode
+--------------
+
+Exception mode (``--mode=exception``) records samples only when a thread has
+an active exception::
+
+   python -m profiling.sampling run --mode=exception script.py
+
+Samples are recorded when a thread is either propagating an exception (between
+``raise`` and being caught) or executing inside an ``except`` block where
+exception information is present.
+
+The following example illustrates which code regions are captured:
+
+.. code-block:: python
+
+   def example():
+       try:
+           raise ValueError("error")    # Captured: exception being raised
+       except ValueError:
+           process_error()              # Captured: inside except block
+       finally:
+           cleanup()                    # NOT captured: exception already handled
+
+   def example_propagating():
+       try:
+           try:
+               raise ValueError("error")
+           finally:
+               cleanup()                # Captured: exception propagating through
+       except ValueError:
+           pass
+
+   def example_no_exception():
+       try:
+           do_work()
+       finally:
+           cleanup()                    # NOT captured: no exception involved
+
+Note that ``finally`` blocks are only captured when an exception is actively
+propagating through them. A ``finally`` block that runs after an ``except``
+block has handled the exception, or during normal execution without any
+exception, is not captured.
+
+This mode is useful for understanding where your program spends time handling
+errors, which can be significant in code paths that use exceptions for flow
+control or in applications that process many error conditions.
+
+Exception mode helps answer questions like "how much time is spent handling
+exceptions?" and "which exception handlers are the most expensive?" It can
+reveal hidden performance costs in code that catches and processes many
+exceptions, even when those exceptions are handled gracefully.
+
+
+Critical section mode
+---------------------
+
+Critical section mode (``--mode=critical``) records samples only when a thread
+is executing inside a critical section::
+
+   python -m profiling.sampling run --mode=critical script.py
+
+Critical sections are regions of code protected by internal interpreter locks.
+This mode is primarily useful on free-threaded Python builds (built with
+``--disable-gil``) where critical sections replace the GIL for fine-grained
+locking.
+
+On standard Python builds with the GIL, critical section mode captures samples
+when threads hold internal locks used by the interpreter for thread-safe
+operations. While less commonly needed than other modes, it can help diagnose
+lock contention issues in multi-threaded code.
+
+Critical section mode helps answer questions like "which code paths trigger
+critical section acquisition?" and "where is lock contention occurring?" This
+is particularly valuable when debugging performance issues in free-threaded
+Python programs where multiple threads may contend for the same critical
+sections.
+
+
 Output formats
 ==============
 
@@ -945,8 +1025,9 @@ Mode options
 
 .. option:: --mode <mode>
 
-   Sampling mode: ``wall`` (default), ``cpu``, or ``gil``.
-   The ``cpu`` and ``gil`` modes are incompatible with ``--async-aware``.
+   Sampling mode: ``wall`` (default), ``cpu``, ``gil``, ``exception``, or
+   ``critical``. The ``cpu``, ``gil``, ``exception``, and ``critical`` modes
+   are incompatible with ``--async-aware``.
 
 .. option:: --async-mode <mode>
 

Doc/sphinx-warnings.txt

@@ -110,8 +110,18 @@ typedef struct _Py_DebugOffsets {
         uint64_t status;
         uint64_t holds_gil;
         uint64_t gil_requested;
+        uint64_t current_exception;
+        uint64_t exc_info;
+        uint64_t critical_section;
     } thread_state;
 
+    // Exception stack item offset;
+    struct {
+        uint64_t size;
+        uint64_t exc_value;
+        uint64_t previous_item;
+    } err_stackitem;
+
     // InterpreterFrame offset;
     struct _interpreter_frame {
         uint64_t size;
@@ -282,6 +292,14 @@ typedef struct _Py_DebugOffsets {
         .status = offsetof(PyThreadState, _status), \
         .holds_gil = offsetof(PyThreadState, holds_gil), \
         .gil_requested = offsetof(PyThreadState, gil_requested), \
+        .current_exception = offsetof(PyThreadState, current_exception), \
+        .exc_info = offsetof(PyThreadState, exc_info), \
+        .critical_section = offsetof(PyThreadState, critical_section), \
+    }, \
+    .err_stackitem = { \
+        .size = sizeof(_PyErr_StackItem), \
+        .exc_value = offsetof(_PyErr_StackItem, exc_value), \
+        .previous_item = offsetof(_PyErr_StackItem, previous_item), \
     }, \
     .interpreter_frame = { \
         .size = sizeof(_PyInterpreterFrame), \

Include/internal/pycore_debug_offsets.h

@@ -505,6 +505,8 @@ body.resizing-sidebar {
 .stat-tile--red    { --tile-color: 220, 53, 69; --tile-text: #dc3545; }
 .stat-tile--yellow { --tile-color: 255, 193, 7; --tile-text: #d39e00; }
 .stat-tile--purple { --tile-color: 111, 66, 193; --tile-text: #6f42c1; }
+.stat-tile--orange { --tile-color: 253, 126, 20; --tile-text: #fd7e14; }
+.stat-tile--cyan   { --tile-color: 23, 162, 184; --tile-text: #17a2b8; }
 
 .stat-tile[class*="--"] {
   border-color: rgba(var(--tile-color), 0.4);

Lib/profiling/sampling/_flamegraph_assets/flamegraph.css

@@ -643,6 +643,18 @@ function populateThreadStats(data, selectedThreadId = null) {
 
   const gcPctElem = document.getElementById('gc-pct');
   if (gcPctElem) gcPctElem.textContent = `${(threadStats.gc_pct || 0).toFixed(1)}%`;
+
+  // Exception stats
+  const excPctElem = document.getElementById('exc-pct');
+  if (excPctElem) excPctElem.textContent = `${(threadStats.has_exception_pct || 0).toFixed(1)}%`;
+
+  // Critical section stats (only shown for free-threaded builds)
+  const critStat = document.getElementById('crit-stat');
+  const critPctElem = document.getElementById('crit-pct');
+  if (critStat && critPctElem && threadStats.free_threaded) {
+    critStat.style.display = 'block';
+    critPctElem.textContent = `${(threadStats.in_critical_section_pct || 0).toFixed(1)}%`;
+  }
 }
 
 // ============================================================================

Lib/profiling/sampling/_flamegraph_assets/flamegraph.js

@@ -161,6 +161,14 @@ <h3 class="section-title">Runtime Stats</h3>
                     <div class="stat-tile-value" id="gc-pct">--</div>
                     <div class="stat-tile-label">GC</div>
                   </div>
+                  <div class="stat-tile stat-tile--orange" id="exc-stat">
+                    <div class="stat-tile-value" id="exc-pct">--</div>
+                    <div class="stat-tile-label">Exception</div>
+                  </div>
+                  <div class="stat-tile stat-tile--cyan" id="crit-stat" style="display: none;">
+                    <div class="stat-tile-value" id="crit-pct">--</div>
+                    <div class="stat-tile-label">Critical Sect</div>
+                  </div>
                 </div>
               </div>
             </section>

Lib/profiling/sampling/_flamegraph_assets/flamegraph_template.html

@@ -16,6 +16,8 @@
     PROFILING_MODE_WALL,
     PROFILING_MODE_CPU,
     PROFILING_MODE_GIL,
+    PROFILING_MODE_EXCEPTION,
+    PROFILING_MODE_CRITICAL_SECTION,
     SORT_MODE_NSAMPLES,
     SORT_MODE_TOTTIME,
     SORT_MODE_CUMTIME,
@@ -90,6 +92,8 @@ def _parse_mode(mode_string):
         "wall": PROFILING_MODE_WALL,
         "cpu": PROFILING_MODE_CPU,
         "gil": PROFILING_MODE_GIL,
+        "exception": PROFILING_MODE_EXCEPTION,
+        "critical": PROFILING_MODE_CRITICAL_SECTION,
     }
     return mode_map[mode_string]
 
@@ -207,10 +211,13 @@ def _add_mode_options(parser):
     mode_group = parser.add_argument_group("Mode options")
     mode_group.add_argument(
         "--mode",
-        choices=["wall", "cpu", "gil"],
+        choices=["wall", "cpu", "gil", "exception", "critical"],
         default="wall",
         help="Sampling mode: wall (all samples), cpu (only samples when thread is on CPU), "
-        "gil (only samples when thread holds the GIL). Incompatible with --async-aware",
+        "gil (only samples when thread holds the GIL), "
+        "exception (only samples when thread has an active exception), "
+        "critical (only samples when thread is in a critical section). "
+        "Incompatible with --async-aware",
     )
     mode_group.add_argument(
         "--async-mode",

Lib/profiling/sampling/cli.py

@@ -4,6 +4,8 @@
     THREAD_STATUS_ON_CPU,
     THREAD_STATUS_GIL_REQUESTED,
     THREAD_STATUS_UNKNOWN,
+    THREAD_STATUS_HAS_EXCEPTION,
+    THREAD_STATUS_IN_CRITICAL_SECTION,
 )
 
 try:
@@ -141,7 +143,7 @@ def _collect_thread_status_stats(self, stack_frames):
 
         Returns:
             tuple: (aggregate_status_counts, has_gc_frame, per_thread_stats)
-                - aggregate_status_counts: dict with has_gil, on_cpu, etc.
+                - aggregate_status_counts: dict with has_gil, on_cpu, has_exception, etc.
                 - has_gc_frame: bool indicating if any thread has GC frames
                 - per_thread_stats: dict mapping thread_id to per-thread counts
         """
@@ -150,6 +152,8 @@ def _collect_thread_status_stats(self, stack_frames):
             "on_cpu": 0,
             "gil_requested": 0,
             "unknown": 0,
+            "has_exception": 0,
+            "in_critical_section": 0,
             "total": 0,
         }
         has_gc_frame = False
@@ -171,6 +175,10 @@ def _collect_thread_status_stats(self, stack_frames):
                     status_counts["gil_requested"] += 1
                 if status_flags & THREAD_STATUS_UNKNOWN:
                     status_counts["unknown"] += 1
+                if status_flags & THREAD_STATUS_HAS_EXCEPTION:
+                    status_counts["has_exception"] += 1
+                if status_flags & THREAD_STATUS_IN_CRITICAL_SECTION:
+                    status_counts["in_critical_section"] += 1
 
                 # Track per-thread statistics
                 thread_id = getattr(thread_info, "thread_id", None)
@@ -181,6 +189,8 @@ def _collect_thread_status_stats(self, stack_frames):
                             "on_cpu": 0,
                             "gil_requested": 0,
                             "unknown": 0,
+                            "has_exception": 0,
+                            "in_critical_section": 0,
                             "total": 0,
                             "gc_samples": 0,
                         }
@@ -196,6 +206,10 @@ def _collect_thread_status_stats(self, stack_frames):
                         thread_stats["gil_requested"] += 1
                     if status_flags & THREAD_STATUS_UNKNOWN:
                         thread_stats["unknown"] += 1
+                    if status_flags & THREAD_STATUS_HAS_EXCEPTION:
+                        thread_stats["has_exception"] += 1
+                    if status_flags & THREAD_STATUS_IN_CRITICAL_SECTION:
+                        thread_stats["in_critical_section"] += 1
 
                     # Check for GC frames in this thread
                     frames = getattr(thread_info, "frame_info", None)

Lib/profiling/sampling/collector.py

@@ -5,6 +5,8 @@
 PROFILING_MODE_CPU = 1
 PROFILING_MODE_GIL = 2
 PROFILING_MODE_ALL = 3  # Combines GIL + CPU checks
+PROFILING_MODE_EXCEPTION = 4  # Only samples when thread has an active exception
+PROFILING_MODE_CRITICAL_SECTION = 5  # Only samples when thread is in a critical section
 
 # Sort mode constants
 SORT_MODE_NSAMPLES = 0
@@ -21,10 +23,14 @@
         THREAD_STATUS_ON_CPU,
         THREAD_STATUS_UNKNOWN,
         THREAD_STATUS_GIL_REQUESTED,
+        THREAD_STATUS_HAS_EXCEPTION,
+        THREAD_STATUS_IN_CRITICAL_SECTION,
     )
 except ImportError:
     # Fallback for tests or when module is not available
     THREAD_STATUS_HAS_GIL = (1 << 0)
     THREAD_STATUS_ON_CPU = (1 << 1)
     THREAD_STATUS_UNKNOWN = (1 << 2)
     THREAD_STATUS_GIL_REQUESTED = (1 << 3)
+    THREAD_STATUS_HAS_EXCEPTION = (1 << 4)
+    THREAD_STATUS_IN_CRITICAL_SECTION = (1 << 5)

Lib/profiling/sampling/constants.py

@@ -8,13 +8,15 @@
 
 from .collector import Collector
 try:
-    from _remote_debugging import THREAD_STATUS_HAS_GIL, THREAD_STATUS_ON_CPU, THREAD_STATUS_UNKNOWN, THREAD_STATUS_GIL_REQUESTED
+    from _remote_debugging import THREAD_STATUS_HAS_GIL, THREAD_STATUS_ON_CPU, THREAD_STATUS_UNKNOWN, THREAD_STATUS_GIL_REQUESTED, THREAD_STATUS_HAS_EXCEPTION, THREAD_STATUS_IN_CRITICAL_SECTION
 except ImportError:
     # Fallback if module not available (shouldn't happen in normal use)
     THREAD_STATUS_HAS_GIL = (1 << 0)
     THREAD_STATUS_ON_CPU = (1 << 1)
     THREAD_STATUS_UNKNOWN = (1 << 2)
     THREAD_STATUS_GIL_REQUESTED = (1 << 3)
+    THREAD_STATUS_HAS_EXCEPTION = (1 << 4)
+    THREAD_STATUS_IN_CRITICAL_SECTION = (1 << 5)
 
 
 # Categories matching Firefox Profiler expectations
@@ -26,6 +28,8 @@
     {"name": "GIL", "color": "green", "subcategories": ["Other"]},
     {"name": "CPU", "color": "purple", "subcategories": ["Other"]},
     {"name": "Code Type", "color": "red", "subcategories": ["Other"]},
+    {"name": "Exception", "color": "magenta", "subcategories": ["Other"]},
+    {"name": "Critical Section", "color": "lightblue", "subcategories": ["Other"]},
 ]
 
 # Category indices
@@ -36,6 +40,8 @@
 CATEGORY_GIL = 4
 CATEGORY_CPU = 5
 CATEGORY_CODE_TYPE = 6
+CATEGORY_EXCEPTION = 7
+CATEGORY_CRITICAL_SECTION = 8
 
 # Subcategory indices
 DEFAULT_SUBCATEGORY = 0
@@ -84,6 +90,10 @@ def __init__(self, sample_interval_usec, *, skip_idle=False):
         self.python_code_start = {}       # Thread running Python code (has GIL)
         self.native_code_start = {}       # Thread running native code (on CPU without GIL)
         self.gil_wait_start = {}          # Thread waiting for GIL
+        self.exception_start = {}         # Thread has an exception set
+        self.no_exception_start = {}      # Thread has no exception set
+        self.critical_section_start = {}  # Thread is in critical section (free-threaded)
+        self.no_critical_section_start = {}  # Thread is not in critical section
 
         # GC event tracking: track GC start time per thread
         self.gc_start_per_thread = {}  # tid -> start_time
@@ -197,6 +207,21 @@ def collect(self, stack_frames):
                     self._add_marker(tid, "Waiting for GIL", self.gil_wait_start.pop(tid),
                                    current_time, CATEGORY_GIL)
 
+                # Track exception state (Has Exception / No Exception)
+                has_exception = bool(status_flags & THREAD_STATUS_HAS_EXCEPTION)
+                self._track_state_transition(
+                    tid, has_exception, self.exception_start, self.no_exception_start,
+                    "Has Exception", "No Exception", CATEGORY_EXCEPTION, current_time
+                )
+
+                # Track critical section state (In Critical Section / Not In Critical Section)
+                # This is mainly relevant for free-threaded Python builds
+                in_critical_section = bool(status_flags & THREAD_STATUS_IN_CRITICAL_SECTION)
+                self._track_state_transition(
+                    tid, in_critical_section, self.critical_section_start, self.no_critical_section_start,
+                    "In Critical Section", "Not In Critical Section", CATEGORY_CRITICAL_SECTION, current_time
+                )
+
                 # Track GC events by detecting <GC> frames in the stack trace
                 # This leverages the improved GC frame tracking from commit 336366fd7ca
                 # which precisely identifies the thread that initiated GC collection
@@ -551,6 +576,10 @@ def _finalize_markers(self):
             (self.native_code_start, "Native Code", CATEGORY_CODE_TYPE),
             (self.gil_wait_start, "Waiting for GIL", CATEGORY_GIL),
             (self.gc_start_per_thread, "GC Collecting", CATEGORY_GC),
+            (self.exception_start, "Has Exception", CATEGORY_EXCEPTION),
+            (self.no_exception_start, "No Exception", CATEGORY_EXCEPTION),
+            (self.critical_section_start, "In Critical Section", CATEGORY_CRITICAL_SECTION),
+            (self.no_critical_section_start, "Not In Critical Section", CATEGORY_CRITICAL_SECTION),
         ]
 
         for state_dict, marker_name, category in marker_states: