man/man8/stackcount.8

.TH stackcount 8  "2016-01-14" "USER COMMANDS"
.SH NAME
stackcount \- Count kernel function calls and their stack traces. Uses Linux eBPF/bcc.
.SH SYNOPSIS
.B stackcount [\-h] [\-p PID] [\-i INTERVAL] [\-T] [\-r] pattern
.SH DESCRIPTION
stackcount traces kernel functions and frequency counts them with their entire
kernel stack trace, summarized in-kernel for efficiency. This allows higher
frequency events to be studied. The output consists of unique stack traces,
and their occurance counts.

The pattern is a string with optional '*' wildcards, similar to file globbing.
If you'd prefer to use regular expressions, use the \-r option.

The stack depth is currently limited to 10 (+1 for the current instruction
pointer).

This currently only works on x86_64. Check for future versions.
.SH REQUIREMENTS
CONFIG_BPF and bcc.
.SH OPTIONS
.TP
\-h
Print usage message.
.TP
\-r
Allow regular expressions for the search pattern. The default allows "*"
wildcards only.
.TP
\-s
Show address offsets.
.TP
\-T
Include a timestamp with interval output.
.TP
\-v
Show raw addresses.
.TP
\-i interval
Summary interval, in seconds.
.TP
\-p PID
Trace this process ID only (filtered in-kernel).
.TP
pattern
A kernel function name, or a search pattern. Can include wildcards ("*"). If the
\-r option is used, can include regular expressions.
.SH EXAMPLES
.TP
Count kernel stack traces for submit_bio():
#
.B stackcount submit_bio
.TP
Count kernel stack traces for ip_output():
#
.B stackcount ip_output
.TP
Show symbol offsets:
#
.B stackcount -s ip_output
.TP
Show offsets and raw addresses (verbose):
#
.B stackcount -sv ip_output
.TP
Count kernel stacks for kernel functions matching tcp_send*:
#
.B stackcount 'tcp_send*'
.TP
Same as previous, but using regular expressions:
#
.B stackcount -r '^tcp_send.*'
.TP
Output every 5 seconds, with timestamps:
#
.B stackcount -Ti 5 ip_output
.TP
Only count stacks when PID 185 is on-CPU:
#
.B stackcount -p 185 ip_output
.SH OVERHEAD
This summarizes unique stack traces in-kernel for efficiency, allowing it to
trace a higher rate of function calls than methods that post-process in user
space. The stack trace data is only copied to user space when the output is
printed, which usually only happens once. Given these techniques, I'd suspect
that call rates of < 10,000/sec would incur negligible overhead (for this
current version; future versions may improve this). Beyond that,
there will be a point where the overhead is measurable, as this does add
a number of instructions to each function call to walk and save stacks.
Test before production use. You can also use funccount to get a handle on
function call rates first.
.SH SOURCE
This is from bcc.
.IP
https://github.com/iovisor/bcc
.PP
Also look in the bcc distribution for a companion _examples.txt file containing
example usage, output, and commentary for this tool.
.SH OS
Linux
.SH STABILITY
Unstable - in development.
.SH AUTHOR
Brendan Gregg
.SH SEE ALSO
stacksnoop(8), funccount(8)