Skip to content

Commit

Permalink
funcslower: Man page
Browse files Browse the repository at this point in the history
  • Loading branch information
goldshtn committed Apr 1, 2017
1 parent 7789318 commit 1f4fcdb
Showing 1 changed file with 112 additions and 0 deletions.
112 changes: 112 additions & 0 deletions man/man8/funcslower.8
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
.TH funcslower 8 "2017-03-30" "USER COMMANDS"
.SH NAME
fileslower \- Trace slow kernel or user function calls.
.SH SYNOPSIS
.B fileslower [\-h] [\-p PID] [-m MIN_MS] [-u MIN_US] [-a ARGUMENTS] [-T] [-t] [-v] function [function ...]
.SH DESCRIPTION
This script traces a kernel or user function's entry and return points, and
prints a message when the function's latency exceeded the specified threshold.
Multiple functions are supported, and you can mix kernel functions with user
functions in different libraries.

WARNING: See the OVERHEAD section.

By default, a minimum millisecond threshold of 1 is used. Recursive functions
are not supported: only the inner-most recursive invocation will be traced.

Since this uses BPF, only the root user can use this tool.
.SH REQUIREMENTS
CONFIG_BPF and bcc.
.SH OPTIONS
\-p PID
Trace this PID only.
.TP
\-m MIN_NS
Minimum duration to trace, in milliseconds. Default is 1 ms.
.TP
\-u MIN_US
Minimum duration to trace, in microseconds.
.TP
\-a ARGUMENTS
Print the function's arguments, up to 6.
.TP
\-T
Print a HH:MM:SS timestamp with each entry.
.TP
\-t
Print a seconds timestamp with each entry, at microsecond resolution.
.TP
\-v
Print the resulting BPF program, for debugging purposes.
.TP
function
The function to trace -- multiple functions are supported. If a plain function
name is provided, the function is assumed to be a kernel function. For user
functions, provide the library name and the function name, e.g. bash:readline
or c:malloc.
.SH EXAMPLES
.TP
Trace vfs_write calls slower than 1ms:
#
.B funcslower vfs_write
.TP
Trace open() calls in libc slower than 10us:
#
.B funcslower \-u 10 c:open
.TP
Trace both malloc() and free() slower than 10us, in pid 135 only:
#
.B funcslower \-p 135 \-u 10 c:malloc c:free
.TP
Trace the write syscall and print its first 4 arguments:
#
.B funcslower -a 4 SyS_write
.SH FIELDS
.TP
TIME
Time of the event as a human-readable HH:MM:SS format, or a timestamp in seconds
at microsecond-accuracy from the first event seen.
.TP
COMM
Process name.
.TP
PID
Process ID.
.TP
LAT
Latency of the operation in either microseconds (us) or milliseconds (ms).
.TP
RVAL
The return value from the function. Often useful for diagnosing a relationship
between slow and failed function calls.
.TP
FUNC
The function name, followed by its arguments if requested.
.SH OVERHEAD
Depending on the function(s) being traced, overhead can become severe. For
example, tracing a common function like malloc() can slow down a C/C++ program
by a factor of 2 or more. On the other hand, tracing a low-frequency event like
the SyS_setreuid() function will probably not be as prohibitive, and in fact
negligible for functions that are called up to 100-1000 times per second.

You should first use the funclatency and argdist tools for investigation,
because they summarize data in-kernel and have a much lower overhead than this
tool. To get a general idea of the number of times a particular function is
called (and estimate the overhead), use the funccount tool, e.g.:
.PP
# funccount c:open
.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
.SH SEE ALSO
funccount(8), funclatency(8), argdist(8), trace(8)

0 comments on commit 1f4fcdb

Please sign in to comment.