doc/man-pages/pod/fstrace_dump.pod

   1 =head1 NAME
   2
   3 fstrace dump - Dumps a trace log
   4
   5 =head1 SYNOPSIS
   6
   7 fstrace dump [B<-set> I<set_name> [I<set_name> ...]]  [B<-follow> I<log_name>]
   8 [B<-file> I<output_filename>]
   9 [B<-sleep> I<seconds_between_reads>]  [B<-help>]
  10
  11 fstrace d [B<-se> I<set_name> [I<set_name> ...]]  [B<-fo> I<log_name>]  [B<-fi> I<output_filename>]
  12 [B<-sl> I<seconds_between_reads>]  [B<-h>]
  13
  14 =head1 DESCRIPTION
  15
  16 The C<fstrace dump> command displays the current contents of the B<cmfx>
  17 trace log on the standard output stream or writes it to the file named
  18 by the B<-file> argument.
  19
  20 To write the log continuously to the standard output stream or to a
  21 file, use the B<-follow> argument. By default, the log's contents are
  22 written out every ten seconds and then automatically cleared. To
  23 change the interval between writes, use the B<-sleep> argument.
  24
  25 =head1 OPTIONS
  26
  27 =over 4
  28
  29 =item B<-set> I<set_name> [I<set_name> ...]
  30
  31 Names the event set for which to write out the associated trace
  32 log. The only acceptable value is B<cm> (for which the associated
  33 trace log is B<cmfx>). Provide either this argument or the B<-follow>
  34 argument, or omit both to write out the B<cmfx> log by default.
  35
  36 =item B<-follow> I<log_name>
  37
  38 Names the trace log to write out continuously at a specified
  39 interval (by default, every ten seconds; use the B<-sleep>
  40 argument to change the interval). The log is cleared after each
  41 write operation.
  42
  43 The only acceptable value is B<cmfx>. Provide either this argument
  44 or the B<-set> argument, or omit both to write out the B<cmfx> log by
  45 default.
  46
  47 =item B<-file> I<output_filename>
  48
  49 Specifies the pathname of the file to which to write the trace
  50 log's contents. It can be in AFS or on the local disk. Partial
  51 pathnames are interpreted relative to the current working
  52 directory. If this argument is omitted, the trace log appears
  53 on the standard output stream.
  54
  55 =item B<-sleep> I<seconds_between_reads>
  56
  57 Sets the number of seconds between writes of the trace log's
  58 contents when it is dumped continuously. Provide the B<-follow>
  59 argument along with this one. If this argument is omitted, the
  60 default interval is ten seconds.
  61
  62 =item B<-help>
  63
  64 Prints the online help for this command. All other valid
  65 options are ignored.
  66
  67 =back
  68
  69 =head1 OUTPUT
  70
  71 The output begins with a header specifying the date and time at which
  72 the write operation began. If the B<-follow> argument is not included,
  73 the header also reports the number of logs being dumped; it is always
  74 1, since there is only the B<cmfx> trace log. The format of the header is
  75 as follows:
  76
  77    AFS Trace Dump -
  78      Date: starting_timestamp
  79    Found 1 logs.
  80    Contents of log cmfx:
  81
  82 Each subsequent message describes a Cache Manager operation in the
  83 following format:
  84
  85 time I<timestamp>, pid I<pid>:I<event_message>
  86
  87 where
  88
  89 =over
  90
  91 =item B<timestamp>
  92
  93 Specifies the time at which the Cache Manager performed the
  94 operation, as the number of seconds since the dump began
  95
  96 =item B<pid>
  97
  98 Specifies the process ID of the process or thread associated
  99 with the message
 100
 101 =item B<event_message>
 102
 103 Is the message itself. They are generally meaningful only to
 104 someone familiar with the AFS source code.
 105
 106 =back
 107
 108 In addition, every 1024 seconds the C<fstrace> command interpreter writes
 109 a message that records the current clock time, in the following
 110 format:
 111
 112 time I<timestamp>, pid I<pid>: Current time: I<unix_time>
 113
 114 where
 115
 116 =over
 117
 118 =item B<timestamp>
 119
 120 Is the number of seconds from the start of trace logging
 121
 122 =item B<pid>
 123
 124 Is the process ID number
 125
 126 =item B<unix_time>
 127
 128 Is the machine's clock time, represent in the standard UNIX
 129 time format as the number of seconds since midnight on January
 130 1, 1970.
 131
 132 =back
 133
 134 Use this message to determine the actual clock time associated with
 135 each log message. Determine the actual time as follows:
 136
 137 =over
 138
 139 =item 1.
 140
 141 Locate the message of interest.
 142
 143 =item 2.
 144
 145 Search backward through the trace file for the closest current
 146 time message.
 147
 148 =item 3.
 149
 150 If the current time message's I<timestamp> is smaller than the log
 151 message's I<timestamp>, subtract former from the latter. If the
 152 current time message's I<timestamp> is larger than the log message's
 153 I<timestamp>, add 1024 to the latter and subtract the former from the
 154 result.
 155
 156 =item 4.
 157
 158 Add the resulting number to the current time message's I<unix_time>
 159 to determine the log message's actual time.
 160
 161 =back
 162
 163 If any of the data in the kernel trace buffer has been overwritten
 164 since tracing was activated, the following message appears at the
 165 appropriate place in the output:
 166
 167    Log wrapped; data missing.
 168
 169 To reduce the likelihood of overwriting, use the C<fstrace setlog>
 170 command to increase the kernel buffer's size. To display the current
 171 defined buffer size, use the C<fstrace lslog> command with the B<-long>
 172 argument.
 173
 174 The following message at the end of the log dump indicates that it is
 175 completed:
 176
 177    AFS Trace Dump - Completed
 178
 179 =head1 EXAMPLES
 180
 181 The following command dumps the log associated with the cm event set
 182 to the standard output stream.
 183
 184     fstrace dump -set cm
 185    AFS Trace Dump -
 186       Date: Tue Apr  7 10:54:57 1998
 187    Found 1 logs.
 188    time 32.965783, pid 0: Tue Apr  7 10:45:52 1998
 189    time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
 190    time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0)
 191    time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
 192    time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
 193                                     .
 194                                     .
 195                                     .
 196    time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
 197         fid (756 4fb7e:588d240.2ff978a8.6)
 198    time 71.440569, pid 33658: Returning code 2 from 19
 199    time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2)
 200    time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
 201    AFS Trace Dump - Completed
 202
 203 The following command dumps the trace log associated with the B<cm> event
 204 set on the local machine to the file B<cmfx.dump.file.1>, using the
 205 default interval of 10 seconds between successive dumps:
 206
 207     fstrace dump -follow cmfx -file cmfx.dump.file.1
 208
 209 =head1 PRIVILEGE REQUIRED
 210
 211 The issuer must be logged in as the local superuser B<root>.
 212
 213 =head1 CAVEATS
 214
 215 This command produces output only if the B<cm> event set is active. To
 216 display or set the event set's state, use the C<fstrace lsset> or C<fstrace
 217 setset> command respectively.
 218
 219 To make the output from this command maximally readable, the message
 220 catalog file called B<afszcm.cat> must reside in the local
 221 B</usr/vice/etc/C> directory. If necessary, copy the file to that
 222 directory from the AFS Binary Distribution before activating tracing.
 223
 224 When the B<cm> event set is active, a defined amount of kernel memory (by
 225 default, 60 KB) is allocated for the B<cmfx> trace log. As described on
 226 the introductory L<fstrace(1)> reference page, when the buffer is full,
 227 messages are overwritten in a circular fashion (new messages overwrite
 228 the oldest ones). To allocate more kernel memory for the log, use the
 229 C<fstrace setlog> command; to display the log buffer's current size, use
 230 the C<fstrace lslog> command with the B<-long> argument.
 231
 232 =head1 COPYRIGHT
 233
 234 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 235
 236 Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
 237 and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
 238 Stanford Linear Accelerator Center, a department of Stanford University.
 239
 240 =head1 SEE ALSO
 241
 242 L<afszcm.cat(1)>,
 243 L<fstrace(1)>,
 244 L<fstrace_lslog(1)>,
 245 L<fstrace_setlog(1)>,
 246 L<fstrace_lsset(1)>
 247
 248 =cut