reword some docs, add examples

Author: gpshead

Doc/library/exceptions.rst

@@ -161,16 +161,31 @@ The following exceptions are used mostly as base classes for other exceptions.
 
    .. attribute:: __timestamp_ns__
 
-      The absolute time in nanoseconds at which the exception was instantiated
-      (usually: when it was raised); as accurate as :func:`time.time_ns`.
-      Display of this in tracebacks is off by default but can be controlled
-      using the :envvar:`PYTHON_TRACEBACK_TIMESTAMPS` environment variable.  In
+      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.675309>
+
+      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
 
 

Doc/using/cmdline.rst

@@ -1223,21 +1223,19 @@ conflict.
 
 .. 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 :meth:`~datetime.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.
+   If this variable is set to any of the following values, tracebacks printed
+   by the runtime will be annotated with the timestamp of each exception.  The
+   values control the format of the timestamp.  ``us`` or ``1`` prints decimal
+   timestamps with microsecond precision, ``ns`` prints the raw timestamp in
+   nanoseconds, ``iso`` prints the timestamp formatted by
+   :meth:`~datetime.datetime.isoformat` which is also microsecond precision.
+   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 remains disabled.
+
+   Formatting of the timestamps only happens at printing time.  The ``iso``
+   format may be slower due to the complexity of the code involved but is much
+   more readable.
 
    .. versionadded:: next