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