| .TH uflow 8 "2016-11-07" "USER COMMANDS" |
| .SH NAME |
| uflow \- Print a flow graph of method calls in high-level languages. |
| .SH SYNOPSIS |
| .B uflow [-h] [-M METHOD] [-C CLAZZ] [-v] {java,python,ruby,php} pid |
| .SH DESCRIPTION |
| uflow traces method calls and prints them in a flow graph that can facilitate |
| debugging and diagnostics by following the program's execution (method flow). |
| |
| 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 processes, the |
| startup flag "-XX:+ExtendedDTraceProbes" is required. 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 |
| \-M METHOD |
| Print only method calls where the method name begins with this string. |
| .TP |
| \-C CLAZZ |
| Print only method calls where the class name begins with this string. The class |
| name interpretation strongly depends on the language. For example, in Java use |
| "package/subpackage/ClassName" to refer to classes. |
| .TP |
| \-v |
| Print the resulting BPF program, for debugging purposes. |
| .TP |
| {java,python,ruby,php} |
| The language to trace. |
| .TP |
| pid |
| The process id to trace. |
| .SH EXAMPLES |
| .TP |
| Follow method flow in a Ruby process: |
| # |
| .B uflow ruby 148 |
| .TP |
| Follow method flow in a Java process where the class name is java.lang.Thread: |
| # |
| .B uflow -C java/lang/Thread java 1802 |
| .SH FIELDS |
| .TP |
| CPU |
| The CPU number on which the method was invoked. This is useful to easily see |
| where the output skips to a different CPU. |
| .TP |
| PID |
| The process id. |
| .TP |
| TID |
| The thread id. |
| .TP |
| TIME |
| The duration of the method call. |
| .TP |
| METHOD |
| The method name. |
| .SH OVERHEAD |
| This tool has extremely high overhead because it prints every method call. For |
| some scenarios, you might see lost samples in the output as the tool is unable |
| to keep up with the rate of data coming from the kernel. Filtering by class |
| or method prefix can help reduce the amount of data printed, but there is still |
| a very high overhead in the collection mechanism. Do not use for performance- |
| sensitive production scenarios, and always test first. |
| .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 |
| trace(8), ustat(8) |