perf stat: worth documenting task-clock/cpu-clock in perf-stat.txt?
Hello Arnaldo,
I'm learning performance engineering and ran into this while playing around with perf stat. perf-stat.txt's TIMINGS section explains "time elapsed" and "user"/"sys", but I couldn't find task-clock itself documented anywhere, even though it appears in the first command example, as the very first metric shown.
This apparently came up unanswered on this list before, in 2013 and 2015 (2015: https://www.spinics.net/lists/linux-perf-users/msg02405.html),
where users asked about cpu-clock too, without anything ever being added to the docs. Would it be worth documenting task-clock/cpu-clock there? Happy to send a patch if so.
Best regards,
Christian
Ian Rogers
reviewerQuoted 9 lines · Christian Melendez
Hello Arnaldo,
I'm learning performance engineering and ran into this while playing around with perf stat. perf-stat.txt's TIMINGS section explains "time elapsed" and "user"/"sys", but I couldn't find task-clock itself documented anywhere, even though it appears in the first command example, as the very first metric shown.
Quoted 5 lines
This apparently came up unanswered on this list before, in 2013 and 2015 (2015: https://www.spinics.net/lists/linux-perf-users/msg02405.html),
where users asked about cpu-clock too, without anything ever being added to the docs. Would it be worth documenting task-clock/cpu-clock there? Happy to send a patch if so.
Extra documentation always sounds good to me. We added json documentation for software events not long ago (it shows up in perf list):
https://web.git.kernel.org/pub/scm/linux/kernel/git/perf/perf-tools-next.git/tree/tools/perf/pmu-events/arch/common/common/software.json
There is also documentation of cpu-clock and task-clock in the perf_event_open man page.
Thanks,
Ian
Quoted 3 lines
Best regards,
Christian
PATCH 1/1 perf stat: document task-clock/cpu-clock in TIMINGS
task-clock/cpu-clock appear in perf stat's own example output but were never explained in perf-stat.txt, unlike time elapsed/user/sys. This came up unanswered on the list in 2013 and 2015 without docs ever being added.
--- tools/perf/Documentation/perf-stat.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)
tools/perf/Documentation/perf-stat.txt +11 -1
@@ -621,6 +621,16 @@ user/system lands: Those times are the very same as displayed by the 'time' tool. +We also display a clock-based timing metric that depends on the +target being monitored: + + 83723.452481 task-clock:u (msec) # 1.004 CPUs utilized + +For a single task, task-clock reports a clock count specific to that +task. When the target is a CPU or the whole system (-a or -C), +cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU +timer. See perf_event_open(2) for more details. + CSV FORMAT ----------
@@ -671,4 +681,4 @@ that can be used for parsing. SEE ALSO -------- -linkperf:perf-top[1], linkperf:perf-list[1] +linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2)
Signature · 1 line
2.34.1
[email protected]
AI reviewRe: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS
Sashiko has reviewed this patch and found no issues. It looks great!
Quoted 7 lines
task-clock/cpu-clock appear in perf stat's own example output but were never explained in perf-stat.txt, unlike time elapsed/user/sys. This came up unanswered on the list in 2013 and 2015 without docs ever being added.
Sashiko has reviewed this patch and found no issues. It looks great!
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
Re: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS
In reply to Christian MelendezQuoted 8 lines · Christian Melendez
task-clock/cpu-clock appear in perf stat's own example output but were never explained in perf-stat.txt, unlike time elapsed/user/sys. This came up unanswered on the list in 2013 and 2015 without docs ever being added.
Thanks,
Ian
Quoted 34 lines
--- tools/perf/Documentation/perf-stat.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)tools/perf/Documentation/perf-stat.txt +11
-2@@ -621,6 +621,16 @@ user/system lands: Those times are the very same as displayed by the 'time' tool. +We also display a clock-based timing metric that depends on the +target being monitored: + + 83723.452481 task-clock:u (msec) # 1.004 CPUs utilized + +For a single task, task-clock reports a clock count specific to that +task. When the target is a CPU or the whole system (-a or -C), +cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU +timer. See perf_event_open(2) for more details. + CSV FORMAT ----------@@ -671,4 +681,4 @@ that can be used for parsing. SEE ALSO -------- -linkperf:perf-top[1], linkperf:perf-list[1] +linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2) --2.34.1
Re: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS
Quoted 11 lines · Ian Rogers
Quoted 8 lines · Christian Melendez
task-clock/cpu-clock appear in perf stat's own example output but were never explained in perf-stat.txt, unlike time elapsed/user/sys. This came up unanswered on the list in 2013 and 2015 without docs ever being added.
Reviewed-by Ian Rogers <[email protected]>
Thanks, applied to perf-tools-next, for v7.4.
- Arnaldo
Namhyung Kim
maintainerRe: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS
In reply to Christian MelendezHello,
Quoted 16 lines · Christian Melendez
task-clock/cpu-clock appear in perf stat's own example output but were never explained in perf-stat.txt, unlike time elapsed/user/sys. This came up unanswered on the list in 2013 and 2015 without docs ever being added.
Link https://patch.msgid.link/CAP-5=fV0-yvc68BUSKoSajHjHY_A6COgbEJYiFxRg+G-8LeJhQ@mail.gmail.com open hereSigned-off-by Christian Melendez <[email protected]>--- tools/perf/Documentation/perf-stat.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)tools/perf/Documentation/perf-stat.txt +0
-0
tools/perf/Documentation/perf-stat.txt user/system lands: · line 627
Quoted 7 lines
tools/perf/Documentation/perf-stat.txt +4
-0@@ -621,6 +621,16 @@ user/system lands: Those times are the very same as displayed by the 'time' tool. +We also display a clock-based timing metric that depends on the +target being monitored: + + 83723.452481 task-clock:u (msec) # 1.004 CPUs utilized
I'm afraid task-clock and any other software events don't support privilege filters or modifiers. So task-clock:u would be same as task-clock, but it can give a wrong idea that it only measured time in userspace.
Maybe the kernel can reject ones with modifiers but then it would have a compatibility issue. :(
So I think it's better to remove the ":u" modifier in the example output. Probably we need to change the perf not to add it to the software events.
Thanks,
Namhyung
Quoted 18 lines
tools/perf/Documentation/perf-stat.txt +7
-1+ +For a single task, task-clock reports a clock count specific to that +task. When the target is a CPU or the whole system (-a or -C), +cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU +timer. See perf_event_open(2) for more details. + CSV FORMAT ----------@@ -671,4 +681,4 @@ that can be used for parsing. SEE ALSO -------- -linkperf:perf-top[1], linkperf:perf-list[1] +linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2)Signature · 1 line
2.34.1
Arnaldo Carvalho de Melo
maintainerRe: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS
Quoted 32 lines · Namhyung Kim
Hello,
Quoted 16 lines · Christian Melendez
task-clock/cpu-clock appear in perf stat's own example output but were never explained in perf-stat.txt, unlike time elapsed/user/sys. This came up unanswered on the list in 2013 and 2015 without docs ever being added.
Link https://patch.msgid.link/CAP-5=fV0-yvc68BUSKoSajHjHY_A6COgbEJYiFxRg+G-8LeJhQ@mail.gmail.com open hereSigned-off-by Christian Melendez <[email protected]>--- tools/perf/Documentation/perf-stat.txt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-)tools/perf/Documentation/perf-stat.txt +0
-0tools/perf/Documentation/perf-stat.txt user/system lands: · line 627
Quoted 7 lines
tools/perf/Documentation/perf-stat.txt +4
-0@@ -621,6 +621,16 @@ user/system lands: Those times are the very same as displayed by the 'time' tool. +We also display a clock-based timing metric that depends on the +target being monitored: + + 83723.452481 task-clock:u (msec) # 1.004 CPUs utilizedI'm afraid task-clock and any other software events don't support privilege filters or modifiers. So task-clock:u would be same as task-clock, but it can give a wrong idea that it only measured time in userspace.
Quoted 6 lines
Maybe the kernel can reject ones with modifiers but then it would have a compatibility issue. :(
So I think it's better to remove the ":u" modifier in the example output. Probably we need to change the perf not to add it to the software events.
Since I'll need to force push due to a missing Signed-off-by in a patch that had --- markers before the author's Signed-off-by, I'll remove the :u.
- Arnaldo
Quoted 21 lines
Thanks,
NamhyungQuoted 18 lines
tools/perf/Documentation/perf-stat.txt +7
-1+ +For a single task, task-clock reports a clock count specific to that +task. When the target is a CPU or the whole system (-a or -C), +cpu-clock is reported instead. cpu-clock is a high-resolution per-CPU +timer. See perf_event_open(2) for more details. + CSV FORMAT ----------@@ -671,4 +681,4 @@ that can be used for parsing. SEE ALSO -------- -linkperf:perf-top[1], linkperf:perf-list[1] +linkperf:perf-top[1], linkperf:perf-list[1], perf_event_open(2)Signature · 1 line
2.34.1