From 958bd4e1fc73c4669e85b785e14b8576f3814e42 Mon Sep 17 00:00:00 2001 From: Sandipan Das Date: Sat, 18 Nov 2017 01:54:41 +0530 Subject: [PATCH] Update 'tools/wakeuptime' documentation This updates the manpage and examples for 'tools/wakeuptime' so that they include descriptions of the new arguments. Signed-off-by: Sandipan Das --- man/man8/wakeuptime.8 | 21 ++++++++++++++------- tools/wakeuptime_example.txt | 27 +++++++++++++++++++-------- 2 files changed, 33 insertions(+), 15 deletions(-) diff --git a/man/man8/wakeuptime.8 b/man/man8/wakeuptime.8 index cbbc79829d46..8630ae4add89 100644 --- a/man/man8/wakeuptime.8 +++ b/man/man8/wakeuptime.8 @@ -2,7 +2,7 @@ .SH NAME wakeuptime \- Summarize sleep to wakeup time by waker kernel stack. Uses Linux eBPF/bcc. .SH SYNOPSIS -.B wakeuptime [\-h] [\-u] [\-p PID] [\-v] [\-f] [duration] +.B wakeuptime [\-h] [\-u] [\-p PID] [\-v] [\-f] [\-\-stack-storage-size STACK_STORAGE_SIZE] [\-m MIN_BLOCK_TIME] [\-M MAX_BLOCK_TIME] [duration] .SH DESCRIPTION This program shows the kernel stack traces for threads that woke up other blocked threads, along with the process names of the waker and target, along @@ -23,10 +23,8 @@ of the blocked thread. wakeuptime shows the stack trace of the waker thread. See http://www.brendangregg.com/FlameGraphs/offcpuflamegraphs.html -The stack depth is currently limited to 20, and the stack traces are kernel -mode only. Check for newer versions where either may be improved. - -This currently only works on x86_64. Check for future versions. +This tool only works on Linux 4.6+. It uses the new `BPF_STACK_TRACE` table +APIs to generate the in-kernel stack traces. .SH REQUIREMENTS CONFIG_BPF and bcc. .SH OPTIONS @@ -46,8 +44,17 @@ Show raw addresses (for non-folded format). \-p PID Trace this process ID only (filtered in-kernel). .TP +\-\-stack-storage-size STACK_STORAGE_SIZE +Change the number of unique stack traces that can be stored and displayed. +.TP duration Duration to trace, in seconds. +.TP +\-m MIN_BLOCK_TIME +The amount of time in microseconds over which we store traces (default 1) +.TP +\-M MAX_BLOCK_TIME +The amount of time in microseconds under which we store traces (default U64_MAX) .SH EXAMPLES .TP Trace all thread blocking events, and summarize (in-kernel) by kernel stack trace and total blocked time: @@ -77,8 +84,8 @@ printed. While these techniques greatly lower overhead, scheduler events are still a high frequency event, as they can exceed 1 million events per second, and so caution should still be used. Test before production use. -If the overhead is still a problem, take a look at the MINBLOCK_US tunable in -the code. If your aim is to chase down longer blocking events, then this could +If the overhead is still a problem, take a look at the min block option. +If your aim is to chase down longer blocking events, then this could be increased to filter shorter blocking events, further lowering overhead. .SH SOURCE This is from bcc. diff --git a/tools/wakeuptime_example.txt b/tools/wakeuptime_example.txt index 1f715b79fd27..dbade295c150 100644 --- a/tools/wakeuptime_example.txt +++ b/tools/wakeuptime_example.txt @@ -448,20 +448,31 @@ creating your "wakeup time flame graphs". USAGE message: # ./wakeuptime -h -usage: wakeuptime [-h] [-u] [-p PID] [-v] [-f] [duration] +usage: wakeuptime [-h] [-u] [-p PID] [-v] [-f] + [--stack-storage-size STACK_STORAGE_SIZE] + [-m MIN_BLOCK_TIME] [-M MAX_BLOCK_TIME] + [duration] Summarize sleep to wakeup time by waker kernel stack positional arguments: - duration duration of trace, in seconds + duration duration of trace, in seconds optional arguments: - -h, --help show this help message and exit - -u, --useronly user threads only (no kernel threads) - -p PID, --pid PID trace this PID only - -v, --verbose show raw addresses - -f, --folded output folded format - + -h, --help show this help message and exit + -u, --useronly user threads only (no kernel threads) + -p PID, --pid PID trace this PID only + -v, --verbose show raw addresses + -f, --folded output folded format + --stack-storage-size STACK_STORAGE_SIZE + the number of unique stack traces that can be stored + and displayed (default 1024) + -m MIN_BLOCK_TIME, --min-block-time MIN_BLOCK_TIME + the amount of time in microseconds over which we store + traces (default 1) + -M MAX_BLOCK_TIME, --max-block-time MAX_BLOCK_TIME + the amount of time in microseconds under which we + store traces (default U64_MAX) examples: ./wakeuptime # trace blocked time with waker stacks ./wakeuptime 5 # trace for 5 seconds only