sysfce2 · pull · Nov 7, 2025 · Nov 6, 2025
diff --git a/doc/faq.rst b/doc/faq.rst
@@ -143,15 +143,23 @@ The total percentage is calculated as::
 Q: Coverage.py is much slower than I remember, what's going on?
 ...............................................................
 
-Make sure you are using the C trace function.  Coverage.py provides two
-implementations of the trace function.  The C implementation runs much faster.
-To see what you are running, use ``coverage debug sys``.  The output contains
-details of the environment, including a line that says either
-``CTracer: available`` or ``CTracer: unavailable``.  If it says unavailable,
-then you are using the slow Python implementation.
-
-Try re-installing coverage.py to see what happened and if you get the CTracer
-as you should.
+Make sure you are using the ``ctrace`` or ``sysmon`` core for measurement.
+Coverage.py provides three different measurement cores. ``ctrace`` is the
+default in Python versions up to 3.13, but might not be installed properly, in
+which case the slower ``pytrace`` core is used.
+
+``sysmon`` is the default in Python 3.14 and later, and is the fastest of the
+three.
+
+To see what you are running, add ``--debug=sys`` to your ``coverage run``
+command line.  The ``core=`` line will indicate which core is being used.  The
+output also includes a line that says either ``CTracer: available`` or
+``CTracer: unavailable`` showing whether the ``ctrace`` core is installed and
+usable.  If it's not, try re-installing coverage.py to see what happened and if
+you get the CTracer as you should.
+
+If needed, you can request a specific core with the ``core=`` setting.  See the
+:ref:`core configuration <config_run_core>` documentation for details.
 
 
 Q: Isn't coverage testing the best thing ever?

diff --git a/doc/howitworks.rst b/doc/howitworks.rst
@@ -19,13 +19,13 @@ Coverage.py works in three phases:
   have run.
 
 * **Reporting**: Coverage.py combines the results of execution and analysis to
-  produce a coverage number and an indication of missing execution.
+  produce coverage statistics and a report of missing execution.
 
 The execution phase is handled by the ``coverage run`` command.  The analysis
 and reporting phases are handled by the reporting commands like ``coverage
 report`` or ``coverage html``.
 
-As a short-hand, I say that coverage.py measures what lines were executed. But
+As a short-hand, I say that coverage.py measures what lines were executed, but
 it collects more information than that.  It can measure what branches were
 taken, and if you have contexts enabled, for each line or branch, it will also
 measure what contexts they were executed in.
@@ -36,30 +36,46 @@ Let's look at each phase in more detail.
 Execution
 ---------
 
-At the heart of the execution phase is a trace function.  This is a function
-that the Python interpreter invokes for each line executed in a program.
-Coverage.py implements a trace function that records each file and line number
-as it is executed.
+At the heart of the execution phase is a measurement core. It listens for
+execution events from the Python interpreter, and captures raw data about what
+has executed.
 
-For more details of trace functions, see the Python docs for `sys.settrace`_,
-or if you are really brave, `How C trace functions really work`_.
+Coverage.py has three cores: ``ctrace`` and ``pytrace`` use trace functions
+with `sys.settrace`_, and ``sysmon`` uses `sys.monitoring`_ for events.
 
-Executing a function for every line in your program can make execution very
-slow.  Coverage.py's trace function is implemented in C to reduce that
-overhead. It also takes care to not trace code that you aren't interested in.
+- A **trace function** is a function that the Python interpreter invokes for
+  each line executed in a program.  Coverage.py uses trace functions that
+  record each file and line number as it is executed. The ``ctrace`` trace
+  function is implemented in C for speed, while ``pytrace`` is implemented in
+  Python for portability.
 
-When measuring branch coverage, the same trace function is used, but instead of
-recording line numbers, coverage.py records pairs of line numbers.  Each
-invocation of the trace function remembers the line number, then the next
-invocation records the pair `(prev, this)` to indicate that execution
-transitioned from the previous line to this line.  Internally, these are called
-arcs.
+  For more details of trace functions, see the Python docs for `sys.settrace`_,
+  or if you are really brave, `How C trace functions really work`_.
+
+  Executing a function for every line in your program can make execution very
+  slow.  Coverage.py's trace function is implemented in C to reduce that
+  overhead. It also takes care to not trace code that you aren't interested in.
+
+- The **sys.monitoring** API is available on Python 3.12 and later.  The
+  ``sysmon`` core uses it to get execution events from the interpreter with
+  much lower overhead than trace functions.
+
+  It does this by disabling events once they have been seen. This means that
+  complex features like dynamic contexts are not supported yet, but for simple
+  line and branch coverage, it is much faster than trace functions.
+
+When measuring branch coverage, the same event collectors are used, but instead
+of recording line numbers, coverage.py records pairs of line numbers.  Each
+line event records the line number, then the next event records the pair
+`(prev, this)` to indicate that execution transitioned from the previous line
+to this line.  Internally, these are called arcs.
 
 As the data is being collected, coverage.py writes the data to a file, usually
 named ``.coverage``.  This is a :ref:`SQLite database <dbschema>` containing
 all of the measured data.
 
 .. _sys.settrace: https://docs.python.org/3/library/sys.html#sys.settrace
+.. _sys.monitoring: https://docs.python.org/3/library/sys.monitoring.html
 .. _How C trace functions really work: https://nedbatchelder.com/text/trace-function.html