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

NAME

6       ucalls,   javacalls,   perlcalls,   phpcalls,  pythoncalls,  rubycalls,
7       tclcalls - Summarize method calls from high-level languages  and  Linux
8       syscalls.
9

SYNOPSIS

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

DESCRIPTION

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

REQUIREMENTS

42       CONFIG_BPF and bcc.
43

OPTIONS

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

EXAMPLES

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

OVERHEAD

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

SOURCE

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

OS

93       Linux
94

STABILITY

96       Unstable - in development.
97

AUTHOR

99       Sasha Goldshtein
100

SEE ALSO

102       ustat(8), argdist(8)
103
104
105
106USER COMMANDS                     2018-10-09                         ucalls(8)
Impressum