Skip to contentSkip to conversation

perf stat: worth documenting task-clock/cpu-clock in perf-stat.txt?

PATCH Applied Christian Melendez 5 participants 8 messages Sep 22 – Sep 24 perf events

lore
Share & tools
lore
#0 lore raw

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

reviewer
#1 lore raw
Quoted 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

#2 lore raw

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
index f334aabdc809..c0d6c344f9eb 100644
@@ -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
#3 lore raw

Re: [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
reviewer Reviewed-by on v1 1/1
#4 lore raw

Re: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS

In reply to Christian Melendez
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.

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
index f334aabdc809..c0d6c344f9eb 100644
@@ -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

maintainer Applied
#5 lore raw

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.

Thanks, applied to perf-tools-next, for v7.4.

- Arnaldo

maintainer
#6 lore raw

Re: [PATCH] perf stat: document task-clock/cpu-clock in TIMINGS

In reply to Christian Melendez

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.

---
 tools/perf/Documentation/perf-stat.txt | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)
tools/perf/Documentation/perf-stat.txt +0 -0
index f334aabdc809..c0d6c344f9eb 100644

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
#7 lore raw

Re: [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.

---
 tools/perf/Documentation/perf-stat.txt | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)
tools/perf/Documentation/perf-stat.txt +0 -0
index f334aabdc809..c0d6c344f9eb 100644

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.

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,
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