linux/Documentation/trace
Steven Rostedt (VMware) 1e3bac71c5 tracing/histogram: Rename "cpu" to "common_cpu"
Currently the histogram logic allows the user to write "cpu" in as an
event field, and it will record the CPU that the event happened on.

The problem with this is that there's a lot of events that have "cpu"
as a real field, and using "cpu" as the CPU it ran on, makes it
impossible to run histograms on the "cpu" field of events.

For example, if I want to have a histogram on the count of the
workqueue_queue_work event on its cpu field, running:

 ># echo 'hist:keys=cpu' > events/workqueue/workqueue_queue_work/trigger

Gives a misleading and wrong result.

Change the command to "common_cpu" as no event should have "common_*"
fields as that's a reserved name for fields used by all events. And
this makes sense here as common_cpu would be a field used by all events.

Now we can even do:

 ># echo 'hist:keys=common_cpu,cpu if cpu < 100' > events/workqueue/workqueue_queue_work/trigger
 ># cat events/workqueue/workqueue_queue_work/hist
 # event histogram
 #
 # trigger info: hist:keys=common_cpu,cpu:vals=hitcount:sort=hitcount:size=2048 if cpu < 100 [active]
 #

 { common_cpu:          0, cpu:          2 } hitcount:          1
 { common_cpu:          0, cpu:          4 } hitcount:          1
 { common_cpu:          7, cpu:          7 } hitcount:          1
 { common_cpu:          0, cpu:          7 } hitcount:          1
 { common_cpu:          0, cpu:          1 } hitcount:          1
 { common_cpu:          0, cpu:          6 } hitcount:          2
 { common_cpu:          0, cpu:          5 } hitcount:          2
 { common_cpu:          1, cpu:          1 } hitcount:          4
 { common_cpu:          6, cpu:          6 } hitcount:          4
 { common_cpu:          5, cpu:          5 } hitcount:         14
 { common_cpu:          4, cpu:          4 } hitcount:         26
 { common_cpu:          0, cpu:          0 } hitcount:         39
 { common_cpu:          2, cpu:          2 } hitcount:        184

Now for backward compatibility, I added a trick. If "cpu" is used, and
the field is not found, it will fall back to "common_cpu" and work as
it did before. This way, it will still work for old programs that use
"cpu" to get the actual CPU, but if the event has a "cpu" as a field, it
will get that event's "cpu" field, which is probably what it wants
anyway.

I updated the tracefs/README to include documentation about both the
common_timestamp and the common_cpu. This way, if that text is present in
the README, then an application can know that common_cpu is supported over
just plain "cpu".

Link: https://lkml.kernel.org/r/20210721110053.26b4f641@oasis.local.home

Cc: Namhyung Kim <namhyung@kernel.org>
Cc: Ingo Molnar <mingo@kernel.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: stable@vger.kernel.org
Fixes: 8b7622bf94 ("tracing: Add cpu field for hist triggers")
Reviewed-by: Tom Zanussi <zanussi@kernel.org>
Reviewed-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
2021-07-23 08:44:47 -04:00
..
coresight docs: trace: coresight: coresight.rst: avoid using ReST :doc:foo markup 2021-06-17 13:24:39 -06:00
postprocess tweewide: Fix most Shebang lines 2020-12-08 23:30:04 +09:00
boottime-trace.rst Documentation: tracing: Add per-group/all events enablement desciption 2021-06-10 11:16:21 -04:00
events-kmem.rst mm/lru: revise the comments of lru_lock 2020-12-15 14:48:04 -08:00
events-msr.rst Replace HTTP links with HTTPS ones: documentation 2020-06-08 09:30:19 -06:00
events-nmi.rst
events-power.rst PM: QoS: Simplify definitions of CPU latency QoS trace events 2020-02-13 11:26:39 +01:00
events.rst docs: trace: fix event state structure name 2020-12-08 10:19:18 -07:00
ftrace-design.rst sh/ftrace: Move arch_ftrace_nmi_{enter,exit} into nmi exception 2020-05-19 15:51:18 +02:00
ftrace-uses.rst ftrace/documentation: Fix RST C code blocks 2020-11-18 11:45:23 -05:00
ftrace.rst docs: trace: ftrace.rst: avoid using ReST :doc:foo markup 2021-06-17 13:24:39 -06:00
function-graph-fold.vim
histogram-design.rst Documentation: trace/histogram-design: drop doubled words 2020-07-05 14:40:55 -06:00
histogram.rst tracing/histogram: Rename "cpu" to "common_cpu" 2021-07-23 08:44:47 -04:00
hwlat_detector.rst trace/hwlat: Implement the per-cpu mode 2021-06-25 18:23:22 -04:00
index.rst trace: Add timerlat tracer 2021-06-25 19:57:24 -04:00
intel_th.rst docs: trace: fix a typo 2020-08-11 10:22:15 -06:00
kprobes.rst kprobes: Remove kprobe::fault_handler 2021-06-01 16:00:08 +02:00
kprobetrace.rst Updates for tracing and bootconfig: 2020-10-15 15:51:28 -07:00
mmiotrace.rst Replace HTTP links with HTTPS ones: documentation 2020-06-08 09:30:19 -06:00
osnoise-tracer.rst Documentation: Fix a typo on trace/osnoise-tracer 2021-06-28 14:12:27 -04:00
ring-buffer-design.rst docs: trace: ring-buffer-design.rst: use the new SPDX tag 2020-09-24 11:07:44 -06:00
stm.rst Documentation: trace/stm: drop doubled words 2020-07-05 14:40:55 -06:00
sys-t.rst stm class: Document the MIPI SyS-T protocol usage 2018-10-11 12:12:55 +02:00
timerlat-tracer.rst trace: Add timerlat tracer 2021-06-25 19:57:24 -04:00
tracepoint-analysis.rst docs: Fix some broken references 2018-06-15 18:10:01 -03:00
tracepoints.rst tracepoints: Add helper to test if tracepoint is enabled in a header 2020-09-25 18:01:35 -04:00
uprobetracer.rst Documentation: tracing: Add %return suffix description 2020-09-21 21:06:03 -04:00