bcc-dirtop(8)

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

NAME

6       dirtop - File reads and writes by directory. Top for directories.
7

SYNOPSIS

9       dirtop   -d   directory1,directory2,...  [-h]  [-C]  [-r  MAXROWS]  [-s
10       {reads,writes,rbytes,wbytes}] [-p PID] [interval] [count]
11

DESCRIPTION

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

REQUIREMENTS

39       CONFIG_BPF and bcc.
40

OPTIONS

42       -d     Defines  a  list  of  directories,  comma separated, to observe.
43              Wildcards are allowed if between single bracket.
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 directory, 1 second screen refresh:
63              # dirtop.py
64
65       Don't clear the screen, and top 8 rows only:
66              # dirtop.py -Cr 8
67
68       5 second summaries, 10 times only:
69              # dirtop.py 5 10
70
71       Report read & write IOs generated in mutliple yarn  and  data  directo‐
72       ries:
73              # dirtop.py -d '/hdfs/uuid/*/yarn,/hdfs/uuid/*/data'
74

FIELDS

76       loadavg:
77              The contents of /proc/loadavg
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       PATH   The path were the IOs were accounted.
88

OVERHEAD

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

SOURCE

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

OS

109       Linux
110

STABILITY

112       Unstable - in development.
113

AUTHOR

115       Erwan Velu
116

INSPIRATION

118       filetop(8) by Brendan Gregg
119