Ignore lockmem executable.
[bluesky.git] / TBBT / trace_init / nfsscan.txt
1 # Copyright (c) 2002-2003
2 #      The President and Fellows of Harvard College.
3 #
4 # $Id: nfsscan.txt,v 1.5 2003/07/28 14:27:16 ellard Exp $
5
6 NFSSCAN DOCUMENTATION
7
8 This is version 0.10a of nfsscan, dated 7/25/2003.
9
10 THIS IS A PRELIMINARY RELEASE OF A NEW UTILITY.  YOU SHOULD ASSUME
11 THAT THE COMMANDLINE FORMATS WILL EVOLVE RAPIDLY OVER THE NEXT SEVERAL
12 WEEKS.
13  
14 Please report bugs, problems or suggestions for improvements to
15 ellard@eecs.harvard.edu.
16
17 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
18
19 COMMANDLINE OPTIONS
20
21 Usage: nfsscan [options] [trace1 [trace2 ...]]
22
23 If no trace files are specified, then the trace is read from stdin.
24
25 Command line options:
26
27 -h              Print usage message and exit.
28
29 -B [CFUG]       Compute per-Client, per-File, per-User, or per-Group info.
30
31 -c c1[,c2]*     Include only activity performed by the specified clients.
32
33 -C c1[,c2]*     Exclude activity performed by the specified clients.
34
35 -d              Compute per-directory statistics.  This implicitly
36                 enables -BF so that per-file info is computed.
37
38 -f              Do file info tracking.  This implicitly enables -BF so
39                 that per-File info is computed.
40
41 -F fhtype       Specify the file handle type used by the server.
42                 (advfs or netapp)
43
44 -g g1[,g2]*     Include only activity performed by the specified groups.
45
46 -G g1[,g2]*     Exclude activity performed by the specified groups.
47
48 -l              Record average operation latency.
49
50 -o basename     Write output to files starting with the specified
51                 basename.  The "Count" table goes to basename.cnt,
52                 "Latency" to basename.lat, and "File" to basename.fil.
53                 The default is to write all output to stdout.
54
55 -O op[,op]*     Specify the list of "interesting" operations.
56                 The default list is:
57
58                 read,write,lookup,getattr,access,create,remove
59
60                 If the first op starts with +, then the specified list
61                 of ops is appended to the default list.  The special
62                 pseudo-ops readM and writeM represent the number of
63                 bytes read and written, expressed in MB.
64
65 -t interval     Time interval for cummulative statistics (such as
66                 operation count).  The default is 300 seconds. 
67                 If set to 0, then the entire trace is processed.  By
68                 default, time is specified in seconds, but if the last
69                 character of the interval is any of s, m, h, or d,
70                 then the interval is interpreted as seconds, minutes,
71                 hours, or days.
72
73 -u u1[,u2]*     Include only activity performed by the specified users.
74
75 -U u1[,u2]*     Exclude activity performed by the specified users.
76
77 -Z              Omit count and latency lines that have a zero total
78                 operation count.
79
80
81 OUTPUT FORMATS
82
83 Each line generated by nfsscan begins with a token that indicates the
84 table to which it belongs.
85
86 COUNT LINES
87
88 These lines all begin with 'C' (or #C, for comments),
89 and have the following format:
90
91 C time client euid egid fh TOTAL INTERESTING <OPS>
92
93 time - The time of the start of the measurement interval.
94
95 client - The IP number of the client.  If the user has not
96         requested per-client statistics, this field is 'u'.
97
98 euid - The effective uid of the caller, in decimal.  If the user has
99         not requested per-user statistics, this field is 'u'.
100
101 egid - The effective gid of the caller, in decimal.  If the user has
102         not requested per-group statistics, this field is 'u'.
103
104 fh - The file handle used by the operation.  If the user has not
105         requested per-file statistics, this field is 'u'.
106
107 TOTAL - The total number of operations for the given client, euid,
108         egid, and fh, for all the operations in <OPS...>.  Note that
109         this is NOT the same as the total of all operations!  For
110         example, if you set <OPS> to the empty list, the TOTAL will
111         always be zero.
112
113 INTERESTING - The total number of "interesting" operations.  These are
114         either the default operations (listed below) or the whatever
115         set of operations the user specifies.
116
117
118 <OPS> - Following INTERESTING, the count for each "interesting"
119         operation observed during the measurement interval is printed. 
120         The list of operations can be specified or extended on the
121         commandline.  By default, the list of operations is:
122
123                 read, write, lookup, getattr, access, create, remove
124
125 LATENCY LINES
126
127 The format for the "latency" lines is like that of the "count" lines,
128 except the lines all begin with "L" (or "#L") and each count
129 (including the TOTAL and INTERESTING counts) is followed the average
130 latency for that operation.  If the count for a particular operation
131 is 0, then the average latency is shown as -1.
132
133 Note that the counts for the latency lines may be (and often are)
134 different than the counts for count lines.  This is because the count
135 lines show the number of calls that were observed, and the latency
136 lines require observing both calls and reponses.
137
138 FILE LINES
139
140 These lines show information about files, rather than information
141 about calls.  These lines all begin with "F" (or "#F").  The file
142 information (size, mode, etc) are currently only printed for files,
143 not directories.
144
145 The format is:
146
147 F type state fh path dirs mode size atime mtime ctime
148
149 type - Either "F" for file, or "D" for directory.
150
151 state - "A" if the file is still alive at the end of the
152         trace, or "D" if the file has been deleted.
153
154 fh - The file handle.
155
156 path - as much of the file path as can be reconstructed from the
157         observed traffic.
158
159 dirs - the number of directories in the path.
160
161 mode - the most recently observed permissions on the file, in hex.
162
163 size - the most recently observed size of the file, in hex.
164
165 atime - last access time of the file
166
167 mtime - last modification time of the file
168
169 ctime - last file status change time
170
171 DIRECTORY LINES
172
173 These lines show operation count information for files and
174 directories.  These lines all begin with "D" (or "#D").  Each line
175 begins with the following fields:
176
177 time - The time of the start of the measurement interval.
178
179 Dir/File - D for directory, F for file.
180
181 dircnt - The length of the path to that directory, or zero for files.
182
183 path - The path from the mount point to the directory or file.
184
185 fh - The file handle of the directory or file.
186
187 TOTAL - The total number of operations for the given client, euid,
188         egid, and fh, for all the operations in <OPS...>.  Note that
189         this is NOT the same as the total of all operations!  For
190         example, if you set <OPS> to the empty list, the TOTAL will
191         always be zero.
192
193 Following the TOTAL, the count for each "interesting" operation
194 observed during the measurement interval is printed.  The list of
195 operations can be specified on the commandline.  By default, the list
196 of operations is:
197
198         read, write, lookup, getattr, access, create, remove
199
200 The information for files is redundant because this information is
201 also reflected in the Count lines (if -BF is used), but it is
202 sometimes useful to have it in the same format as the directory info.
203
204 The TOTAL and op counts for directories represent the total number of
205 ops for the files in that directory AND all of its subdirectories.
206
207 NOTE: there are several potential problems with the directory information:
208
209         1.  It is possible (and not uncommon) for some part of a path
210                 to be missing from the traces.  The path is
211                 reconstructed as far back to the root as possible, but
212                 this is not always successful.
213
214                 If no information about the name of a file is known,
215                 then it is given the name ".".
216
217         2.  If files are renamed during the trace, then the name shown
218                 is the most recent name for the file.
219
220         3.  If files are removed during the trace, they are still
221                 reported in the summary.
222
223                 This can lead to an error:  if a directory is deleted,
224                 and then another directory is created elsewhere with a
225                 new name but the same inode number, this new directory
226                 can "inherit" all the info about the files in the old
227                 directory, including parentage.  In the worst case,
228                 this can cause a loop.  The program will detect such
229                 loops, and therefore not get caught forever, but it
230                 doesn't do anything clever about them.