| .TH ucalls 8 "2016-11-07" "USER COMMANDS" |
| .SH NAME |
| ucalls \- Summarize method calls from high-level languages and Linux syscalls. |
| .SH SYNOPSIS |
| .B ucalls [-l {java,python,ruby,php}] [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval] |
| .SH DESCRIPTION |
| This tool summarizes method calls from high-level languages such as Python, |
| Java, Ruby, and PHP. 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, Python, Ruby, and PHP. 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,python,ruby,php} |
| 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 STABILITY |
| Unstable - in development. |
| .SH AUTHOR |
| Sasha Goldshtein |
| .SH SEE ALSO |
| ustat(8), argdist(8) |