blob: 63b7c758367195c3b25b9e220c52e563b123a306 [file] [log] [blame]
.TH uflow 8 "2016-11-07" "USER COMMANDS"
.SH NAME
uflow, javaflow, pythonflow, rubyflow, phpflow \- Print a flow graph of method
calls in high-level languages.
.SH SYNOPSIS
.B javaflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
.br
.B pythonflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
.br
.B rubyflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
.br
.B phpflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
.br
.B uflow [-h] [-M METHOD] [-C CLAZZ] [-v] [-l {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)