=head1 NAME

fstrace dump - Dumps a trace log

=head1 SYNOPSIS

fstrace dump [B<-set> I<set_name> [I<set_name> ...]]  [B<-follow> I<log_name>]
[B<-file> I<output_filename>]
[B<-sleep> I<seconds_between_reads>]  [B<-help>]

fstrace d [B<-se> I<set_name> [I<set_name> ...]]  [B<-fo> I<log_name>]  [B<-fi> I<output_filename>]
[B<-sl> I<seconds_between_reads>]  [B<-h>]

=head1 DESCRIPTION

The C<fstrace dump> command displays the current contents of the B<cmfx>
trace log on the standard output stream or writes it to the file named
by the B<-file> argument.

To write the log continuously to the standard output stream or to a
file, use the B<-follow> argument. By default, the log's contents are
written out every ten seconds and then automatically cleared. To
change the interval between writes, use the B<-sleep> argument.

=head1 OPTIONS

=over 4

=item B<-set> I<set_name> [I<set_name> ...]

Names the event set for which to write out the associated trace
log. The only acceptable value is B<cm> (for which the associated
trace log is B<cmfx>). Provide either this argument or the B<-follow>
argument, or omit both to write out the B<cmfx> log by default.

=item B<-follow> I<log_name>

Names the trace log to write out continuously at a specified
interval (by default, every ten seconds; use the B<-sleep>
argument to change the interval). The log is cleared after each
write operation.

The only acceptable value is B<cmfx>. Provide either this argument
or the B<-set> argument, or omit both to write out the B<cmfx> log by
default.

=item B<-file> I<output_filename>

Specifies the pathname of the file to which to write the trace
log's contents. It can be in AFS or on the local disk. Partial
pathnames are interpreted relative to the current working
directory. If this argument is omitted, the trace log appears
on the standard output stream.

=item B<-sleep> I<seconds_between_reads>

Sets the number of seconds between writes of the trace log's
contents when it is dumped continuously. Provide the B<-follow>
argument along with this one. If this argument is omitted, the
default interval is ten seconds.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 OUTPUT

The output begins with a header specifying the date and time at which
the write operation began. If the B<-follow> argument is not included,
the header also reports the number of logs being dumped; it is always
1, since there is only the B<cmfx> trace log. The format of the header is
as follows:

   AFS Trace Dump -
     Date: starting_timestamp
   Found 1 logs.
   Contents of log cmfx:

Each subsequent message describes a Cache Manager operation in the
following format:

time I<timestamp>, pid I<pid>:I<event_message>

where

=over

=item B<timestamp>

Specifies the time at which the Cache Manager performed the
operation, as the number of seconds since the dump began

=item B<pid>

Specifies the process ID of the process or thread associated
with the message

=item B<event_message>

Is the message itself. They are generally meaningful only to
someone familiar with the AFS source code.

=back

In addition, every 1024 seconds the C<fstrace> command interpreter writes
a message that records the current clock time, in the following
format:

time I<timestamp>, pid I<pid>: Current time: I<unix_time>

where

=over

=item B<timestamp>

Is the number of seconds from the start of trace logging

=item B<pid>

Is the process ID number

=item B<unix_time>

Is the machine's clock time, represent in the standard UNIX
time format as the number of seconds since midnight on January
1, 1970.

=back

Use this message to determine the actual clock time associated with
each log message. Determine the actual time as follows:

=over

=item 1.

Locate the message of interest.

=item 2.

Search backward through the trace file for the closest current
time message.

=item 3.

If the current time message's I<timestamp> is smaller than the log
message's I<timestamp>, subtract former from the latter. If the
current time message's I<timestamp> is larger than the log message's
I<timestamp>, add 1024 to the latter and subtract the former from the
result.

=item 4.

Add the resulting number to the current time message's I<unix_time>
to determine the log message's actual time.

=back

If any of the data in the kernel trace buffer has been overwritten
since tracing was activated, the following message appears at the
appropriate place in the output:

   Log wrapped; data missing.

To reduce the likelihood of overwriting, use the C<fstrace setlog>
command to increase the kernel buffer's size. To display the current
defined buffer size, use the C<fstrace lslog> command with the B<-long>
argument.

The following message at the end of the log dump indicates that it is
completed:

   AFS Trace Dump - Completed

=head1 EXAMPLES

The following command dumps the log associated with the cm event set
to the standard output stream.

    fstrace dump -set cm
   AFS Trace Dump -
      Date: Tue Apr  7 10:54:57 1998
   Found 1 logs.
   time 32.965783, pid 0: Tue Apr  7 10:45:52 1998
   time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
   time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0)
   time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
   time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
                                    .
                                    .
                                    .
   time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
        fid (756 4fb7e:588d240.2ff978a8.6)
   time 71.440569, pid 33658: Returning code 2 from 19
   time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2)
   time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
   AFS Trace Dump - Completed

The following command dumps the trace log associated with the B<cm> event
set on the local machine to the file B<cmfx.dump.file.1>, using the
default interval of 10 seconds between successive dumps:

    fstrace dump -follow cmfx -file cmfx.dump.file.1

=head1 PRIVILEGE REQUIRED

The issuer must be logged in as the local superuser B<root>.

=head1 CAVEATS

This command produces output only if the B<cm> event set is active. To
display or set the event set's state, use the C<fstrace lsset> or C<fstrace
setset> command respectively.

To make the output from this command maximally readable, the message
catalog file called B<afszcm.cat> must reside in the local
B</usr/vice/etc/C> directory. If necessary, copy the file to that
directory from the AFS Binary Distribution before activating tracing.

When the B<cm> event set is active, a defined amount of kernel memory (by
default, 60 KB) is allocated for the B<cmfx> trace log. As described on
the introductory L<fstrace(1)> reference page, when the buffer is full,
messages are overwritten in a circular fashion (new messages overwrite
the oldest ones). To allocate more kernel memory for the log, use the
C<fstrace setlog> command; to display the log buffer's current size, use
the C<fstrace lslog> command with the B<-long> argument.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<afszcm.cat(1)>,
L<fstrace(1)>,
L<fstrace_lslog(1)>,
L<fstrace_setlog(1)>,
L<fstrace_lsset(1)>

=cut
