fix execsnoop, add man page

README.md

@@ -149,6 +149,7 @@ bpftrace contains various tools, which also serve as examples of programming in
 - tools/[biosnoop.bt](tools/biosnoop.bt): Block I/O tracing tool, showing per I/O latency. [Examples](tools/biosnoop_example.txt).
 - tools/[capable.bt](tools/capable.bt): Trace security capabilitiy checks. [Examples](tools/capable_example.txt).
 - tools/[cpuwalk.bt](tools/cpuwalk.bt): Sample which CPUs are executing processes. [Examples](tools/cpuwalk_example.txt).
+- tools/[execsnoop.bt](tools/execsnoop.bt): Trace new processes via exec() syscalls. [Examples](tools/execsnoop_example.txt).
 - tools/[gethostlatency.bt](tools/gethostlatency.bt): Show latency for getaddrinfo/gethostbyname[2] calls. [Examples](tools/gethostlatency_example.txt).
 - tools/[loads.bt](tools/loads.bt): Print load averages. [Examples](tools/loads_example.txt).
 - tools/[pidpersec.bt](tools/pidpersec.bt): Count new procesess (via fork). [Examples](tools/pidpersec_example.txt).

man/man8/execsnoop.8

+.TH execsnoop 8  "2018-09-11" "USER COMMANDS"
+.SH NAME
+execsnoop.bt \- Trace signals issued by the kill() syscall. Uses bpftrace/eBPF.
+.SH SYNOPSIS
+.B execsnoop.bt
+.SH DESCRIPTION
+This traces when processes call exec() (execve()). It is handy for identifying new
+processes created via the usual fork()->exec() sequence. Note that the
+return value is not currently traced, so the exec() may have failed.
+
+This tool is useful for debugging shell scripts, including application startup.
+It is also useful for identifying a type of performance issue: a flood of
+short-lived processes, that end quickly and aren't readily visible in top(1).
+
+Since this uses BPF, only the root user can use this tool.
+.SH REQUIREMENTS
+CONFIG_BPF and bpftrace.
+.SH EXAMPLES
+.TP
+Trace all new processes calling execve():
+#
+.B execsnoop.bt
+.SH FIELDS
+.TP
+TIME
+Time of the exec() call, in milliseconds since program start.
+.TP
+PID
+Process ID
+.TP
+ARGS
+Process name and arguments (16 word maximum).
+.SH OVERHEAD
+This traces the execve() tracepoint and prints output for each event. As the
+rate of this is generally expected to be low (< 100/s), the overhead is also
+expected to be negligible. If you have an application that is spawning
+a high rate of new processes for a reason (large build process), this could
+cause a small amount of overhead: test and understand overhead before
+use.
+.SH SOURCE
+This is from bpftrace.
+.IP
+https://github.com/iovisor/bpftrace
+.PP
+Also look in the bpftrace distribution for a companion _examples.txt file containing
+example usage, output, and commentary for this tool.
+
+This is a bpftrace version of the bcc tool of the same name. The bcc tool
+provides more fields and options to customize the output.
+.IP
+https://github.com/iovisor/bcc
+.SH OS
+Linux
+.SH STABILITY
+Unstable - in development.
+.SH AUTHOR
+Brendan Gregg
+.SH SEE ALSO
+opensnoop(8)

tools/execsnoop.bt

-//
-// execsnoop.bt - basic process exec tracing tool.
-//                For Linux, uses bpftrace, eBPF.
-//
-// This traces when processes call exec(). It is handy for identifying new
-// processes created via the usual fork()->exec() sequence. Note that the
-// return value is not currently traced, so the exec() may have failed.
-// Also, only the first five arguments are currently printed.
-//
-// TODO: switch to proc tracepoints. Support more args. Include retval.
-//
-// 15-Nov-2017	Brendan Gregg	Created this.
-//
+/*
+ * execsnoop.bt   Trace new processes via exec() syscalls.
+ *                For Linux, uses bpftrace and eBPF.
+ *
+ * This traces when processes call exec(). It is handy for identifying new
+ * processes created via the usual fork()->exec() sequence. Note that the
+ * return value is not currently traced, so the exec() may have failed.
+ *
+ * TODO: switch to tracepoints args. Support more args. Include retval.
+ *
+ * This is a bpftrace version of the bcc tool of the same name.
+ *
+ * 15-Nov-2017	Brendan Gregg	Created this.
+ * 11-Sep-2018	   "     "	Switched to use join().
+ */
 
 BEGIN
 {
@@ -18,22 +20,12 @@ BEGIN
 	@epoch = nsecs;
 }
 
-kprobe:sys_execve
+tracepoint:syscalls:sys_enter_execve
 {
-	$step = 8;	// sizeof (char *)
-	$ptr = arg1;
-	
+	$argv = ctx + 24; // workaround until #32
 	$now = nsecs;
-	printf("%-10u %-5d %s",
-	    ($now - @epoch) / 1000000, pid,
-	    str(*$ptr));
-	// unrolled loop for now:
-	$ptr = $ptr + $step; printf(" %s", str(*$ptr));
-	$ptr = $ptr + $step; printf(" %s", str(*$ptr));
-	$ptr = $ptr + $step; printf(" %s", str(*$ptr));
-	$ptr = $ptr + $step; printf(" %s", str(*$ptr));
-	$ptr = $ptr + $step; printf(" %s", str(*$ptr));
-	printf("\n");
+	printf("%-10u %-5d ", ($now - @epoch) / 1000000, pid);
+	join(*$argv);
 }
 
 END

tools/execsnoop_example.txt

@@ -38,3 +38,7 @@ they are failing as the $PATH variable is walked, until one finally succeeds.
 
 This tool can be used to discover unwanted short-lived processes that may be
 causing performance issues such as latency perturbations.
+
+
+There is another version of this tool in bcc: https://github.com/iovisor/bcc
+The bcc version provides more fields and command line options.