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