A new chapter describing how to use trace event stack filter is added to the documentation. Signed-off-by: Sicheng Liu <lsc2001@xxxxxxxxxxx> --- Documentation/trace/events.rst | 88 ++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/Documentation/trace/events.rst b/Documentation/trace/events.rst index 759907c20e75..718a6d078e24 100644 --- a/Documentation/trace/events.rst +++ b/Documentation/trace/events.rst @@ -350,6 +350,94 @@ To add more PIDs without losing the PIDs already included, use '>>'. # echo 123 244 1 >> set_event_pid +5.6 Stack filters +--------------------- + +Trace events can be filtered by their call stacks. There could exist +various paths to tigger an trace event, but people sometimes only care +about some of them. Once the stack filter is set, call stack of the +corresponding event will be compared with the stack filter. An event +with matched call stack will appear in the trace output and the rest will +be discarded. + +5.6.1 Expression syntax +------------------------ + +Stack filters have the form (in regular expression style) below:: + + '!'?((function|'**')'/')*(function|'**') + +In the expression, '!' means negating the filter and '**' matches any +call path (maybe empty). The top of call stack will be ``stack_filter_match``, +which means the call path will be something like ``**/stack_filter_match``. + +A stack filter matches if the call stack contains it, which means that +``ret_from_fork/**/schedule`` has the same effect as +``**/ret_from_fork/**/schedule/**``. + +A call stack is matched successfully if the following conditions are +met simultaneously: +[1] It matches any positive stack filter. +[2] It doesn't match any negative stack filter. +If no positive filter are set, condition 1 don't need to be satisified. + +5.6.2 Setting stack filters +--------------------------- + +Stack filters are add by echo commands to 'stack_filter' file for a given +event, and unset by echo 0 or blank string to the same file. + +An usage example (on x86_64 platform): + +The call stack contains ``ret_from_fork`` but not ``do_syscall_64``:: + + # cd /sys/kernel/tracing/events/sched/sched_switch + # echo 'ret_from_fork' > stack_filter + # echo '!do_syscall_64' >> stack_filter + # cat stack_filter + +Another example (on arm64 platform): + +Set up a kprobe:: + + # echo 1 > /sys/kernel/tracing/options/stacktrace + # echo 'p alloc_pages' > /sys/kernel/tracing/kprobe_events + +The call stack contains ``copy_process``:: + + # echo 'copy_process' > \ + /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter + +The call stack doesn't contain ``copy_process``:: + + # echo '!copy_process' > \ + /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter + +The call stack contains ``copy_process`` or ``do_exit``, +but not ``free_pgtables``:: + + # echo 'copy_process' > \ + /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter + # echo 'do_exit' >> \ + /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter + # echo '!free_pgtables' >> \ + /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter + +The call stack contains ``invoke_syscall -> ... -> copy_process``:: + + # echo 'invoke_syscall/**/copy_process' > \ + /sys/kernel/tracing/events/kprobes/p_alloc_pages_0/stack_filter + +Enable the kprobe event and check the trace log:: + + # echo 1 > /sys/kernel/tracing/events/kprobes/enable + # cat /sys/kernel/tracing/trace + +Disable the stack filter:: + + # echo 0 > stack_filter + or + # echo > stack_filter 6. Event triggers ================= -- 2.25.1
