Fixes

Author: pablogsal

Doc/library/debug.rst

@@ -17,7 +17,6 @@ intrusive debugging or patching.
    pdb.rst
    profiling.rst
    pstats.rst
-   profile.rst
    timeit.rst
    trace.rst
    tracemalloc.rst

Doc/library/profiling-sampling.rst

@@ -33,8 +33,8 @@ What is statistical profiling?
 
 Statistical profiling builds a picture of program behavior by periodically
 capturing snapshots of the call stack. Rather than instrumenting every function
-call and return as deterministic profilers do, the sampling profiler interrupts
-execution at regular intervals to record what code is currently running.
+call and return as deterministic profilers do, the sampling profiler reads the
+call stack at regular intervals to record what code is currently running.
 
 This approach rests on a simple principle: functions that consume significant
 CPU time will appear frequently in the collected samples. By gathering thousands
@@ -53,7 +53,9 @@ and inferring your path from those snapshots.
 
 This external observation model is what makes sampling profiling practical for
 production use. The profiled program runs at full speed because there is no
-instrumentation code running inside it. You can attach to a live server,
+instrumentation code running inside it, and the target process is never stopped
+or paused during sampling---the profiler reads the call stack directly from the
+process's memory while it continues to run. You can attach to a live server,
 collect data, and detach without the application ever knowing it was observed.
 The trade-off is that very short-lived functions may be missed if they happen
 to complete between samples.
@@ -262,6 +264,36 @@ if the profiler cannot keep up. The statistics help verify that profiling is
 working correctly and that sufficient samples are being collected.
 
 
+.. _sampling-efficiency:
+
+Sampling efficiency
+-------------------
+
+Sampling efficiency metrics help assess the quality of the collected data.
+These metrics appear in the profiler's terminal output and in the flame graph
+sidebar.
+
+**Sampling efficiency** is the percentage of sample attempts that succeeded.
+Each sample attempt reads the target process's call stack from memory. An
+attempt can fail if the process is in an inconsistent state at the moment of
+reading, such as during a context switch or while the interpreter is updating
+its internal structures. A low efficiency may indicate that the profiler could
+not keep up with the requested sampling rate, often due to system load or an
+overly aggressive interval setting.
+
+**Missed samples** is the percentage of expected samples that were not
+collected. Based on the configured interval and duration, the profiler expects
+to collect a certain number of samples. Some samples may be missed if the
+profiler falls behind schedule, for example when the system is under heavy
+load. A small percentage of missed samples is normal and does not significantly
+affect the statistical accuracy of the profile.
+
+Both metrics are informational. Even with some failed attempts or missed
+samples, the profile remains statistically valid as long as enough samples
+were collected. The profiler reports the actual number of samples captured,
+which you can use to judge whether the data is sufficient for your analysis.
+
+
 Profiling modes
 ===============
 
@@ -441,7 +473,7 @@ zooms into that portion of the call tree.
 The flame graph interface includes:
 
 - A sidebar showing profile summary, thread statistics, sampling efficiency
-  metrics (error rate, missed samples), and top hotspot functions
+  metrics (see :ref:`sampling-efficiency`), and top hotspot functions
 - Search functionality supporting both function name matching and
   ``file.py:42`` line patterns
 - Per-thread filtering via dropdown

Doc/library/superseded.rst

@@ -24,3 +24,4 @@ currently no modules in this latter category.
    :maxdepth: 1
 
    getopt.rst
+   profile.rst

Doc/whatsnew/2.5.rst

@@ -1277,12 +1277,12 @@ complete list of changes, or look through the SVN logs for all the details.
   with the new ':keyword:`with`' statement.  See section :ref:`contextlibmod`
   for more about this module.
 
-* New module: The :mod:`cProfile` module is a C implementation of  the existing
-  :mod:`profile` module that has much lower overhead. The module's interface is
-  the same as :mod:`profile`: you run ``cProfile.run('main()')`` to profile a
+* New module: The :mod:`!cProfile` module is a C implementation of  the existing
+  :mod:`!profile` module that has much lower overhead. The module's interface is
+  the same as :mod:`!profile`: you run ``cProfile.run('main()')`` to profile a
   function, can save profile data to a file, etc.  It's not yet known if the
   Hotshot profiler, which is also written in C but doesn't match the
-  :mod:`profile` module's interface, will continue to be maintained in future
+  :mod:`!profile` module's interface, will continue to be maintained in future
   versions of Python.  (Contributed by Armin Rigo.)
 
   Also, the :mod:`pstats` module for analyzing the data measured by the profiler

Doc/whatsnew/3.7.rst

@@ -841,7 +841,7 @@ and by Alexander Mohr and Ilya Kulakov in :issue:`29302`.)
 cProfile
 --------
 
-The :mod:`cProfile` command line now accepts ``-m module_name`` as an
+The :mod:`!cProfile` command line now accepts ``-m module_name`` as an
 alternative to script path.  (Contributed by Sanyam Khurana in :issue:`21862`.)
 
 

Misc/NEWS.d/3.10.0a2.rst

@@ -593,7 +593,7 @@ of treating them as a match.
 .. nonce: ONk9Na
 .. section: Library
 
-Fix ``--outfile`` for :mod:`cProfile` / :mod:`profile` not writing the
+Fix ``--outfile`` for :mod:`!cProfile` / :mod:`!profile` not writing the
 output file in the original directory when the program being profiled
 changes the working directory.  PR by Anthony Sottile.
 

Misc/NEWS.d/3.10.0a5.rst

@@ -426,7 +426,7 @@ specified using a relative path and the current directory changed.
 .. nonce: Jq6Az-
 .. section: Library
 
-Fix CLI of :mod:`cProfile` and :mod:`profile` to catch
+Fix CLI of :mod:`!cProfile` and :mod:`!profile` to catch
 :exc:`BrokenPipeError`.
 
 ..

Misc/NEWS.d/3.12.0b1.rst

@@ -1257,7 +1257,7 @@ defined by any build system or documented for manual use.
 .. nonce: n_AfcS
 .. section: Library
 
-Update :mod:`cProfile` to use PEP 669 API
+Update :mod:`!cProfile` to use PEP 669 API
 
 ..
 

Misc/NEWS.d/3.13.0a1.rst

@@ -3476,7 +3476,7 @@ Fix rare concurrency bug in lock acquisition by the logging package.
 .. nonce: ya5jBT
 .. section: Library
 
-Added PY_THROW event hook for :mod:`cProfile` for generators
+Added PY_THROW event hook for :mod:`!cProfile` for generators
 
 ..
 

Misc/NEWS.d/3.14.0a1.rst

@@ -2623,7 +2623,7 @@ Fix :func:`unittest.mock.patch` to not read attributes of the target when
 .. nonce: s4HXR0
 .. section: Library
 
-Fixed the use-after-free issue in :mod:`cProfile` by disallowing
+Fixed the use-after-free issue in :mod:`!cProfile` by disallowing
 ``disable()`` and ``clear()`` in external timers.
 
 ..