Merge pull request #369 from goldshtn/alloc-hist

argdist.py: Trace a function and its parameters into a histogram or frequency count

README.md

@@ -65,6 +65,7 @@ Examples:
 
 Tools:
 
+- tools/[argdist](tools/argdist.py): Display function parameter values as a histogram or frequency count. [Examples](tools/argdist_example.txt).
 - tools/[bashreadline](tools/bashreadline.py): Print entered bash commands system wide. [Examples](tools/bashreadline_example.txt).
 - tools/[biolatency](tools/biolatency.py): Summarize block device I/O latency as a histogram. [Examples](tools/biolatency_example.txt).
 - tools/[biotop](tools/biotop.py): Top for disks: Summarize block device I/O by process. [Examples](tools/biotop_example.txt).

man/man8/argdist.8

+.TH argdist 8  "2016-02-11" "USER COMMANDS"
+.SH NAME
+argdist \- Trace a function and display a histogram or frequency count of its parameter values. Uses Linux eBPF/bcc.
+.SH SYNOPSIS
+.B argdist [-h] [-p PID] [-z STRING_SIZE] [-i INTERVAL] [-n COUNT] [-H specifier [specifier ...]] [-C specifier [specifier ...]]
+.SH DESCRIPTION
+argdist attaches to function entry and exit points, collects specified parameter
+values, and stores them in a histogram or a frequency collection that counts
+the number of times a parameter value occurred. It can also filter parameter
+values and instrument multiple entry points at once.
+
+This currently only works on x86_64. Check for future versions.
+.SH REQUIREMENTS
+CONFIG_BPF and bcc.
+.SH OPTIONS
+.TP
+\-h
+Print usage message.
+.TP
+\-p PID
+Trace only functions in the process PID.
+.TP
+\-z STRING_SIZE
+When collecting string arguments (of type char*), collect up to STRING_SIZE 
+characters. Longer strings will be truncated.
+.TP
+-i INTERVAL
+Print the collected data every INTERVAL seconds. The default is 1 second.
+.TP
+-n NUMBER
+Print the collected data COUNT times and then exit.
+.TP
+-H SPECIFIER, -C SPECIFIER
+One or more probe specifications that instruct argdist which functions to
+probe, which parameters to collect, how to aggregate them, and whether to perform
+any filtering. See SPECIFIER SYNTAX below.
+.SH SPECIFIER SYNTAX
+The general specifier syntax is as follows:
+
+.B {p,r}:[library]:function(signature)[:type:expr[:filter]][;label]
+.TP
+.B {p,r}
+Probe type \- "p" for function entry, "r" for function return;
+\-H for histogram collection, \-C for frequency count.
+Indicates where to place the probe and whether the probe should collect frequency
+count information, or aggregate the collected values into a histogram. Counting 
+probes will collect the number of times every parameter value was observed,
+whereas histogram probes will collect the parameter values into a histogram.
+Only integral types can be used with histogram probes; there is no such limitation
+for counting probes. Return probes can only use the pseudo-variable $retval, which
+is an alias for the function's return value.
+.TP
+.B [library]
+Library containing the probe.
+Specify the full path to the .so or executable file where the function to probe
+resides. Alternatively, you can specify just the lib name: for example, "c"
+refers to libc. If no library name is specified, the kernel is assumed.
+.TP
+.B function(signature)
+The function to probe, and its signature.
+The function name must match exactly for the probe to be placed. The signature,
+on the other hand, is only required if you plan to collect parameter values 
+based on that signature. For example, if you only want to collect the first
+parameter, you don't have to specify the rest of the parameters in the signature.
+.TP
+.B [type]
+The type of the expression to capture.
+This is the type of the keys in the histogram or raw event collection that are
+collected by the probes.
+.TP
+.B [expr]
+The expression to capture.
+These are the values that are assigned to the histogram or raw event collection.
+You may use the parameters directly, or valid C expressions that involve the
+parameters, such as "size % 10".
+.TP
+.B [filter]
+The filter applied to the captured data.
+Only parameter values that pass the filter will be collected. This is any valid
+C expression that refers to the parameter values, such as "fd == 1 && length > 16".
+.TP
+.B [label]
+The label that will be displayed when printing the probed values. By default,
+this is the probe specifier. 
+.SH EXAMPLES
+.TP
+Print a histogram of allocation sizes passed to kmalloc:
+#
+.B argdist.py -H 'p::__kmalloc(u64 size):u64:size'
+.TP
+Print a count of how many times process 1005 called malloc with an allocation size of 16 bytes:
+#
+.B argdist.py -p 1005 -C 'p:c:malloc(size_t size):size_t:size:size==16'
+.TP
+Snoop on all strings returned by gets():
+#
+.B argdist.py -C 'r:c:gets():char*:$retval'
+.TP
+Print frequency counts of how many times writes were issued to a particular file descriptor number, in process 1005:
+#
+.B argdist.py -p 1005 -C 'p:c:write(int fd):int:fd'
+.TP
+Print a histogram of error codes returned by read() in process 1005:
+#
+.B argdist.py -p 1005 -H 'r:c:read()'
+.TP
+Print a histogram of buffer sizes passed to write() across all processes, where the file descriptor was 1 (STDOUT):
+#
+.B argdist.py -H 'p:c:write(int fd, const void *buf, size_t count):size_t:count:fd==1'
+.TP
+Count fork() calls in libc across all processes, grouped by pid:
+#
+.B argdist.py -C 'p:c:fork():int:$PID;fork per process'
+.TP
+Print histograms of sleep() and nanosleep() parameter values:
+#
+.B argdist.py -H 'p:c:sleep(u32 seconds):u32:seconds' -H 'p:c:nanosleep(struct timespec { time_t tv_sec; long tv_nsec; } *req):long:req->tv_nsec'
+.TP
+Spy on writes to STDOUT performed by process 2780, up to a string size of 120 characters:
+#
+.B argdist.py -p 2780 -z 120 -C 'p:c:write(int fd, char* buf, size_t len):char*:buf:fd==1'
+.SH SOURCE
+This is from bcc.
+.IP
+https://github.com/iovisor/bcc
+.PP
+Also look in the bcc distribution for a companion _examples.txt file containing
+example usage, output, and commentary for this tool.
+.SH OS
+Linux
+.SH STABILITY
+Unstable - in development.
+.SH AUTHOR
+Sasha Goldshtein