Provided by: openafs-client_1.4.1-2_i386 bug

NAME

       fstrace dump - Dumps a trace log

SYNOPSIS

       fstrace dump << [-set <set name+] >>> << [-follow <log name] >>>
           << [-file <output filename] >>> << [-sleep <seconds between reads]
       >>>
           [-help]

       fstrace d << [-se <set name+] >>> << [-fo <log name] >>>
           << [-fi <output filename] >>> << [-sl <seconds between reads] >>>
           [-h]

DESCRIPTION

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

       To write the log continuously to the standard output stream or to a
       file, use the -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 -sleep argument.

CAUTIONS

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

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

       When the cm event set is active, a defined amount of kernel memory (by
       default, 60 KB) is allocated for the cmfx trace log. As described in
       the fstrace(8) manpage, 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 fstrace
       setlog command; to display the log buffer’s current size, use the
       fstrace lslog command with the -long argument.

OPTIONS

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

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

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

       -file <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.

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

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

OUTPUT

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

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

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

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

       where

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

       <pid>
           Specifies the process ID of the process or thread associated with
           the message.

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

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

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

       where

       <timestamp>
           Is the number of seconds from the start of trace logging.

       <pid>
           Is the process ID number.

       <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.

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

       ·   Locate the message of interest.

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

       ·   If the current time message’s timestamp is smaller than the log
           message’s timestamp, subtract former from the latter.  If the
           current time message’s timestamp is larger than the log message’s
           timestamp, add 1024 to the latter and subtract the former from the
           result.

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

           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 fstrace setlog
           command to increase the kernel buffer’s size. To display the
           current defined buffer size, use the fstrace lslog command with the
           -long argument.

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

              AFS Trace Dump - Completed

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 cm event
       set on the local machine to the file cmfx.dump.file.1, using the
       default interval of 10 seconds between successive dumps:

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

PRIVILEGE REQUIRED

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

SEE ALSO

       the afszcm.cat(5) manpage, the fstrace(8) manpage, the fstrace_lslog(8)
       manpage, the fstrace_setlog(8) manpage, the fstrace_lsset(8) manpage

COPYRIGHT

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

       This documentation is covered by the IBM Public License Version 1.0.
       It was converted from HTML to POD by software written by Chas Williams
       and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.