some more polish, claim number 829, TODOs before undrafting

Author: gpshead

peps/pep-9999.rst peps/pep-0829.rstpeps/pep-9999.rst renamed to peps/pep-0829.rst

@@ -1,4 +1,4 @@
-PEP: 9999
+PEP: 829
 Title: Add timestamps to exceptions and tracebacks
 Author: Gregory P. Smith <greg@krypto.org>
 PEP-Delegate:
@@ -14,9 +14,9 @@ Abstract
 ========
 
 This PEP adds an optional ``__timestamp_ns__`` attribute to ``BaseException``
-that records when the exception was instantiated.  When enabled via environment
-variable or command-line flag, formatted tracebacks display this timestamp
-alongside the exception message.
+that records when the exception was instantiated with no observable overhead.
+When enabled via environment variable or command-line flag, formatted
+tracebacks display this timestamp alongside the exception message.
 
 
 Motivation
@@ -27,9 +27,9 @@ propagate multiple unrelated exceptions simultaneously.  When debugging these,
 or when correlating exceptions with external logs and metrics, knowing *when*
 each exception occurred is often as important as knowing *what* occurred.
 
-Currently there is no standard way to obtain this information.  Developers must
-manually add timing to exception messages or rely on logging frameworks, which
-is inconsistent and error-prone.
+Currently there is no standard way to obtain this information.  Python authors
+must manually add timing to exception messages or rely on logging frameworks,
+which can be costly and is inconsistently done and error-prone.
 
 Consider an async service that fetches data from multiple backends concurrently
 using ``asyncio.TaskGroup``.  When several backends fail, the resulting
@@ -91,8 +91,9 @@ With ``PYTHON_TRACEBACK_TIMESTAMPS=iso``, the output becomes:
 
 The timestamps immediately reveal that the order validation failed first
 (at .142s), while the recommendation service was the slowest at 2.3 seconds.
-They can also be correlated with metrics dashboards, load balancer logs, or
-traces from other services to build a complete picture of the incident.
+That could also be correlated with metrics dashboards, load balancer logs, or
+traces from other services or even logs from the program itself to build a
+complete picture.
 
 
 Rationale
@@ -124,7 +125,7 @@ Control Flow Exceptions
 To avoid performance impact on normal control flow, timestamps are **not**
 collected for ``StopIteration`` or ``StopAsyncIteration`` even when the feature
 is enabled.  These exceptions are raised at extremely high frequency during
-iteration; the check uses C type pointer identity (not ``isinstance``) and adds
+iteration; the check uses C type pointer identity (not ``isinstance``) for
 negligible overhead.
 
 Configuration
@@ -228,6 +229,18 @@ GitHub Actions runs to maintain coverage, most projects are unlikely to
 have the feature enabled while running their test suites.
 
 
+Performance Measurements
+========================
+
+The pyperformance suite has been run on the merge base, on the PR branch with
+the feature disabled, and on the PR branch with the feature enabled in both
+``ns`` and ``iso`` modes.
+
+TODO(@gpshead): summarize results of the most recent run here.
+
+TODO(@gpshead): Do another run with the feature enabled but without the StopIteration special case to demonstrate why that choice was made.
+
+
 Security Implications
 =====================