gh-132502: Prototyping adding timestamps to tracebacks.

.github/workflows/build.yml

@@ -269,6 +269,7 @@ jobs:
       bolt-optimizations: ${{ matrix.bolt }}
       free-threading: ${{ matrix.free-threading }}
       os: ${{ matrix.os }}
+      traceback_timestamps: ${{ matrix.os == 'ubuntu-22.04-arm' && matrix.bolt == false && 'ns' || '' }}
 
   build-ubuntu-ssltests:
     name: 'Ubuntu SSL tests with OpenSSL'
@@ -686,3 +687,4 @@ jobs:
             || ''
           }}
         jobs: ${{ toJSON(needs) }}
+        traceback_timestamps: 'iso'

.github/workflows/reusable-macos.yml

@@ -14,6 +14,10 @@ on:
         description: OS to run the job
         required: true
         type: string
+      traceback_timestamps:
+        description: Set to us|1|ns|iso to enable printing timestamps on exceptions in tracebacks (for feature coverage)
+        required: false
+        type: string
 
 env:
   FORCE_COLOR: 1
@@ -29,6 +33,7 @@ jobs:
       HOMEBREW_NO_INSTALL_CLEANUP: 1
       HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK: 1
       PYTHONSTRICTEXTENSIONBUILD: 1
+      PYTHON_TRACEBACK_TIMESTAMPS: ${{ inputs.traceback_timestamps }}
       TERM: linux
     steps:
     - uses: actions/checkout@v4

.github/workflows/reusable-ubuntu.yml

@@ -17,9 +17,13 @@ on:
         type: boolean
         default: false
       os:
-         description: OS to run the job
-         required: true
-         type: string
+        description: OS to run the job
+        required: true
+        type: string
+      traceback_timestamps:
+        description: Set to us|1|ns|iso to enable printing timestamps on exceptions in tracebacks (for feature coverage)
+        required: false
+        type: string
 
 env:
   FORCE_COLOR: 1
@@ -33,6 +37,7 @@ jobs:
       OPENSSL_VER: 3.0.15
       PYTHONSTRICTEXTENSIONBUILD: 1
       TERM: linux
+      PYTHON_TRACEBACK_TIMESTAMPS: ${{ inputs.traceback_timestamps }}
     steps:
     - uses: actions/checkout@v4
       with:

.github/workflows/reusable-windows.yml

@@ -29,6 +29,7 @@ jobs:
     timeout-minutes: 60
     env:
       ARCH: ${{ inputs.arch }}
+      PYTHON_TRACEBACK_TIMESTAMPS: 'ns'
     steps:
     - uses: actions/checkout@v4
       with:

Doc/c-api/init_config.rst

@@ -493,6 +493,10 @@ Configuration Options
      - :c:member:`tracemalloc <PyConfig.tracemalloc>`
      - ``int``
      - Read-only
+   * - ``"traceback_timestamps"``
+     - :c:member:`traceback_timestamps <PyConfig.traceback_timestamps>`
+     - ``str``
+     - Read-only
    * - ``"use_environment"``
      - :c:member:`use_environment <PyConfig.use_environment>`
      - ``bool``
@@ -1883,6 +1887,25 @@ PyConfig
 
       Default: ``-1`` in Python mode, ``0`` in isolated mode.
 
+   .. c:member:: wchar_t* traceback_timestamps
+
+      Format of timestamps shown in tracebacks.
+
+      If not ``NULL`` or an empty string, timestamps of exceptions are collected
+      and will be displayed in the configured format. Acceptable values are:
+
+      * ``"us"``: Display timestamps in microseconds
+      * ``"ns"``: Display timestamps in nanoseconds
+      * ``"iso"``: Display timestamps in ISO-8601 format
+      * ``""``: Collection and display is disabled.
+
+      Set by the :option:`-X traceback_timestamps=FORMAT <-X>` command line
+      option or the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable.
+
+      Default: ``NULL`` (timestamps disabled).
+
+      .. versionadded:: next
+
    .. c:member:: int perf_profiling
 
       Enable the Linux ``perf`` profiler support?

Doc/library/doctest.rst

@@ -530,6 +530,11 @@ Some details you should read once, but won't need to remember:
   everything following the leftmost colon and any module information in the
   exception name is ignored.
 
+* When the :const:`IGNORE_EXCEPTION_TIMESTAMPS` doctest option is specified,
+  timestamps of the formats that :envvar:`PYTHON_TRACEBACK_TIMESTAMPS`
+  environment variable could append to exception messages are stripped from
+  tracebacks generated by the code under test before comparison.
+
 * The interactive shell omits the traceback header line for some
   :exc:`SyntaxError`\ s.  But doctest uses the traceback header line to
   distinguish exceptions from non-exceptions.  So in the rare case where you need
@@ -652,6 +657,22 @@ doctest decides whether actual output matches an example's expected output:
       to the module containing the exception under test.
 
 
+.. data:: IGNORE_EXCEPTION_TIMESTAMPS
+
+   When the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable is set,
+   exception and warning messages rendered in tracebacks may have a timestamp
+   value appended after the message.  This strips all possible formats of that
+   timestamp tag that may be appended to an exception message in generated
+   tracebacks before comparing.
+
+   :const:`ELLIPSIS` and :const:`IGNORE_EXCEPTION_DETAIL` could also be used to
+   avoid matching those.  This can be cleaner when you need to test specific
+   details of exception messages.
+
+   .. versionadded:: next
+      :const:`IGNORE_EXCEPTION_TIMESTAMPS` was added.
+
+
 .. data:: SKIP
 
    When specified, do not run the example at all.  This can be useful in contexts

Doc/library/exceptions.rst

@@ -159,6 +159,35 @@ The following exceptions are used mostly as base classes for other exceptions.
 
       .. versionadded:: 3.11
 
+   .. attribute:: __timestamp_ns__
+
+      The absolute time in nanoseconds at which this exception was instantiated
+      (usually: when it was raised); the same accuracy as :func:`time.time_ns`.
+      Display of these timestamps after the exception message in tracebacks is
+      off by default but can be configured using the
+      :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable.  In
+      applications with complicated exception chains and exception groups it
+      may be useful to help understand what happened when.  The value will be
+      ``0`` if a timestamp was not recorded.  :exc:`StopIteration` and
+      :exc:`StopAsyncIteration` never record timestamps as those are primarily
+      for control flow.
+
+      With ``PYTHON_TRACEBACK_TIMESTAMPS=iso`` in the environment ::
+
+         Traceback (most recent call last):
+           File "<python-input-0>", line 1, in <module>
+             raise RuntimeError("example")
+         RuntimeError: example <@2025-02-08T01:21:28.675309Z>
+
+      With ``PYTHON_TRACEBACK_TIMESTAMPS=ns`` in the environment ::
+
+         Traceback (most recent call last):
+           File "<python-input-0>", line 1, in <module>
+             raise RuntimeError("example")
+         RuntimeError: example <@1739172733527638530ns>
+
+      .. versionadded:: next
+
 
 .. exception:: Exception
 

Doc/library/sys.rst

@@ -606,6 +606,10 @@ always available. Unless explicitly noted otherwise, all variables are read-only
         - :option:`-X context_aware_warnings <-X>` and
           :envvar:`PYTHON_CONTEXT_AWARE_WARNINGS`
 
+      * - .. attribute:: flags.traceback_timestamps
+        - :option:`-X traceback_timestamps <-X>`.  This is a string containing
+          the selected format (``us``, ``ns``, ``iso``),  or an empty string
+          when disabled.
 
    .. versionchanged:: 3.2
       Added ``quiet`` attribute for the new :option:`-q` flag.
@@ -642,6 +646,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    .. versionchanged:: 3.14
       Added the ``context_aware_warnings`` attribute.
 
+   .. versionchanged:: next
+      Added the ``traceback_timestamps`` attribute.
+
 
 .. data:: float_info