Skip to content

Commit 9f3662e

Browse files
myllynenyonghong-song
myllynen
authored and
yonghong-song
committed
utools Tcl support (iovisor#2005)
* Add perl* utools man page links Matches other languages, related to commit 9162be4. * uthreads: explicitly list C as supported uthreads supports C (pthreads) thread tracing, make this explicit. Earlier use of -l java and -l none unchanged. Add the corresponding man page and usage examples. * Add Tcl support for ucalls / uflow / uobjnew / ustat For some reason we need to use proc__args instead of proc__entry in uflow.py to get similar results as with e.g. Python.
1 parent b96ebcd commit 9f3662e

33 files changed

+139
-71
lines changed

‎man/man8/cthreads.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
uthreads.8

‎man/man8/perlcalls.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ucalls.8

‎man/man8/perlflow.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
uflow.8

‎man/man8/perlstat.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ustat.8

‎man/man8/tclcalls.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ucalls.8

‎man/man8/tclflow.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
uflow.8

‎man/man8/tclobjnew.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
uobjnew.8

‎man/man8/tclstat.8

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
ustat.8

‎man/man8/ucalls.8

+7-5
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
.TH ucalls 8 "2016-11-07" "USER COMMANDS"
1+
.TH ucalls 8 "2018-10-09" "USER COMMANDS"
22
.SH NAME
3-
ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls \- Summarize method calls
3+
ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls, tclcalls \- Summarize method calls
44
from high-level languages and Linux syscalls.
55
.SH SYNOPSIS
66
.B javacalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
@@ -13,17 +13,19 @@ from high-level languages and Linux syscalls.
1313
.br
1414
.B rubycalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
1515
.br
16+
.B tclcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
17+
.br
1618
.B ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
1719
.SH DESCRIPTION
1820
This tool summarizes method calls from high-level languages such as Java, Perl,
19-
PHP, Python, and Ruby. It can also trace Linux system calls. Whenever a method
21+
PHP, Python, Ruby, and Tcl. It can also trace Linux system calls. Whenever a method
2022
is invoked, ucalls records the call count and optionally the method's execution
2123
time (latency) and displays a summary.
2224

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

2527
This tool relies on USDT probes embedded in many high-level languages, such as
26-
Java, Perl, PHP, Python, and Ruby. It requires a runtime instrumented with these
28+
Java, Perl, PHP, Python, Ruby, and Tcl. It requires a runtime instrumented with these
2729
probes, which in some cases requires building from source with a USDT-specific
2830
flag, such as "--enable-dtrace" or "--with-dtrace". For Java, method probes are
2931
not enabled by default, and can be turned on by running the Java process with
@@ -35,7 +37,7 @@ Since this uses BPF, only the root user can use this tool.
3537
CONFIG_BPF and bcc.
3638
.SH OPTIONS
3739
.TP
38-
\-l {java,perl,php,python,ruby}
40+
\-l {java,perl,php,python,ruby,tcl}
3941
The language to trace. If not provided, only syscalls are traced (when the \-S
4042
option is used).
4143
.TP

‎man/man8/uflow.8

+7-5
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
.TH uflow 8 "2016-11-07" "USER COMMANDS"
1+
.TH uflow 8 "2018-10-09" "USER COMMANDS"
22
.SH NAME
3-
uflow, javaflow, perlflow, phpflow, pythonflow, rubyflow \- Print a flow graph of method
3+
uflow, javaflow, perlflow, phpflow, pythonflow, rubyflow, tclflow \- Print a flow graph of method
44
calls in high-level languages.
55
.SH SYNOPSIS
66
.B javaflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
@@ -13,13 +13,15 @@ calls in high-level languages.
1313
.br
1414
.B rubyflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
1515
.br
16-
.B uflow [-h] [-M METHOD] [-C CLAZZ] [-v] [-l {java,perl,php,python,ruby}] pid
16+
.B tclflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
17+
.br
18+
.B uflow [-h] [-M METHOD] [-C CLAZZ] [-v] [-l {java,perl,php,python,ruby,tcl}] pid
1719
.SH DESCRIPTION
1820
uflow traces method calls and prints them in a flow graph that can facilitate
1921
debugging and diagnostics by following the program's execution (method flow).
2022

2123
This tool relies on USDT probes embedded in many high-level languages, such as
22-
Java, Perl, PHP, Python, and Ruby. It requires a runtime instrumented with these
24+
Java, Perl, PHP, Python, Ruby, and Tcl. It requires a runtime instrumented with these
2325
probes, which in some cases requires building from source with a USDT-specific
2426
flag, such as "--enable-dtrace" or "--with-dtrace". For Java processes, the
2527
startup flag "-XX:+ExtendedDTraceProbes" is required. For PHP processes, the
@@ -41,7 +43,7 @@ name interpretation strongly depends on the language. For example, in Java use
4143
\-v
4244
Print the resulting BPF program, for debugging purposes.
4345
.TP
44-
{java,perl,php,python,ruby}
46+
{java,perl,php,python,ruby,tcl}
4547
The language to trace.
4648
.TP
4749
pid

‎man/man8/ugc.8

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,24 @@
1-
.TH ugc 8 "2016-11-07" "USER COMMANDS"
1+
.TH ugc 8 "2018-10-09" "USER COMMANDS"
22
.SH NAME
3-
ugc, javagc, pythongc, rubygc, nodegc \- Trace garbage collection events in
3+
ugc, javagc, nodegc, pythongc, rubygc \- Trace garbage collection events in
44
high-level languages.
55
.SH SYNOPSIS
66
.B javagc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
77
.br
8+
.B nodegc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
9+
.br
810
.B pythongc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
911
.br
1012
.B rubygc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
1113
.br
12-
.B nodegc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
13-
.br
14-
.B ugc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] [-l {java,python,ruby,node}] pid
14+
.B ugc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] [-l {java,node,python,ruby}] pid
1515
.SH DESCRIPTION
1616
This traces garbage collection events as they occur, including their duration
1717
and any additional information (such as generation collected or type of GC)
1818
provided by the respective language's runtime.
1919

2020
This tool relies on USDT probes embedded in many high-level languages, such as
21-
Node, Java, Python, and Ruby. It requires a runtime instrumented with these
21+
Java, Node, Python, and Ruby. It requires a runtime instrumented with these
2222
probes, which in some cases requires building from source with a USDT-specific
2323
flag, such as "--enable-dtrace" or "--with-dtrace".
2424

@@ -45,7 +45,7 @@ if you have thousands of collection events, specifying this filter will not
4545
reduce the amount of data that has to be transferred from the BPF program to
4646
the user-space script.
4747
.TP
48-
{java,python,ruby,node}
48+
{java,node,python,ruby}
4949
The language to trace.
5050
.TP
5151
pid

‎man/man8/uobjnew.8

+9-7
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,24 @@
1-
.TH uobjnew 8 "2016-11-07" "USER COMMANDS"
1+
.TH uobjnew 8 "2018-10-09" "USER COMMANDS"
22
.SH NAME
3-
uobjnew, javaobjnew, rubyobjnew, cobjnew \- Summarize object allocations in
3+
uobjnew, cobjnew, javaobjnew, rubyobjnew, tclobjnew \- Summarize object allocations in
44
high-level languages.
55
.SH SYNOPSIS
6+
.B cobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
7+
.br
68
.B javaobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
79
.br
810
.B rubyobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
911
.br
10-
.B cobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
12+
.B tclobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
1113
.br
12-
.B uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] [-l {java,ruby,c}] pid [interval]
14+
.B uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] [-l {c,java,ruby,tcl}] pid [interval]
1315
.SH DESCRIPTION
1416
uobjnew traces object allocations in high-level languages (including "malloc")
15-
and prints summaries of the most frequently allocated types by number of
17+
and prints summaries of the most frequently allocated types by number of
1618
objects or number of bytes.
1719

1820
This tool relies on USDT probes embedded in many high-level languages, such as
19-
Node, Java, Python, and Ruby. It requires a runtime instrumented with these
21+
C, Java, Ruby, and Tcl. It requires a runtime instrumented with these
2022
probes, which in some cases requires building from source with a USDT-specific
2123
flag, such as "--enable-dtrace" or "--with-dtrace". For Java, the Java process
2224
must be started with the "-XX:+ExtendedDTraceProbes" flag.
@@ -35,7 +37,7 @@ Print the top object types sorted by size.
3537
\-v
3638
Print the resulting BPF program, for debugging purposes.
3739
.TP
38-
{java,ruby,c}
40+
{c,java,ruby,tcl}
3941
The language to trace.
4042
.TP
4143
pid

‎man/man8/ustat.8

+10-8
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
.TH ustat 8 "2016-11-07" "USER COMMANDS"
1+
.TH ustat 8 "2018-10-09" "USER COMMANDS"
22
.SH NAME
3-
ustat, javastat, nodestat, perlstat, phpstat, pythonstat, rubystat \- Activity stats from
3+
ustat, javastat, nodestat, perlstat, phpstat, pythonstat, rubystat, tclstat \- Activity stats from
44
high-level languages.
55
.SH SYNOPSIS
66
.B javastat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
@@ -15,7 +15,9 @@ high-level languages.
1515
.br
1616
.B rubystat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
1717
.br
18-
.B ustat [-l {java,perl,python,ruby,node,php}] [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
18+
.B tclstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
19+
.br
20+
.B ustat [-l {java,node,perl,php,python,ruby,tcl}] [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
1921
.SH DESCRIPTION
2022
This is "top" for high-level language events, such as garbage collections,
2123
exceptions, thread creations, object allocations, method calls, and more. The
@@ -26,7 +28,7 @@ set of details.
2628
This uses in-kernel eBPF maps to store per process summaries for efficiency.
2729

2830
This tool relies on USDT probes embedded in many high-level languages, such as
29-
Java, Node, Perl, PHP, Python, and Ruby. It requires a runtime instrumented with
31+
Java, Node, Perl, PHP, Python, Ruby, and Tcl. It requires a runtime instrumented with
3032
these probes, which in some cases requires building from source with a
3133
USDT-specific flag, such as "--enable-dtrace" or "--with-dtrace". For Java,
3234
some probes are not enabled by default, and can be turned on by running the Java
@@ -43,7 +45,7 @@ Since this uses BPF, only the root user can use this tool.
4345
CONFIG_BPF and bcc.
4446
.SH OPTIONS
4547
.TP
46-
\-l {java,node,perl,php,python,ruby}
48+
\-l {java,node,perl,php,python,ruby,tcl}
4749
The language to trace. By default, all languages are traced.
4850
.TP
4951
\-C
@@ -107,10 +109,10 @@ THR/s
107109
Count of threads created during interval.
108110
.SH OVERHEAD
109111
When using this tool with high-frequency events, such as method calls, a very
110-
significant slow-down can be expected. However, many of the high-level
112+
significant slow-down can be expected. However, many of the high-level
111113
languages covered by this tool already have a fairly high per-method invocation
112-
cost, especially when running in interpreted mode. For the lower-frequency
113-
events, such as garbage collections or thread creations, the overhead should
114+
cost, especially when running in interpreted mode. For the lower-frequency
115+
events, such as garbage collections or thread creations, the overhead should
114116
not be significant. Specifically, when probing Java processes and not using the
115117
"-XX:+ExtendedDTraceProbes" flag, the most expensive probes are not emitted,
116118
and the overhead should be acceptable.

‎man/man8/uthreads.8

+8-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
.TH uthreads 8 "2016-11-07" "USER COMMANDS"
1+
.TH uthreads 8 "2018-10-09" "USER COMMANDS"
22
.SH NAME
3-
uthreads, javathreads \- Trace thread creation events in Java or pthreads.
3+
uthreads, cthreads, javathreads \- Trace thread creation events in Java or pthreads.
44
.SH SYNOPSIS
5+
.B cthreads [-h] [-v] pid
6+
.BR
57
.B javathreads [-h] [-v] pid
68
.BR
7-
.B uthreads [-h] [-l {java}] [-v] pid
9+
.B uthreads [-h] [-l {c,java,none}] [-v] pid
810
.SH DESCRIPTION
911
This traces thread creation events in Java processes, or pthread creation
1012
events in any process. When a thread is created, its name or start address
@@ -15,9 +17,9 @@ Since this uses BPF, only the root user can use this tool.
1517
CONFIG_BPF and bcc.
1618
.SH OPTIONS
1719
.TP
18-
\-l {java}
19-
The language to trace (currently only Java is supported). When no language is
20-
specified, only pthread creations are traced.
20+
\-l {c,java,none}
21+
The language to trace. C and none select tracing pthreads only, regardless
22+
of the runtime being traced.
2123
.TP
2224
\-v
2325
Print the resulting BPF program, for debugging purposes.

‎tools/cthreads_example.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
lib/uthreads_example.txt

‎tools/lib/ucalls.py

+8-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# ucalls Summarize method calls in high-level languages and/or system calls.
55
# For Linux, uses BCC, eBPF.
66
#
7-
# USAGE: ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP] [-L] [-S] [-v] [-m]
7+
# USAGE: ucalls [-l {java,perl,php,python,ruby,tcl}] [-h] [-T TOP] [-L] [-S] [-v] [-m]
88
# pid [interval]
99
#
1010
# Copyright 2016 Sasha Goldshtein
@@ -18,7 +18,7 @@
1818
from time import sleep
1919
import os
2020

21-
languages = ["java", "perl", "php", "python", "ruby"]
21+
languages = ["java", "perl", "php", "python", "ruby", "tcl"]
2222

2323
examples = """examples:
2424
./ucalls -l java 185 # trace Java calls and print statistics on ^C
@@ -94,6 +94,12 @@
9494
return_probe = "method__return"
9595
read_class = "bpf_usdt_readarg(1, ctx, &clazz);"
9696
read_method = "bpf_usdt_readarg(2, ctx, &method);"
97+
elif language == "tcl":
98+
# TODO Also consider probe cmd__entry and cmd__return with same arguments
99+
entry_probe = "proc__entry"
100+
return_probe = "proc__return"
101+
read_class = "" # no class/file info available
102+
read_method = "bpf_usdt_readarg(1, ctx, &method);"
97103
elif not language or language == "none":
98104
if not args.syscalls:
99105
print("Nothing to do; use -S to trace syscalls.")

‎tools/lib/ucalls_example.txt

+4-4
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ Demonstrations of ucalls.
22

33

44
ucalls summarizes method calls in various high-level languages, including Java,
5-
Perl, PHP, Python, Ruby, and Linux system calls. It displays statistics on the
6-
most frequently called methods, as well as the latency (duration) of these
5+
Perl, PHP, Python, Ruby, Tcl, and Linux system calls. It displays statistics on
6+
the most frequently called methods, as well as the latency (duration) of these
77
methods.
88

99
Through the syscalls support, ucalls can provide basic information on a
@@ -61,7 +61,7 @@ METHOD # CALLS
6161
USAGE message:
6262

6363
# ./ucalls.py -h
64-
usage: ucalls.py [-h] [-l {java,perl,php,python,ruby,none}] [-T TOP] [-L] [-S] [-v]
64+
usage: ucalls.py [-h] [-l {java,perl,php,python,ruby,tcl,none}] [-T TOP] [-L] [-S] [-v]
6565
[-m]
6666
pid [interval]
6767

@@ -73,7 +73,7 @@ positional arguments:
7373

7474
optional arguments:
7575
-h, --help show this help message and exit
76-
-l {java,perl,php,python,ruby,none}, --language {java,perl,php,python,ruby,none}
76+
-l {java,perl,php,python,ruby,tcl,none}, --language {java,perl,php,python,ruby,tcl,none}
7777
language to trace (if none, trace syscalls only)
7878
-T TOP, --top TOP number of most frequent/slow calls to print
7979
-L, --latency record method latency from enter to exit (except

‎tools/lib/uflow.py

+9-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# uflow Trace method execution flow in high-level languages.
55
# For Linux, uses BCC, eBPF.
66
#
7-
# USAGE: uflow [-C CLASS] [-M METHOD] [-v] {java,perl,php,python,ruby} pid
7+
# USAGE: uflow [-C CLASS] [-M METHOD] [-v] {java,perl,php,python,ruby,tcl} pid
88
#
99
# Copyright 2016 Sasha Goldshtein
1010
# Licensed under the Apache License, Version 2.0 (the "License")
@@ -18,7 +18,7 @@
1818
import time
1919
import os
2020

21-
languages = ["java", "perl", "php", "python", "ruby"]
21+
languages = ["java", "perl", "php", "python", "ruby", "tcl"]
2222

2323
examples = """examples:
2424
./uflow -l java 185 # trace Java method calls in process 185
@@ -161,6 +161,13 @@ def enable_probe(probe_name, func_name, read_class, read_method, is_return):
161161
enable_probe("cmethod__return", "ruby_creturn",
162162
"bpf_usdt_readarg(1, ctx, &clazz);",
163163
"bpf_usdt_readarg(2, ctx, &method);", is_return=True)
164+
elif language == "tcl":
165+
enable_probe("proc__args", "tcl_entry",
166+
"", # no class/file info available
167+
"bpf_usdt_readarg(1, ctx, &method);", is_return=False)
168+
enable_probe("proc__return", "tcl_return",
169+
"", # no class/file info available
170+
"bpf_usdt_readarg(1, ctx, &method);", is_return=True)
164171
else:
165172
print("No language detected; use -l to trace a language.")
166173
exit(1)

‎tools/lib/uflow_example.txt

+3-3
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Demonstrations of uflow.
44
uflow traces method entry and exit events and prints a visual flow graph that
55
shows how methods are entered and exited, similar to a tracing debugger with
66
breakpoints. This can be useful for understanding program flow in high-level
7-
languages such as Java, Perl, PHP, Python, and Ruby, which provide USDT
7+
languages such as Java, Perl, PHP, Python, Ruby, and Tcl which provide USDT
88
probes for method invocations.
99

1010

@@ -88,7 +88,7 @@ thread running on the same CPU.
8888
USAGE message:
8989

9090
# ./uflow -h
91-
usage: uflow.py [-h] [-l {java,perl,php,python,ruby}] [-M METHOD] [-C CLAZZ] [-v]
91+
usage: uflow.py [-h] [-l {java,perl,php,python,ruby,tcl}] [-M METHOD] [-C CLAZZ] [-v]
9292
pid
9393

9494
Trace method execution flow in high-level languages.
@@ -98,7 +98,7 @@ positional arguments:
9898

9999
optional arguments:
100100
-h, --help show this help message and exit
101-
-l {java,perl,php,python,ruby}, --language {java,perl,php,python,ruby}
101+
-l {java,perl,php,python,ruby,tcl}, --language {java,perl,php,python,ruby,tcl}
102102
language to trace
103103
-M METHOD, --method METHOD
104104
trace only calls to methods starting with this prefix

0 commit comments

Comments
 (0)