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] [-i INTERVAL] [-D DURATION] [-T] [-r] [-s]
11                     [-P] [-K] [-U] [-v] [-d] [-f] 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       -T     Include a timestamp with interval output.
42
43       -v     Show raw addresses.
44
45       -d     Print a delimiter ("--") in-between the kernel and user stacks.
46
47       --debug
48              Print the source of the BPF program when loading it (for  debug‐
49              ging purposes).
50
51       -i interval
52              Summary interval, in seconds.
53
54       -D duration
55              Total duration of trace, in seconds.  -f Folded output format.
56
57       -p PID Trace this process ID only (filtered in-kernel).
58
59
60       pattern
61              A  function  name, or a search pattern. Can include wild‐
62              cards ("*"). If the -r option is used, can include  regu‐
63              lar expressions.
64

EXAMPLES

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

OVERHEAD

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

SOURCE

126       This is from bcc.
127
128              https://github.com/iovisor/bcc
129
130       Also  look in the bcc distribution for a companion _examples.txt
131       file containing example usage, output, and commentary  for  this
132       tool.
133

OS

135       Linux
136

STABILITY

138       Unstable - in development.
139

AUTHOR

141       Brendan Gregg, Sasha Goldshtein
142