.TH ucalls 8  "2018-10-09" "USER COMMANDS"
.SH NAME
ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls, tclcalls \- Summarize method calls
from high-level languages and Linux syscalls.
.SH SYNOPSIS
.B javacalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.br
.B perlcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.br
.B phpcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.br
.B pythoncalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.br
.B rubycalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.br
.B tclcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.br
.B ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.SH DESCRIPTION
This tool summarizes method calls from high-level languages such as Java, Perl,
PHP, Python, Ruby, and Tcl. It can also trace Linux system calls. Whenever a method
is invoked, ucalls records the call count and optionally the method's execution
time (latency) and displays a summary.

This uses in-kernel eBPF maps to store per process summaries for efficiency.

This tool relies on USDT probes embedded in many high-level languages, such as
Java, Perl, PHP, Python, Ruby, and Tcl. It requires a runtime instrumented with these
probes, which in some cases requires building from source with a USDT-specific
flag, such as "--enable-dtrace" or "--with-dtrace". For Java, method probes are
not enabled by default, and can be turned on by running the Java process with
the "-XX:+ExtendedDTraceProbes" flag. For PHP processes, the environment
variable USE_ZEND_DTRACE must be set to 1.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bcc.
.SH OPTIONS
.TP
\-l {java,perl,php,python,ruby,tcl}
The language to trace. If not provided, only syscalls are traced (when the \-S
option is used).
.TP
\-T TOP
Print only the top methods by frequency or latency.
.TP
\-L
Collect method invocation latency (duration).
.TP
\-S
Collect Linux syscalls frequency and timing.
.TP
\-v
Print the resulting BPF program, for debugging purposes.
.TP
\-m
Print times in milliseconds (the default is microseconds).
.TP
pid
The process id to trace.
.TP
interval
Print summary after this number of seconds and then exit. By default, wait for
Ctrl+C to terminate.
.SH EXAMPLES
.TP
Trace the top 10 Ruby method calls:
#
.B ucalls -T 10 -l ruby 1344
.TP
Trace Python method calls and Linux syscalls including latency in milliseconds:
#
.B ucalls -l python -mL 2020
.TP
Trace only syscalls and print a summary after 10 seconds:
#
.B ucalls -S 788 10
.SH OVERHEAD
Tracing individual method calls will produce a considerable overhead in all
high-level languages. For languages with just-in-time compilation, such as
Java, the overhead can be more considerable than for interpreted languages.
On the other hand, syscall tracing will typically be tolerable for most
processes, unless they have a very unusual rate of system calls.
.SH SOURCE
This is from bcc.
.IP
https://github.com/iovisor/bcc
.PP
Also look in the bcc distribution for a companion _example.txt file containing
example usage, output, and commentary for this tool.
.SH OS
Linux
.SH AUTHOR
Sasha Goldshtein
.SH SEE ALSO
ustat(8), argdist(8)