doc/man-pages/pod8/fstrace_dump.pod

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