bcc-ucalls(8)

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

NAME

6       ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls - Summa‐
7       rize method calls from high-level languages and Linux syscalls.
8

SYNOPSIS

10       javacalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
11       perlcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
12       phpcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
13       pythoncalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
14       rubycalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
15       ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP]  [-L]  [-S]  [-v]
16       [-m] pid [interval]
17

DESCRIPTION

19       This  tool  summarizes  method  calls from high-level languages such as
20       Java, Perl, PHP, Python, and Ruby.  It  can  also  trace  Linux  system
21       calls.  Whenever a method is invoked, ucalls records the call count and
22       optionally the method's execution time (latency) and  displays  a  sum‐
23       mary.
24
25       This  uses in-kernel eBPF maps to store per process summaries for effi‐
26       ciency.
27
28       This tool relies on USDT probes embedded in many high-level  languages,
29       such  as  Java,  Perl,  PHP,  Python,  and  Ruby. It requires a runtime
30       instrumented with these probes, which in some cases  requires  building
31       from  source  with  a  USDT-specific flag, such as "--enable-dtrace" or
32       "--with-dtrace". For Java, method probes are not  enabled  by  default,
33       and   can   be   turned  on  by  running  the  Java  process  with  the
34       "-XX:+ExtendedDTraceProbes" flag. For PHP  processes,  the  environment
35       variable USE_ZEND_DTRACE must be set to 1.
36
37       Since this uses BPF, only the root user can use this tool.
38

REQUIREMENTS

40       CONFIG_BPF and bcc.
41

OPTIONS

43       -l {java,perl,php,python,ruby}
44              The language to trace. If not provided, only syscalls are traced
45              (when the -S option is used).
46
47       -T TOP Print only the top methods by frequency or latency.
48
49       -L     Collect method invocation latency (duration).
50
51       -S     Collect Linux syscalls frequency and timing.
52
53       -v     Print the resulting BPF program, for debugging purposes.
54
55       -m     Print times in milliseconds (the default is microseconds).
56
57       pid    The process id to trace.
58
59       interval
60              Print summary after this number of seconds  and  then  exit.  By
61              default, wait for Ctrl+C to terminate.
62

EXAMPLES

64       Trace the top 10 Ruby method calls:
65              # ucalls -T 10 -l ruby 1344
66
67       Trace  Python method calls and Linux syscalls including latency in mil‐
68       liseconds:
69              # ucalls -l python -mL 2020
70
71       Trace only syscalls and print a summary after 10 seconds:
72              # ucalls -S 788 10
73

OVERHEAD

75       Tracing individual method calls will produce a considerable overhead in
76       all  high-level languages. For languages with just-in-time compilation,
77       such as Java, the overhead can be more  considerable  than  for  inter‐
78       preted languages.  On the other hand, syscall tracing will typically be
79       tolerable for most processes, unless they have a very unusual  rate  of
80       system calls.
81

SOURCE

83       This is from bcc.
84
85              https://github.com/iovisor/bcc
86
87       Also  look  in  the  bcc distribution for a companion _example.txt file
88       containing example usage, output, and commentary for this tool.
89

OS

91       Linux
92

STABILITY

94       Unstable - in development.
95

AUTHOR

97       Sasha Goldshtein
98