bcc-stackcount(8)

1stackcount(8)               System Manager's Manual              stackcount(8)
2
3
4

NAME

6       stackcount  -  Count  function calls and their stack traces. Uses Linux
7       eBPF/bcc.
8

SYNOPSIS

10       stackcount [-h] [-p PID] [-c CPU] [-i INTERVAL] [-D DURATION] [-T]
11                     [-r] [-s] [-P] [-K] [-U] [-v] [-d] [-f] [--debug] pattern
12

DESCRIPTION

14       stackcount traces functions and frequency counts them with their entire
15       stack  trace,  kernel  stack  and  user stack, summarized in-kernel for
16       efficiency.  This allows higher frequency events  to  be  studied.  The
17       output consists of unique stack traces, and their occurrence counts. In
18       addition to kernel and user functions, kernel tracepoints and USDT tra‐
19       cepoint are also supported.
20
21       The  pattern  is  a string with optional '*' wildcards, similar to file
22       globbing.  If you'd prefer to  use  regular  expressions,  use  the  -r
23       option.
24
25       This tool only works on Linux 4.6+. Stack traces are obtained using the
26       new `BPF_STACK_TRACE` APIs.  For kernels older than 4.6, see  the  ver‐
27       sion under tools/old.
28
29

REQUIREMENTS

31       CONFIG_BPF and bcc.
32

OPTIONS

34       -h     Print usage message.
35
36       -r     Allow  regular  expressions  for the search pattern. The default
37              allows "*" wildcards only.
38
39       -s     Show address offsets.
40
41       -P     Display stacks separately for each process.
42
43       -K     Show kernel stack only.
44
45       -U     Show user stack only.
46
47       -T     Include a timestamp with interval output.
48
49       -v     Show raw addresses.
50
51       -d     Print a delimiter ("--") in-between the kernel and user stacks.
52
53       --debug
54              Print the source of the BPF program when loading it (for  debug‐
55              ging purposes).
56
57       -i interval
58              Summary interval, in seconds.
59
60       -D duration
61              Total duration of trace, in seconds.  -f Folded output format.
62
63       -p PID Trace this process ID only (filtered in-kernel).
64
65       -c CPU Trace this CPU only (filtered in-kernel).
66
67
68       pattern
69              A  function  name, or a search pattern. Can include wild‐
70              cards ("*"). If the -r option is used, can include  regu‐
71              lar expressions.
72

EXAMPLES

74       Count kernel and user stack traces for submit_bio():
75              # stackcount submit_bio
76
77       Count stacks with a delimiter for submit_bio():
78              # stackcount -d submit_bio
79
80       Count kernel stack trace only for submit_bio():
81              # stackcount -K submit_bio
82
83       Count user stack trace only for submit_bio():
84              # stackcount -U submit_bio
85
86       Count stack traces for ip_output():
87              # stackcount ip_output
88
89       Show symbol offsets:
90              # stackcount -s ip_output
91
92       Show offsets and raw addresses (verbose):
93              # stackcount -sv ip_output
94
95       Count stacks for kernel functions matching tcp_send*:
96              # stackcount 'tcp_send*'
97
98       Same as previous, but using regular expressions:
99              # stackcount -r '^tcp_send.*'
100
101       Output every 5 seconds, with timestamps:
102              # stackcount -Ti 5 ip_output
103
104       Only count stacks when PID 185 is on-CPU:
105              # stackcount -p 185 ip_output
106
107       Only count stacks for CPU 1:
108              # stackcount -c 1 put_prev_entity
109
110       Count  user  stacks  for dynamic heap allocations with malloc in
111       PID 185:
112              # stackcount -p 185 c:malloc
113
114       Count user stacks for thread creation (USDT tracepoint)  in  PID
115       185:
116              # stackcount -p 185 u:pthread:pthread_create
117
118       Count  stacks  for  context  switch events using a kernel trace‐
119       point:
120              # stackcount t:sched:sched_switch
121

OVERHEAD

123       This summarizes unique stack traces  in-kernel  for  efficiency,
124       allowing  it to trace a higher rate of function calls than meth‐
125       ods that post-process in user space. The  stack  trace  data  is
126       only copied to user space when the output is printed, which usu‐
127       ally only happens once. The stack walking  also  happens  in  an
128       optimized   code   path   in   the  kernel  thanks  to  the  new
129       BPF_STACK_TRACE table APIs, which should be more efficient  than
130       the  manual  walker  in  the eBPF tracer which older versions of
131       this script used. With this in mind, call rates of <  10,000/sec
132       would incur negligible overhead. Test before production use. You
133       can also use funccount to get a handle on  function  call  rates
134       first.
135

SOURCE

137       This is from bcc.
138
139              https://github.com/iovisor/bcc
140
141       Also  look in the bcc distribution for a companion _examples.txt
142       file containing example usage, output, and commentary  for  this
143       tool.
144

OS

146       Linux
147

STABILITY

149       Unstable - in development.
150

AUTHOR

152       Brendan Gregg, Sasha Goldshtein
153