initial pass at documentation.

Author: gpshead

Doc/library/exceptions.rst

@@ -159,6 +159,19 @@ The following exceptions are used mostly as base classes for other exceptions.
 
       .. versionadded:: 3.11
 
+   .. attribute:: __timestamp_ns__
+
+      The time at which the exception instance was instantiated (usually when
+      it was raised) in nanoseconds in :func:`time.time_ns` units.  Display of
+      this in tracebacks can be controlled using the
+      :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable.  In
+      applications with complicated exception chains and exception groups it be
+      used to help visualize what happened when.  The value will be 0 if a time
+      was not recorded as is the case on :exc:`StopIteration` and
+      :exc:`AsyncStopIteration`.
+
+      .. versionadded:: next
+
 
 .. exception:: Exception
 

Doc/using/cmdline.rst

@@ -1221,6 +1221,27 @@ conflict.
 
    .. versionadded:: 3.13
 
+.. envvar:: PYTHON_TRACEBACK_TIMESTAMPS
+
+   If this variable is set to any of the following values, tracebacks displayed
+   by the :mod:`traceback` module will be annotated with the timestamp of each
+   exception.  The values control the format of the timestamp.  ``us`` or ``1``
+   displays decimal timestamps with microsecond precision, ``ns`` displays the
+   nanosecond timestamp as :func:`time.time_ns` would produce, ``iso`` enables
+   display formatted by :func:`datetime.isoformat`.  The time is not recorded
+   on the :exc:`StopIteration` family of exceptions for performance reasons as
+   those are used for control flow rather than errors. If unset, empty or other
+   values this feature is disabled.
+
+   Timestamps are collected as nanoseconds internally when exceptions are
+   instantiated and are available via a :attr:`~BaseException.__timestamp_ns__`
+   attribute.  Optional formatting of the timestamps only happens during
+   :mod:`traceback` rendering.  The ``iso`` format is presumed slower to
+   display due to the complexity of the code involved.
+
+   .. versionadded:: next
+
+
 Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~