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.