Brendan Gregg | 38cef48 | 2016-01-15 17:26:30 -0800 | [diff] [blame] | 1 | .TH stackcount 8 "2016-01-14" "USER COMMANDS" |
| 2 | .SH NAME |
| 3 | stackcount \- Count kernel function calls and their stack traces. Uses Linux eBPF/bcc. |
| 4 | .SH SYNOPSIS |
| 5 | .B stackcount [\-h] [\-p PID] [\-i INTERVAL] [\-T] [\-r] pattern |
| 6 | .SH DESCRIPTION |
| 7 | stackcount traces kernel functions and frequency counts them with their entire |
| 8 | kernel stack trace, summarized in-kernel for efficiency. This allows higher |
| 9 | frequency events to be studied. The output consists of unique stack traces, |
Alex Bagehot | 3b9679a | 2016-02-06 16:01:02 +0000 | [diff] [blame^] | 10 | and their occurrence counts. |
Brendan Gregg | 38cef48 | 2016-01-15 17:26:30 -0800 | [diff] [blame] | 11 | |
| 12 | The pattern is a string with optional '*' wildcards, similar to file globbing. |
| 13 | If you'd prefer to use regular expressions, use the \-r option. |
| 14 | |
| 15 | The stack depth is currently limited to 10 (+1 for the current instruction |
| 16 | pointer). |
| 17 | |
| 18 | This currently only works on x86_64. Check for future versions. |
| 19 | .SH REQUIREMENTS |
| 20 | CONFIG_BPF and bcc. |
| 21 | .SH OPTIONS |
| 22 | .TP |
| 23 | \-h |
| 24 | Print usage message. |
| 25 | .TP |
| 26 | \-r |
| 27 | Allow regular expressions for the search pattern. The default allows "*" |
| 28 | wildcards only. |
| 29 | .TP |
| 30 | \-s |
| 31 | Show address offsets. |
| 32 | .TP |
| 33 | \-T |
| 34 | Include a timestamp with interval output. |
| 35 | .TP |
| 36 | \-v |
| 37 | Show raw addresses. |
| 38 | .TP |
| 39 | \-i interval |
| 40 | Summary interval, in seconds. |
| 41 | .TP |
| 42 | \-p PID |
| 43 | Trace this process ID only (filtered in-kernel). |
| 44 | .TP |
| 45 | pattern |
| 46 | A kernel function name, or a search pattern. Can include wildcards ("*"). If the |
| 47 | \-r option is used, can include regular expressions. |
| 48 | .SH EXAMPLES |
| 49 | .TP |
| 50 | Count kernel stack traces for submit_bio(): |
| 51 | # |
| 52 | .B stackcount submit_bio |
| 53 | .TP |
| 54 | Count kernel stack traces for ip_output(): |
| 55 | # |
| 56 | .B stackcount ip_output |
| 57 | .TP |
| 58 | Show symbol offsets: |
| 59 | # |
| 60 | .B stackcount -s ip_output |
| 61 | .TP |
| 62 | Show offsets and raw addresses (verbose): |
| 63 | # |
| 64 | .B stackcount -sv ip_output |
| 65 | .TP |
| 66 | Count kernel stacks for kernel functions matching tcp_send*: |
| 67 | # |
| 68 | .B stackcount 'tcp_send*' |
| 69 | .TP |
| 70 | Same as previous, but using regular expressions: |
| 71 | # |
| 72 | .B stackcount -r '^tcp_send.*' |
| 73 | .TP |
| 74 | Output every 5 seconds, with timestamps: |
| 75 | # |
| 76 | .B stackcount -Ti 5 ip_output |
| 77 | .TP |
| 78 | Only count stacks when PID 185 is on-CPU: |
| 79 | # |
| 80 | .B stackcount -p 185 ip_output |
| 81 | .SH OVERHEAD |
| 82 | This summarizes unique stack traces in-kernel for efficiency, allowing it to |
| 83 | trace a higher rate of function calls than methods that post-process in user |
| 84 | space. The stack trace data is only copied to user space when the output is |
| 85 | printed, which usually only happens once. Given these techniques, I'd suspect |
| 86 | that call rates of < 10,000/sec would incur negligible overhead (for this |
| 87 | current version; future versions may improve this). Beyond that, |
| 88 | there will be a point where the overhead is measurable, as this does add |
| 89 | a number of instructions to each function call to walk and save stacks. |
| 90 | Test before production use. You can also use funccount to get a handle on |
| 91 | function call rates first. |
| 92 | .SH SOURCE |
| 93 | This is from bcc. |
| 94 | .IP |
| 95 | https://github.com/iovisor/bcc |
| 96 | .PP |
| 97 | Also look in the bcc distribution for a companion _examples.txt file containing |
| 98 | example usage, output, and commentary for this tool. |
| 99 | .SH OS |
| 100 | Linux |
| 101 | .SH STABILITY |
| 102 | Unstable - in development. |
| 103 | .SH AUTHOR |
| 104 | Brendan Gregg |
| 105 | .SH SEE ALSO |
| 106 | stacksnoop(8), funccount(8) |