doc/man-pages/pod8/fstrace_dump.pod

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