Commit | Line | Data |
---|---|---|
805e021f CE |
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. |