bcc-profile(8)

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

NAME

6       profile  -  Profile  CPU  usage  by  sampling  stack traces. Uses Linux
7       eBPF/bcc.
8

SYNOPSIS

10       profile [-adfh] [-p PID | -L TID] [-U | -K] [-F FREQUENCY |  -c  COUNT]
11       [--stack-storage-size  COUNT]  [--cgroupmap CGROUPMAP] [--mntnsmap MAP‐
12       PATH] [duration]
13

DESCRIPTION

15       This is a CPU profiler. It works by taking samples of stack  traces  at
16       timed  intervals.  It  will help you understand and quantify CPU usage:
17       which code is executing, and by how much, including both user-level and
18       kernel code.
19
20       By  default  this  samples at 49 Hertz (samples per second), across all
21       CPUs.  This frequency can be tuned using a  command  line  option.  The
22       reason for 49, and not 50, is to avoid lock-step sampling.
23
24       This  is  also  an  efficient  profiler,  as stack traces are frequency
25       counted in kernel context, rather than passing each stack to user space
26       for  frequency  counting  there.  Only the unique stacks and counts are
27       passed to user space at the end of the profile,  greatly  reducing  the
28       kernel<->user transfer.
29

REQUIREMENTS

31       CONFIG_BPF and bcc.
32
33       This  also  requires Linux 4.9+ (BPF_PROG_TYPE_PERF_EVENT support). See
34       tools/old for an older version that may work on Linux 4.6 - 4.8.
35

OPTIONS

37       -h     Print usage message.
38
39       -p PID Trace this process ID only (filtered in-kernel).
40
41       -L TID Trace this thread ID only (filtered in-kernel).
42
43       -F frequency
44              Frequency to sample stacks.
45
46       -c count
47              Sample stacks every one in this many events.
48
49       -f     Print output in folded stack format.
50
51       -d     Include an output  delimiter  between  kernel  and  user  stacks
52              (either "--", or, in folded mode, "-").
53
54       -U     Show stacks from user space only (no kernel space stacks).
55
56       -K     Show stacks from kernel space only (no user space stacks).
57
58       -I     Include CPU idle stacks (by default these are excluded).
59
60       --stack-storage-size COUNT
61              The  maximum  number of unique stack traces that the kernel will
62              count (default 16384). If the  sampled  count  exceeds  this,  a
63              warning will be printed.
64
65       -C cpu Collect stacks only from specified cpu.
66
67       --cgroupmap MAPPATH
68              Profile cgroups in this BPF map only (filtered in-kernel).
69
70       duration
71              Duration to trace, in seconds.
72

EXAMPLES

74       Profile (sample) stack traces system-wide at 49 Hertz (samples per sec‐
75       ond) until Ctrl-C:
76              # profile
77
78       Profile for 5 seconds only:
79              # profile 5
80
81       Profile at 99 Hertz for 5 seconds only:
82              # profile -F 99 5
83
84       Profile 1 in a million events for 5 seconds only:
85              # profile -c 1000000 5
86
87       Profile process with PID 181 only:
88              # profile -p 181
89
90       Profile thread with TID 181 only:
91              # profile -L 181
92
93       Profile for 5 seconds and output in folded stack  format  (suitable  as
94       input  for flame graphs), including a delimiter between kernel and user
95       stacks:
96              # profile -df 5
97
98       Profile kernel stacks only:
99              # profile -K
100
101       Profile a set  of  cgroups  only  (see  special_filtering.md  from  bcc
102       sources for more details):
103              # profile --cgroupmap /sys/fs/bpf/test01
104

DEBUGGING

106       See  "[unknown]"  frames with bogus addresses? This can happen for dif‐
107       ferent reasons. Your best approach is to get Linux perf to work  first,
108       and  then  to  try  this tool. Eg, "perf record -F 49 -a -g -- sleep 1;
109       perf script", and to check for unknown frames there.
110
111       The most common reason for "[unknown]" frames is that the target  soft‐
112       ware  has  not  been  compiled with frame pointers, and so we can't use
113       that simple method for walking the stack. The fix in that  case  is  to
114       use  software  that  does have frame pointers, eg, gcc -fno-omit-frame-
115       pointer, or Java's -XX:+PreserveFramePointer.
116
117       Another reason for "[unknown]" frames is JIT compilers, which don't use
118       a  traditional  symbol  table.  The  fix  in that case is to populate a
119       /tmp/perf-PID.map file with the symbols, which this tool  should  read.
120       How you do this depends on the runtime (Java, Node.js).
121
122       If  you  seem  to have unrelated samples in the output, check for other
123       sampling or tracing tools that may be running. The current  version  of
124       this  tool can include their events if profiling happened concurrently.
125       Those samples may be filtered in a future version.
126

OVERHEAD

128       This is an efficient profiler, as stack traces are frequency counted in
129       kernel  context, and only the unique stacks and their counts are passed
130       to user space. Contrast this with the current "perf record  -F  99  -a"
131       method of profiling, which writes each sample to user space (via a ring
132       buffer), and then to the file system (perf.data), which must  be  post-
133       processed.
134
135       This  uses  perf_event_open  to  setup a timer which is instrumented by
136       BPF, and for efficiency it does not initialize the perf ring buffer, so
137       the redundant perf samples are not collected.
138
139       It's  expected  that  the  overhead  while  sampling  at  49 Hertz (the
140       default), across all CPUs, should be negligible. If  you  increase  the
141       sample rate, the overhead might begin to be measurable.
142

SOURCE

144       This is from bcc.
145
146              https://github.com/iovisor/bcc
147
148       Also  look  in  the bcc distribution for a companion _examples.txt file
149       containing example usage, output, and commentary for this tool.
150

OS

152       Linux
153

STABILITY

155       Unstable - in development.
156

AUTHOR

158       Brendan Gregg
159