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.

man/man8/cthreads.8

@@ -0,0 +1 @@
+uthreads.8

man/man8/perlcalls.8

@@ -0,0 +1 @@
+ucalls.8

man/man8/perlflow.8

@@ -0,0 +1 @@
+uflow.8

man/man8/perlstat.8

@@ -0,0 +1 @@
+ustat.8

man/man8/tclcalls.8

@@ -0,0 +1 @@
+ucalls.8

man/man8/tclflow.8

@@ -0,0 +1 @@
+uflow.8

man/man8/tclobjnew.8

@@ -0,0 +1 @@
+uobjnew.8

man/man8/tclstat.8

@@ -0,0 +1 @@
+ustat.8

man/man8/ucalls.8

@@ -1,6 +1,6 @@
-.TH ucalls 8 "2016-11-07" "USER COMMANDS"
+.TH ucalls 8 "2018-10-09" "USER COMMANDS"
 .SH NAME
-ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls \- Summarize method calls
+ucalls, javacalls, perlcalls, phpcalls, pythoncalls, rubycalls, tclcalls \- Summarize method calls
 from high-level languages and Linux syscalls.
 .SH SYNOPSIS
 .B javacalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
@@ -13,17 +13,19 @@ from high-level languages and Linux syscalls.
 .br
 .B rubycalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
 .br
+.B tclcalls [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
+.br
 .B ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP] [-L] [-S] [-v] [-m] pid [interval]
 .SH DESCRIPTION
 This tool summarizes method calls from high-level languages such as Java, Perl,
-PHP, Python, and Ruby. It can also trace Linux system calls. Whenever a method
+PHP, Python, Ruby, and Tcl. 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, Perl, PHP, Python, and Ruby. It requires a runtime instrumented with these
+Java, Perl, PHP, Python, Ruby, and Tcl. 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
@@ -35,7 +37,7 @@ Since this uses BPF, only the root user can use this tool.
 CONFIG_BPF and bcc.
 .SH OPTIONS
 .TP
-\-l {java,perl,php,python,ruby}
+\-l {java,perl,php,python,ruby,tcl}
 The language to trace. If not provided, only syscalls are traced (when the \-S
 option is used).
 .TP

man/man8/uflow.8

@@ -1,6 +1,6 @@
-.TH uflow 8 "2016-11-07" "USER COMMANDS"
+.TH uflow 8 "2018-10-09" "USER COMMANDS"
 .SH NAME
-uflow, javaflow, perlflow, phpflow, pythonflow, rubyflow \- Print a flow graph of method
+uflow, javaflow, perlflow, phpflow, pythonflow, rubyflow, tclflow \- Print a flow graph of method
 calls in high-level languages.
 .SH SYNOPSIS
 .B javaflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
@@ -13,13 +13,15 @@ calls in high-level languages.
 .br
 .B rubyflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
 .br
-.B uflow [-h] [-M METHOD] [-C CLAZZ] [-v] [-l {java,perl,php,python,ruby}] pid
+.B tclflow [-h] [-M METHOD] [-C CLAZZ] [-v] pid
+.br
+.B uflow [-h] [-M METHOD] [-C CLAZZ] [-v] [-l {java,perl,php,python,ruby,tcl}] 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, Perl, PHP, Python, and Ruby. It requires a runtime instrumented with these
+Java, Perl, PHP, Python, Ruby, and Tcl. 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
@@ -41,7 +43,7 @@ name interpretation strongly depends on the language. For example, in Java use
 \-v
 Print the resulting BPF program, for debugging purposes.
 .TP
-{java,perl,php,python,ruby}
+{java,perl,php,python,ruby,tcl}
 The language to trace.
 .TP
 pid

man/man8/ugc.8

@@ -1,24 +1,24 @@
-.TH ugc 8 "2016-11-07" "USER COMMANDS"
+.TH ugc 8 "2018-10-09" "USER COMMANDS"
 .SH NAME
-ugc, javagc, pythongc, rubygc, nodegc \- Trace garbage collection events in
+ugc, javagc, nodegc, pythongc, rubygc \- Trace garbage collection events in
 high-level languages.
 .SH SYNOPSIS
 .B javagc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
 .br
+.B nodegc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
+.br
 .B pythongc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
 .br
 .B rubygc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
 .br
-.B nodegc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
-.br
-.B ugc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] [-l {java,python,ruby,node}] pid
+.B ugc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] [-l {java,node,python,ruby}] 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 
+Java, Node, 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".
 
@@ -45,7 +45,7 @@ if you have thousands of collection events, specifying this filter will not
 reduce the amount of data that has to be transferred from the BPF program to
 the user-space script.
 .TP
-{java,python,ruby,node}
+{java,node,python,ruby}
 The language to trace.
 .TP
 pid

man/man8/uobjnew.8

@@ -1,22 +1,24 @@
-.TH uobjnew 8 "2016-11-07" "USER COMMANDS"
+.TH uobjnew 8 "2018-10-09" "USER COMMANDS"
 .SH NAME
-uobjnew, javaobjnew, rubyobjnew, cobjnew \- Summarize object allocations in
+uobjnew, cobjnew, javaobjnew, rubyobjnew, tclobjnew \- Summarize object allocations in
 high-level languages.
 .SH SYNOPSIS
+.B cobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
+.br
 .B javaobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
 .br
 .B rubyobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
 .br
-.B cobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
+.B tclobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] pid [interval]
 .br
-.B uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] [-l {java,ruby,c}] pid [interval]
+.B uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] [-l {c,java,ruby,tcl}] 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 
+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 
+C, Java, Ruby, and Tcl. 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.
@@ -35,7 +37,7 @@ Print the top object types sorted by size.
 \-v
 Print the resulting BPF program, for debugging purposes.
 .TP
-{java,ruby,c}
+{c,java,ruby,tcl}
 The language to trace.
 .TP
 pid

man/man8/ustat.8

@@ -1,6 +1,6 @@
-.TH ustat 8 "2016-11-07" "USER COMMANDS"
+.TH ustat 8 "2018-10-09" "USER COMMANDS"
 .SH NAME
-ustat, javastat, nodestat, perlstat, phpstat, pythonstat, rubystat \- Activity stats from
+ustat, javastat, nodestat, perlstat, phpstat, pythonstat, rubystat, tclstat \- Activity stats from
 high-level languages.
 .SH SYNOPSIS
 .B javastat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
@@ -15,7 +15,9 @@ high-level languages.
 .br
 .B rubystat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
 .br
-.B ustat [-l {java,perl,python,ruby,node,php}] [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
+.B tclstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
+.br
+.B ustat [-l {java,node,perl,php,python,ruby,tcl}] [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
 .SH DESCRIPTION
 This is "top" for high-level language events, such as garbage collections,
 exceptions, thread creations, object allocations, method calls, and more. The
@@ -26,7 +28,7 @@ set of details.
 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, Node, Perl, PHP, Python, and Ruby. It requires a runtime instrumented with
+Java, Node, Perl, PHP, Python, Ruby, and Tcl. 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,
 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.
 CONFIG_BPF and bcc.
 .SH OPTIONS
 .TP
-\-l {java,node,perl,php,python,ruby}
+\-l {java,node,perl,php,python,ruby,tcl}
 The language to trace. By default, all languages are traced.
 .TP
 \-C
@@ -107,10 +109,10 @@ THR/s
 Count of threads created during interval.
 .SH OVERHEAD
 When using this tool with high-frequency events, such as method calls, a very
-significant slow-down can be expected. However, many of the high-level 
+significant slow-down can be expected. However, many of the high-level
 languages covered by this tool already have a fairly high per-method invocation
-cost, especially when running in interpreted mode. For the lower-frequency 
-events, such as garbage collections or thread creations, the overhead should 
+cost, especially when running in interpreted mode. For the lower-frequency
+events, such as garbage collections or thread creations, the overhead should
 not be significant. Specifically, when probing Java processes and not using the
 "-XX:+ExtendedDTraceProbes" flag, the most expensive probes are not emitted,
 and the overhead should be acceptable.

man/man8/uthreads.8

@@ -1,10 +1,12 @@
-.TH uthreads 8 "2016-11-07" "USER COMMANDS"
+.TH uthreads 8 "2018-10-09" "USER COMMANDS"
 .SH NAME
-uthreads, javathreads \- Trace thread creation events in Java or pthreads.
+uthreads, cthreads, javathreads \- Trace thread creation events in Java or pthreads.
 .SH SYNOPSIS
+.B cthreads [-h] [-v] pid
+.BR
 .B javathreads [-h] [-v] pid
 .BR
-.B uthreads [-h] [-l {java}] [-v] pid
+.B uthreads [-h] [-l {c,java,none}] [-v] pid
 .SH DESCRIPTION
 This traces thread creation events in Java processes, or pthread creation
 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.
 CONFIG_BPF and bcc.
 .SH OPTIONS
 .TP
-\-l {java}
-The language to trace (currently only Java is supported). When no language is
-specified, only pthread creations are traced.
+\-l {c,java,none}
+The language to trace. C and none select tracing pthreads only, regardless
+of the runtime being traced.
 .TP
 \-v
 Print the resulting BPF program, for debugging purposes.

tools/cthreads_example.txt

@@ -0,0 +1 @@
+lib/uthreads_example.txt

tools/lib/ucalls.py

@@ -4,7 +4,7 @@
 # ucalls Summarize method calls in high-level languages and/or system calls.
 # For Linux, uses BCC, eBPF.
 #
-# USAGE: ucalls [-l {java,perl,php,python,ruby}] [-h] [-T TOP] [-L] [-S] [-v] [-m]
+# USAGE: ucalls [-l {java,perl,php,python,ruby,tcl}] [-h] [-T TOP] [-L] [-S] [-v] [-m]
 # pid [interval]
 #
 # Copyright 2016 Sasha Goldshtein
@@ -18,7 +18,7 @@
 from time import sleep
 import os
 
-languages = ["java", "perl", "php", "python", "ruby"]
+languages = ["java", "perl", "php", "python", "ruby", "tcl"]
 
 examples = """examples:
  ./ucalls -l java 185 # trace Java calls and print statistics on ^C
@@ -94,6 +94,12 @@
  return_probe = "method__return"
  read_class = "bpf_usdt_readarg(1, ctx, &clazz);"
  read_method = "bpf_usdt_readarg(2, ctx, &method);"
+elif language == "tcl":
+ # TODO Also consider probe cmd__entry and cmd__return with same arguments
+ entry_probe = "proc__entry"
+ return_probe = "proc__return"
+ read_class = "" # no class/file info available
+ read_method = "bpf_usdt_readarg(1, ctx, &method);"
 elif not language or language == "none":
  if not args.syscalls:
  print("Nothing to do; use -S to trace syscalls.")

tools/lib/ucalls_example.txt

@@ -2,8 +2,8 @@ Demonstrations of ucalls.
 
 
 ucalls summarizes method calls in various high-level languages, including Java,
-Perl, PHP, Python, Ruby, and Linux system calls. It displays statistics on the
-most frequently called methods, as well as the latency (duration) of these
+Perl, PHP, Python, Ruby, Tcl, and Linux system calls. It displays statistics on
+the most frequently called methods, as well as the latency (duration) of these
 methods.
 
 Through the syscalls support, ucalls can provide basic information on a 
@@ -61,7 +61,7 @@ METHOD # CALLS
 USAGE message:
 
 # ./ucalls.py -h
-usage: ucalls.py [-h] [-l {java,perl,php,python,ruby,none}] [-T TOP] [-L] [-S] [-v]
+usage: ucalls.py [-h] [-l {java,perl,php,python,ruby,tcl,none}] [-T TOP] [-L] [-S] [-v]
  [-m]
  pid [interval]
 
@@ -73,7 +73,7 @@ positional arguments:
 
 optional arguments:
  -h, --help show this help message and exit
- -l {java,perl,php,python,ruby,none}, --language {java,perl,php,python,ruby,none}
+ -l {java,perl,php,python,ruby,tcl,none}, --language {java,perl,php,python,ruby,tcl,none}
  language to trace (if none, trace syscalls only)
  -T TOP, --top TOP number of most frequent/slow calls to print
  -L, --latency record method latency from enter to exit (except

tools/lib/uflow.py

@@ -4,7 +4,7 @@
 # uflow Trace method execution flow in high-level languages.
 # For Linux, uses BCC, eBPF.
 #
-# USAGE: uflow [-C CLASS] [-M METHOD] [-v] {java,perl,php,python,ruby} pid
+# USAGE: uflow [-C CLASS] [-M METHOD] [-v] {java,perl,php,python,ruby,tcl} pid
 #
 # Copyright 2016 Sasha Goldshtein
 # Licensed under the Apache License, Version 2.0 (the "License")
@@ -18,7 +18,7 @@
 import time
 import os
 
-languages = ["java", "perl", "php", "python", "ruby"]
+languages = ["java", "perl", "php", "python", "ruby", "tcl"]
 
 examples = """examples:
  ./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):
  enable_probe("cmethod__return", "ruby_creturn",
  "bpf_usdt_readarg(1, ctx, &clazz);",
  "bpf_usdt_readarg(2, ctx, &method);", is_return=True)
+elif language == "tcl":
+ enable_probe("proc__args", "tcl_entry",
+ "", # no class/file info available
+ "bpf_usdt_readarg(1, ctx, &method);", is_return=False)
+ enable_probe("proc__return", "tcl_return",
+ "", # no class/file info available
+ "bpf_usdt_readarg(1, ctx, &method);", is_return=True)
 else:
  print("No language detected; use -l to trace a language.")
  exit(1)

tools/lib/uflow_example.txt

@@ -4,7 +4,7 @@ Demonstrations of uflow.
 uflow traces method entry and exit events and prints a visual flow graph that
 shows how methods are entered and exited, similar to a tracing debugger with
 breakpoints. This can be useful for understanding program flow in high-level
-languages such as Java, Perl, PHP, Python, and Ruby, which provide USDT
+languages such as Java, Perl, PHP, Python, Ruby, and Tcl which provide USDT
 probes for method invocations.
 
 
@@ -88,7 +88,7 @@ thread running on the same CPU.
 USAGE message:
 
 # ./uflow -h
-usage: uflow.py [-h] [-l {java,perl,php,python,ruby}] [-M METHOD] [-C CLAZZ] [-v]
+usage: uflow.py [-h] [-l {java,perl,php,python,ruby,tcl}] [-M METHOD] [-C CLAZZ] [-v]
  pid
 
 Trace method execution flow in high-level languages.
@@ -98,7 +98,7 @@ positional arguments:
 
 optional arguments:
  -h, --help show this help message and exit
- -l {java,perl,php,python,ruby}, --language {java,perl,php,python,ruby}
+ -l {java,perl,php,python,ruby,tcl}, --language {java,perl,php,python,ruby,tcl}
  language to trace
  -M METHOD, --method METHOD
  trace only calls to methods starting with this prefix