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 <cody@xxxxxxxxxxx> --- 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. + +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_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 +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
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 @@ measurement as well as any kernel use of the performance counters .TP .I exclude_user If this bit is set, the count excludes events that happen in user 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_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 @@ In that case the events run only part of the time and the 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 +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.
