bcc-filetop(8)

1filetop(8)                  System Manager's Manual                 filetop(8)
2
3
4

NAME

6       filetop - File reads and writes by filename and process. Top for files.
7

SYNOPSIS

9       filetop  [-h]  [-C]  [-r MAXROWS] [-s {reads,writes,rbytes,wbytes}] [-p
10       PID] [interval] [count]
11

DESCRIPTION

13       This is top for files.
14
15       This traces file reads and writes, and prints a per-file summary  every
16       interval  (by  default,  1 second). By default the summary is sorted on
17       the highest read throughput (Kbytes). Sorting order can be changed  via
18       -s  option. By default only IO on regular files is shown. The -a option
19       will list all file types (sockets, FIFOs, etc).
20
21       This uses in-kernel eBPF maps to store per process summaries for  effi‐
22       ciency.
23
24       This  script  works by tracing the __vfs_read() and __vfs_write() func‐
25       tions using kernel dynamic tracing, which instruments explicit read and
26       write  calls. If files are read or written using another means (eg, via
27       mmap()), then they will not be visible using this tool. Also, this tool
28       will need updating to match any code changes to those vfs functions.
29
30       This  should  be  useful for file system workload characterization when
31       analyzing the performance of applications.
32
33       Note that tracing VFS level reads and writes can be a  frequent  activ‐
34       ity,  and  this  tool can begin to cost measurable overhead at high I/O
35       rates.
36
37       Since this uses BPF, only the root user can use this tool.
38

REQUIREMENTS

40       CONFIG_BPF and bcc.
41

OPTIONS

43       -a     Include non-regular file types (sockets, FIFOs, etc).
44
45       -C     Don't clear the screen.
46
47       -r MAXROWS
48              Maximum number of rows to print. Default is 20.
49
50       -s {reads,writes,rbytes,wbytes}
51              Sort column. Default is rbytes (read throughput).
52
53       -p PID Trace this PID only.
54
55       interval
56              Interval between updates, seconds.
57
58       count  Number of interval summaries.
59
60

EXAMPLES

62       Summarize block device I/O by process, 1 second screen refresh:
63              # filetop
64
65       Don't clear the screen, and top 8 rows only:
66              # filetop -Cr 8
67
68       5 second summaries, 10 times only:
69              # filetop 5 10
70

FIELDS

72       loadavg:
73              The contents of /proc/loadavg
74
75       PID    Process ID.
76
77       COMM   Process name.
78
79       READS  Count of reads during interval.
80
81       WRITES Count of writes during interval.
82
83       R_Kb   Total read Kbytes during interval.
84
85       W_Kb   Total write Kbytes during interval.
86
87       T      Type of file: R == regular, S == socket, O == other (pipe, etc).
88
89       FILE   Filename.
90

OVERHEAD

92       Depending on the frequency of application reads  and  writes,  overhead
93       can  become significant, in the worst case slowing applications by over
94       50%. Hopefully for real world workloads the overhead is  much  less  --
95       test before use. The reason for the high overhead is that VFS reads and
96       writes can be a frequent event, and despite  the  eBPF  overhead  being
97       very  small per event, if you multiply this small overhead by a million
98       events per second, it becomes a million times worse. Literally. You can
99       gauge  the  number  of reads and writes using the vfsstat(8) tool, also
100       from bcc.
101

SOURCE

103       This is from bcc.
104
105              https://github.com/iovisor/bcc
106
107       Also look in the bcc distribution for a  companion  _examples.txt  file
108       containing example usage, output, and commentary for this tool.
109

OS

111       Linux
112

STABILITY

114       Unstable - in development.
115

AUTHOR

117       Brendan Gregg
118

INSPIRATION

120       top(1) by William LeFebvre
121