doc/html/AdminReference/auarf172.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf171.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf173.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRFSTRACE_DUMP" HREF="auarf002.htm#ToC_186">fstrace dump</A></H2>
  19 <P><STRONG>Purpose</STRONG>
  20 <A NAME="IDX5031"></A>
  21 <A NAME="IDX5032"></A>
  22 <P>Dumps a trace log
  23 <P><STRONG>Synopsis</STRONG>
  24 <PRE><B>fstrace dump</B> [<B>-set</B> &lt;<VAR>set_name</VAR>><SUP>+</SUP>]  [<B>-follow</B> &lt;<VAR>log_name</VAR>>]
  25              [<B>-file</B> &lt;<VAR>output_filename</VAR>>]
  26              [<B>-sleep</B> &lt;<VAR>seconds_between_reads</VAR>>]  [<B>-help</B>]
  27
  28 <B>fstrace d</B> [<B>-se</B> &lt;<VAR>set_name</VAR>><SUP>+</SUP>]  [<B>-fo</B> &lt;<VAR>log_name</VAR>>]  [<B>-fi</B> &lt;<VAR>output_filename</VAR>>]
  29           [<B>-sl</B> &lt;<VAR>seconds_between_reads</VAR>>]  [<B>-h</B>]
  30 </PRE>
  31 <P><STRONG>Description</STRONG>
  32 <P>The <B>fstrace dump</B> command displays the current contents of the
  33 <B>cmfx</B> trace log on the standard output stream or writes it to the
  34 file named by the <B>-file</B> argument.
  35 <P>To write the log continuously to the standard output stream or to a file,
  36 use the <B>-follow</B> argument. By default, the log's
  37 contents are written out every ten seconds and then automatically
  38 cleared. To change the interval between writes, use the
  39 <B>-sleep</B> argument.
  40 <P><STRONG>Cautions</STRONG>
  41 <P>This command produces output only if the <B>cm</B> event set is
  42 active. To display or set the event set's state, use the
  43 <B>fstrace lsset</B> or <B>fstrace setset</B> command
  44 respectively.
  45 <P>To make the output from this command maximally readable, the message
  46 catalog file called <B>afszcm.cat</B> must reside in the local
  47 <B>/usr/vice/etc/C</B> directory. If necessary, copy the file to
  48 that directory from the AFS Binary Distribution before activating
  49 tracing.
  50 <P>When the <B>cm</B> event set is active, a defined amount of kernel
  51 memory (by default, 60 KB) is allocated for the <B>cmfx</B> trace
  52 log. As described on the introductory <B>fstrace</B> reference
  53 page, when the buffer is full, messages are overwritten in a circular fashion
  54 (new messages overwrite the oldest ones). To allocate more kernel
  55 memory for the log, use the <B>fstrace setlog</B> command; to display
  56 the log buffer's current size, use the <B>fstrace lslog</B> command
  57 with the <B>-long</B> argument.
  58 <P><STRONG>Options</STRONG>
  59 <DL>
  60 <P><DT><B>-set
  61 </B><DD>Names the event set for which to write out the associated trace
  62 log. The only acceptable value is <B>cm</B> (for which the
  63 associated trace log is <B>cmfx</B>). Provide either this argument
  64 or the <B>-log</B> argument, or omit both to write out the <B>cmfx</B>
  65 log by default.
  66 <P><DT><B>-follow
  67 </B><DD>Names the trace log to write out continuously at a specified interval (by
  68 default, every ten seconds; use the <B>-sleep</B> argument to change
  69 the interval). The log is cleared after each write operation.
  70 <P>The only acceptable value is <B>cmfx</B>. Provide either this
  71 argument or the <B>-set</B> argument, or omit both to write out the
  72 <B>cmfx</B> log by default.
  73 <P><DT><B>-file
  74 </B><DD>Specifies the pathname of the file to which to write the trace log's
  75 contents. It can be in AFS or on the local disk. Partial
  76 pathnames are interpreted relative to the current working directory. If
  77 this argument is omitted, the trace log appears on the standard output
  78 stream.
  79 <P><DT><B>-sleep
  80 </B><DD>Sets the number of seconds between writes of the trace log's contents
  81 when it is dumped continuously. Provide the <B>-follow</B> argument
  82 along with this one. If this argument is omitted, the default interval
  83 is ten seconds.
  84 <P><DT><B>-help
  85 </B><DD>Prints the online help for this command. All other valid options
  86 are ignored.
  87 </DL>
  88 <P><STRONG>Output</STRONG>
  89 <P>The output begins with a header specifying the date and time at which the
  90 write operation began. If the <B>-follow</B> argument is not
  91 included, the header also reports the number of logs being dumped; it is
  92 always <TT>1</TT>, since there is only the <B>cmfx</B> trace log.
  93 The format of the header is as follows:
  94 <PRE>   AFS Trace Dump -
  95      Date: <VAR>starting_timestamp</VAR>
  96    Found 1 logs.
  97    Contents of log cmfx:
  98
  99 </PRE>
 100 <P>Each subsequent message describes a Cache Manager operation in the
 101 following format:
 102 <PRE>   time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>:<VAR>event_message</VAR>
 103
 104 </PRE>
 105 <P>where
 106 <DL>
 107 <P><DT><B><VAR>timestamp</VAR>
 108 </B><DD>Specifies the time at which the Cache Manager performed the operation, as
 109 the number of seconds since the dump began
 110 <P><DT><B><VAR>pid</VAR>
 111 </B><DD>Specifies the process ID of the process or thread associated with the
 112 message
 113 <P><DT><B><VAR>event_message</VAR>
 114 </B><DD>Is the message itself. They are generally meaningful only to
 115 someone familiar with the AFS source code.
 116 </DL>
 117 <P>In addition, every 1024 seconds the <B>fstrace</B> command interpreter
 118 writes a message that records the current clock time, in the following
 119 format:
 120 <PRE>   time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>: Current time: <VAR>unix_time</VAR>
 121
 122 </PRE>
 123 <P>where
 124 <DL>
 125 <P><DT><B><VAR>timestamp</VAR>
 126 </B><DD>Is the number of seconds from the start of trace logging
 127 <P><DT><B><VAR>pid</VAR>
 128 </B><DD>Is the process ID number
 129 <P><DT><B><VAR>unix_time</VAR>
 130 </B><DD>Is the machine's clock time, represent in the standard UNIX time
 131 format as the number of seconds since midnight on January 1, 1970.
 132 </DL>
 133 <P>Use this message to determine the actual clock time associated with each
 134 log message. Determine the actual time as follows:
 135 <OL TYPE=1>
 136 <P><LI>Locate the message of interest.
 137 <P><LI>Search backward through the trace file for the closest current time
 138 message.
 139 <P><LI>If the current time message's <VAR>timestamp</VAR> is smaller than the
 140 log message's <VAR>timestamp</VAR>, subtract former from the latter.
 141 If the current time message's <VAR>timestamp</VAR> is larger than the log
 142 message's <VAR>timestamp</VAR>, add 1024 to the latter and subtract the
 143 former from the result.
 144 <P><LI>Add the resulting number to the current time message's
 145 <VAR>unix_time</VAR> to determine the log message's actual time.
 146 </OL>
 147 <P>If any of the data in the kernel trace buffer has been overwritten since
 148 tracing was activated, the following message appears at the appropriate place
 149 in the output:
 150 <PRE>   Log wrapped; data missing.
 151
 152 </PRE>
 153 <P>To reduce the likelihood of overwriting, use the <B>fstrace setlog</B>
 154 command to increase the kernel buffer's size. To display the
 155 current defined buffer size, use the <B>fstrace lslog</B> command with the
 156 <B>-long</B> argument.
 157 <P>The following message at the end of the log dump indicates that it is
 158 completed:
 159 <PRE>   AFS Trace Dump - Completed
 160
 161 </PRE>
 162 <P><STRONG>Examples</STRONG>
 163 <P>The following command dumps the log associated with the <B>cm</B> event
 164 set to the standard output stream.
 165 <PRE>   # <B>fstrace dump -set cm</B>
 166    AFS Trace Dump -
 167       Date: Tue Apr  7 10:54:57 1998
 168    Found 1 logs.
 169    time 32.965783, pid 0: Tue Apr  7 10:45:52 1998
 170    time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
 171    time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0)
 172    time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
 173    time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
 174                                     .
 175                                     .
 176                                     .
 177    time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
 178         fid (756 4fb7e:588d240.2ff978a8.6)
 179    time 71.440569, pid 33658: Returning code 2 from 19
 180    time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2)
 181    time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
 182    AFS Trace Dump - Completed
 183
 184 </PRE>
 185 <P>The following command dumps the trace log associated with the <B>cm</B>
 186 event set on the local machine to the file
 187 <B>cmfx.dump.file.1</B>, using the default interval
 188 of 10 seconds between successive dumps:
 189 <PRE>   # <B>fstrace dump -follow cmfx -file cmfx.dump.file.1</B>
 190
 191 </PRE>
 192 <P><STRONG>Privilege Required</STRONG>
 193 <P>The issuer must be logged in as the local superuser <B>root</B>.
 194 <P><STRONG>Related Information</STRONG>
 195 <P><A HREF="auarf041.htm#HDRAFSZCM">afszcm.cat</A>
 196 <P><A HREF="auarf169.htm#HDRFSTRACE_INTRO">fstrace</A>
 197 <P><A HREF="auarf174.htm#HDRFSTRACE_LSLOG">fstrace lslog</A>
 198 <P><A HREF="auarf176.htm#HDRFSTRACE_SETLOG">fstrace setlog</A>
 199 <P><A HREF="auarf175.htm#HDRFSTRACE_LSSET">fstrace lsset</A>
 200 <P>
 201 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf171.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf173.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 202 <!-- Begin Footer Records  ========================================== -->
 203 <P><HR><B>
 204 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 205 </B>
 206 <!-- End Footer Records  ============================================ -->
 207 <A NAME="Bot_Of_Page"></A>
 208 </BODY></HTML>