Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

PEP 829: Add timestamps to exceptions and tracebacks#4592

Draft
gpshead wants to merge 12 commits intopython:mainfrom
gpshead:pep-exception-timestamps
Draft

PEP 829: Add timestamps to exceptions and tracebacks#4592
gpshead wants to merge 12 commits intopython:mainfrom
gpshead:pep-exception-timestamps

Conversation

@gpshead
Copy link
Member

@gpshead gpshead commented Sep 17, 2025 •
edited
Loading

This PEP adds an optional __timestamp_ns__ attribute to BaseException that records when the exception was instantiated. When enabled via PYTHON_TRACEBACK_TIMESTAMPS or -X traceback_timestamps, formatted tracebacks display the timestamp alongside the exception message.

This feature was presented and discussed at the September 2025 Core Team sprint in Cambridge, UK. The reference implementation is CPython PR #129337.

Basic requirements (all PEP Types)

  • Read and followed PEP 1 & PEP 12
  • File created from the latest PEP template
  • PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
  • Title clearly, accurately and concisely describes the content in 79 characters or less
  • Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
  • Author, Status (Draft), Type and Created headers filled out correctly
  • PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
  • Required sections included
    • Abstract (first section)
    • Copyright (last section; exact wording from template required)
  • Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
  • PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
  • Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

  • PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
  • Suggested sections included (unless not applicable)
    • Motivation
    • Specification
    • Rationale
    • Backwards Compatibility
    • Security Implications
    • How to Teach This
    • Reference Implementation
    • Rejected Ideas
    • Open Issues
    • Acknowledgements
    • Footnotes
    • Change History
  • Python-Version set to valid (pre-beta) future Python version, if relevant
  • Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
  • Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

📚 Documentation preview 📚: https://pep-previews--4592.org.readthedocs.build/

@gpshead @claude
PEP-8XX: Add timestamps to exception tracebacks
aa4f6dc 
This draft PEP proposes adding optional timestamps to Python exception
objects that can be displayed in tracebacks. Based on CPython PR #129337
by Gregory P. Smith.

The feature adds a __timestamp_ns__ attribute to BaseException and allows
configuration via environment variables or command-line options. This is
particularly useful for debugging async applications with exception groups
and distributed systems.

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@AA-Turner AA-Turner changed the title PEP-8XX: Add timestamps to exception tracebacks PEP 8XX: Add timestamps to exception tracebacks Sep 17, 2025
@AA-Turner AA-Turner changed the title PEP 8XX: Add timestamps to exception tracebacks PEP 9999: Add timestamps to exception tracebacks Sep 17, 2025
@gpshead @claude
Add open issues about timestamp collection and control flow exceptions
5a25936 
Added two important open issues to the PEP:

1. Whether to always collect timestamps unconditionally (performance
   testing shows it's cheap) and the implications for pickle size and
   cross-version compatibility testing

2. Configuration of control flow exception exclusions (StopIteration,
   AsyncStopIteration) and whether subclasses should be included, noting
   the performance constraints of the hot path

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@gpshead gpshead changed the title PEP 9999: Add timestamps to exception tracebacks PEP 8XX: Add timestamps to exception tracebacks Sep 17, 2025
@gpshead gpshead changed the title PEP 8XX: Add timestamps to exception tracebacks PEP 9999: Add timestamps to exception tracebacks Sep 17, 2025
gpshead and others added 2 commits September 18, 2025 15:18
@gpshead @claude
Expand motivation with answers to common questions
47d0b78 
Added two new sections to address questions raised at core team sprint:

1. "Why Exception Groups Need Timestamps" - Explains that while exception
   groups are conceptually unrelated, in practice they have important
   temporal relationships for debugging causality, performance analysis,
   and correlation with external observability tools.

2. "Why Not Use .add_note() When Catching?" - Details six key drawbacks
   of using add_note() instead: not all exceptions are caught, timing
   accuracy issues, inconsistent application, performance overhead,
   complexity burden, and loss of original timing information.

Key insight: When an exception occurs is intrinsic, immutable information
that should be captured at the source, not added later by consumers.

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@gpshead @claude
Update control flow exception handling to acknowledge configurability…
892bb05 
… need

Based on feedback from @picnixz about Sphinx's Skip exception and other
projects using exceptions for control flow:

1. Renamed "Special Cases" to "Control Flow Exceptions" for clarity
2. Added acknowledgment that other projects need this configurability
3. Deferred specific API design to open issues
4. Updated Open Issue python#5 with key challenges:
   - API design options (env var vs Python API)
   - Performance constraints in the hot path
   - Subclass handling complexity
   - Whether to expand the default exclusion list

The PEP now acknowledges the need for configurability while leaving the
specific implementation approach as an open question requiring careful
API design and performance testing.

🤖 Generated with Claude Code (https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@rocky-d

This comment was marked as spam.

Sign in to view
@rocky-d

This comment was marked as spam.

Sign in to view
@gpshead @claude
Revise PEP to match implementation and improve writing
21686cf 
Align the PEP with the current reference implementation, resolve all
open issues, and rewrite for conciseness and natural tone.

Implementation alignment:
- Fix type description to int64_t, fix StopAsyncIteration name
- Document pickle format (2-tuple when disabled, 3-tuple when enabled)
- Document colorized output, control flow check uses C pointer identity
- Resolve all open issues into Rejected Ideas

Writing improvements:
- Cut from ~500 to ~300 lines by removing redundant subsections
- Rewrite Motivation: delete "Why Exception Groups Need Timestamps",
  move .add_note() comparison to Rejected Ideas, trim example analysis
- Convert numbered bold lists to prose throughout
- Add Maintenance Burden section with test suite impact data
- Remove non-ASCII characters and remaining LLM-isms
- Security Implications: None (opt-in, disabled by default)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@gpshead gpshead force-pushed the pep-exception-timestamps branch from 6832465 to 21686cf Compare March 15, 2026 09:04
@gpshead gpshead changed the title PEP 9999: Add timestamps to exception tracebacks PEP 9999: Add timestamps to exceptions and tracebacks Mar 15, 2026
@hugovk

This comment was marked as resolved.

Sign in to view
gpshead and others added 5 commits March 15, 2026 09:29
@gpshead @claude
Rename pep-08XX.rst to pep-9999.rst and update PEP number
c18f3bb 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@gpshead
date and discussion pending lints
a05e769
@gpshead @claude
Remove unreferenced footnotes to fix Sphinx warnings
988a5c0 
The PEPs and CPython PR are already linked inline throughout the text.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@gpshead
no syntax highlighting of the example tracebacks
f254b72
@gpshead
some more polish, claim number 829, TODOs before undrafting
7e9ff7f
@gpshead gpshead changed the title PEP 9999: Add timestamps to exceptions and tracebacks PEP 829: Add timestamps to exceptions and tracebacks Mar 15, 2026
@gpshead gpshead self-assigned this Mar 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@gpshead gpshead

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@gpshead @rocky-d @hugovk