Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

USDT tools for higher level languages #774

Merged
merged 29 commits into from Dec 19, 2016
Merged
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
c13d14f
ucalls: Summarize method calls with USDT
goldshtn Oct 17, 2016
e5d9d99
ugc: Monitor GC events in high-level languages
goldshtn Oct 17, 2016
ddef09a
ugc: Add description messages for GC events
goldshtn Oct 20, 2016
c0217a9
tools: Script skeletons
goldshtn Oct 20, 2016
8853347
ugc: Node support
goldshtn Oct 25, 2016
a245c79
ucalls: Trace syscalls
goldshtn Oct 25, 2016
989057d
uthreads: Trace thread creation/destruction events
goldshtn Oct 25, 2016
bf0cf12
uthreads: Add pthread support
goldshtn Oct 25, 2016
4cebb42
ugc: Fix order of arguments in usage comment
goldshtn Oct 25, 2016
6e5c621
ucalls: TODO reminder to probe C methods
goldshtn Oct 25, 2016
2e7e240
uobjnew: Summarize object allocations
goldshtn Oct 25, 2016
dfab8f5
python: Do not call USDT.get_text() twice
goldshtn Oct 25, 2016
7040f44
python: Expose active probes from USDT object
goldshtn Oct 25, 2016
1cba422
ustat: Activity stats from high-level languages
goldshtn Oct 25, 2016
bee71b2
tools: Add block comments to u* scripts
goldshtn Oct 26, 2016
9f6d03b
ustat: Sort by pid if no other sort column provided
goldshtn Oct 26, 2016
087dd73
ustat: Change 'count' argument type to int
goldshtn Oct 26, 2016
e725b14
uflow: Trace method execution flow
goldshtn Oct 26, 2016
d8c7f47
ustat: Replace \0 with spaces in cmdline
goldshtn Oct 27, 2016
fb3c471
ustat: Graceful error handling
goldshtn Oct 27, 2016
5a9b154
ustat: Add man page and companion example file
goldshtn Oct 29, 2016
070c1df
ucalls: Add man page and companion examples file
goldshtn Oct 29, 2016
ea77193
ugc: Add man page and companion examples file
goldshtn Oct 29, 2016
7160f8a
uobjnew: Add man page and companion examples file
goldshtn Oct 29, 2016
c0a6352
uthreads: Add man page and companion examples file
goldshtn Oct 29, 2016
af05e5a
uflow: Add man page and companion examples file
goldshtn Oct 29, 2016
0a5ea58
README: Add u* tools based on USDT probes
goldshtn Oct 29, 2016
39ace6f
uobjnew: Attach uprobe only to the requested process
goldshtn Dec 19, 2016
d4a4248
uobjnew: Remove -l switch from examples
goldshtn Dec 19, 2016
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

@@ -129,6 +129,12 @@ Examples:
- tools/[tplist](tools/tplist.py): Display kernel tracepoints or USDT probes and their formats. [Examples](tools/tplist_example.txt).
- tools/[trace](tools/trace.py): Trace arbitrary functions, with filters. [Examples](tools/trace_example.txt)
- tools/[ttysnoop](tools/ttysnoop.py): Watch live output from a tty or pts device. [Examples](tools/ttysnoop_example.txt)
- tools/[ucalls](tools/ucalls.py): Summarize method calls or Linux syscalls in high-level languages. [Examples](tools/ucalls_example.txt)
- tools/[uflow](tools/uflow.py): Print a method flow graph in high-level languages. [Examples](tools/uflow_example.txt)
- tools/[ugc](tools/ugc.py): Trace garbage collection events in high-level languages. [Examples](tools/ugc_example.txt)
- tools/[uobjnew](tools/uobjnew.py): Summarize object allocation events by object type and number of bytes allocated. [Examples](tools/uobjnew_example.txt)
- tools/[ustat](tools/ustat.py): Collect events such as GCs, thread creations, object allocations, exceptions and more in high-level languages. [Examples](tools/ustat_example.txt)
- tools/[uthreads](tools/uthreads.py): Trace thread creation events in Java and raw pthreads. [Examples](tools/uthreads_example.txt)
- tools/[vfscount](tools/vfscount.py) tools/[vfscount.c](tools/vfscount.c): Count VFS calls. [Examples](tools/vfscount_example.txt).
- tools/[vfsstat](tools/vfsstat.py) tools/[vfsstat.c](tools/vfsstat.c): Count some VFS calls, with column output. [Examples](tools/vfsstat_example.txt).
- tools/[wakeuptime](tools/wakeuptime.py): Summarize sleep to wakeup time by waker kernel stack. [Examples](tools/wakeuptime_example.txt).
@@ -0,0 +1,84 @@
.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}] [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
.SH DESCRIPTION
This tool summarizes method calls from high-level languages such as Python,
Java, and Ruby. 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
Node, Java, Python, and Ruby. 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.

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,node}
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)
@@ -0,0 +1,84 @@
.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} 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
Node, Java, Python, and Ruby. 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.

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}
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)
@@ -0,0 +1,71 @@
.TH ugc 8 "2016-11-07" "USER COMMANDS"
.SH NAME
ugc \- Trace garbage collection events in high-level languages.
.SH SYNOPSIS
.B ugc [-h] [-v] [-m] {java,python,ruby,node} pid
.SH DESCRIPTION
This traces garbage collection events as they occur, including their duration
and any additional information (such as generation collected or type of GC)
provided by the respective language's runtime.

This tool relies on USDT probes embedded in many high-level languages, such as
Node, Java, Python, and Ruby. 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".

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bcc.
.SH OPTIONS
.TP
\-v
Print the resulting BPF program, for debugging purposes.
.TP
\-m
Print times in milliseconds. The default is microseconds.
.TP
{java,python,ruby,node}
The language to trace.
.TP
pid
The process id to trace.
.SH EXAMPLES
.TP
Trace garbage collections in a specific Node process:
#
.B ugc node 148
.TP
Trace garbage collections in a specific Java process, and print GC times in
milliseconds:
#
.B ugc -m java 6004
.SH FIELDS
.TP
START
The start time of the GC, in seconds from the beginning of the trace.
.TP
DESCRIPTION
The runtime-provided description of this garbage collection event.
.TP
TIME
The duration of the garbage collection event.
.SH OVERHEAD
Garbage collection events, even if frequent, should not produce a considerable
overhead when traced because they are still not very common. Even hundreds of
GCs per second (which is a very high rate) will still produce a fairly
negligible overhead.
.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), uobjnew(8)
@@ -0,0 +1,79 @@
.TH uobjnew 8 "2016-11-07" "USER COMMANDS"
.SH NAME
uobjnew \- Summarize object allocations in high-level languages.
.SH SYNOPSIS
.B uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] {java,ruby,c} pid [interval]
.SH DESCRIPTION
uobjnew traces object allocations in high-level languages (including "malloc")
and prints summaries of the most frequently allocated types by number of
objects or number of bytes.

This tool relies on USDT probes embedded in many high-level languages, such as
Node, Java, Python, and Ruby. 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, the Java process
must be started with the "-XX:+ExtendedDTraceProbes" flag.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bcc.
.SH OPTIONS
.TP
\-C TOP_COUNT
Print the top object types sorted by number of instances.
.TP
\-S TOP_SIZE
Print the top object types sorted by size.
.TP
\-v
Print the resulting BPF program, for debugging purposes.
.TP
{java,ruby,c}
The language to trace.
.TP
pid
The process id to trace.
.TP
interval
Wait this many seconds and then print the summary and exit. By default, wait
for Ctrl+C to exit.
.SH EXAMPLES
.TP
Trace object allocations in a Ruby process:
#
.B uobjnew ruby 148
.TP
Trace object allocations from "malloc" and print the top 10 by total size:
#
.B uobjnew -S 10 c 1788
.SH FIELDS
.TP
TYPE
The object type being allocated. For C (malloc), this is the block size.
.TP
ALLOCS
The number of objects allocated.
.TP
BYTES
The number of bytes allocated.
.SH OVERHEAD
Object allocation events are quite frequent, and therefore the overhead from
running this tool can be considerable. Use with caution and make sure to
test before using in a production environment. Nonetheless, even thousands of
allocations per second will likely produce a reasonable overhead when
investigating a problem.
.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), ugc(8), memleak(8)
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.