Re: [PATCH] man/man2/perf_event_open.2: Clarify that exclude_kernel does not affect time_running
From: Alejandro Colomar <alx@kernel.org>
Date: 2025-02-05 16:46:54
Hi Cody, On Tue, Feb 04, 2025 at 09:42:59PM -0500, Cody Tapscott wrote:
quoted hunk ↗ jump to hunk
The goal of this patch is to clarify some limitations regarding re-scaled event counts measured via perf_event_open. The man page recommends re-scaling event counts as (value * time_enabled / time_running), but does not mention that some time-filters (esp. exclude_kernel and exclude_user) do not affect the reported time_enabled or time_running, sometimes causing a very noisy estimate of the true event count. This limitation is easy to encounter when profiling events that are dominated by kernel (>= 50%) vs. user time and which are relatively short compared to the PMU muxing frequency (~several milliseconds, on my machine). In those cases, it is common to see (time_running / time_enabled) report, e.g., ~50% active time when perhaps almost none of the user time was actually spent with the counter running, leading to a dramatic under-estimate of the event counts. Signed-off-by: Cody Tapscott <redacted> --- man/man2/perf_event_open.2 | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)diff --git a/man/man2/perf_event_open.2 b/man/man2/perf_event_open.2 index bcc6a39cb..d52c04c3d 100644 --- a/man/man2/perf_event_open.2 +++ b/man/man2/perf_event_open.2@@ -1063,9 +1063,23 @@ .SS Arguments .TP .I exclude_user If this bit is set, the count excludes events that happen in user space. +
This should be .IP (indented paragraph).
+Note this does not affect the +.I time_running +or +.I time_enabled +fields, so enabling this may impact the reliability of the estimated total +counts in the presence of multiplexing.
Please use semantic newlines. See man-pages(7):
$ MANWIDTH=72 man man-pages 2>/dev/null \
| sed -n '/Use semantic newlines/,/^$/p';
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at
clause breaks (commas, semicolons, colons, and so on), and long
clauses should be split at phrase boundaries. This convention,
sometimes known as "semantic newlines", makes it easier to see
the effect of patches, which often operate at the level of indi-
vidual sentences, clauses, or phrases.
quoted hunk ↗ jump to hunk
.TP .I exclude_kernel If this bit is set, the count excludes events that happen in kernel space. + +Note this does not affect the +.I time_running +or +.I time_enabled +fields, so enabling this may impact the reliability of the estimated total +counts in the presence of multiplexing. .TP .I exclude_hv If this bit is set, the count excludes events that happen in the@@ -1677,6 +1691,11 @@ .SS Reading results and .I time running values can be used to scale an estimated value for the count. + +Note that for most events these values are not affected by +.IR exclude_hv ", " exclude_idle ", " exclude_user ", or " exclude_kernel
Please use one line per identifier: .IR a , .IR b , or .I c Have a lovely day! Alex
+and, if these are enabled, the scaled estimate may be +significantly less reliable in the presence of multiplexing. .TP .I value An unsigned 64-bit value containing the counter result. -- 2.34.1
-- <https://www.alejandro-colomar.es/>
Attachments
- signature.asc [application/pgp-signature] 833 bytes