FSTRACE_DUMP(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💅 FSTRACE_DUMP ✨

okay bestie, welcome to fstrace_dump — a page from the AFS Command Reference, section 8 (that's the admin-commands section, iykyk). Sit down, grab a strawberry, we're dumping a trace log together. 🍓

🌸 NAME 🌸

fstrace_dump — it dumps a trace log. that's it. that's the whole job. iconic, honestly. 👑

🎀 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]

lowkey obsessed with how every long option has a tiny little nickname version. the abbreviations are right there, matching the first letters, slay. ✨

🦋 DESCRIPTION 🦋

so the fstrace dump command shows you the current contents of the "cmfx" trace log. it either puts it on the standard output stream, or it writes it into the file you name with the -file argument. you pick. main character choice. 💖

and listen — if you want the log written continuously, over and over, to stdout or to a file, that's what the -follow argument is for. by default, the log's contents get written out every ten seconds and then automatically cleared. yes, cleared. every ten seconds. to change how long it waits between writes, use the -sleep argument. periodt.

⚠️ CAUTIONS ⚠️

okay this is the part where we get serious for a sec, bestie, because there are real gotchas here.

  • this command only produces output if the "cm" event set is active. like, if it's not active, you get nothing. if you need to display or set the event set's state, use fstrace lsset or fstrace setset respectively. those are your girls.
  • for the output of this command to be maximally readable, the message catalog file called afszcm.cat must live in the local /etc/openafs/C directory. if it's not there, copy the file into that directory from the AFS Binary Distribution before you activate tracing. do not skip this step, I'm begging. 🙈
  • when the "cm" event set is active, a defined amount of kernel memory (by default, 60 KB) gets allocated for the "cmfx" trace log. and as it says over in fstrace(8), when that buffer fills up, messages get overwritten in a circular fashion — new messages overwrite the oldest ones. so the oldest tea gets spilled first. if you want to allocate more kernel memory for the log, use the fstrace setlog command. and if you want to see the log buffer's current size, use fstrace lslog with the -long argument.
fr fr: tracing is not free and the buffer is not infinite. plan accordingly. 💀

✨ OPTIONS ✨

here's the full roster, every single one, no skips:

  • -set <set name>+ — names the event set whose associated trace log you want written out. the only acceptable value is "cm" (and the associated trace log for it is "cmfx", cute matching set 💜). 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 -sleep to change that interval). the log gets cleared after every write operation, no cap. 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 write the trace log's contents into. it can be in AFS or on the local disk, whichever. partial pathnames are interpreted relative to the current working directory. if you omit this argument, the trace log goes to the standard output stream instead.
  • -sleep <seconds between reads> — sets the number of seconds between writes of the trace log's contents when it's being dumped continuously. you gotta provide the -follow argument alongside this one, they're a duo. if you omit this, the default interval is ten seconds.
  • -help — prints the online help for this command. and heads up: all other valid options are ignored when you use this one. so don't bother stacking them. 😭

📜 OUTPUT 📜

the output starts with a header specifying the date and time at which the write operation began. if the -follow argument isn't included, that header also reports the number of logs being dumped — and it is always 1, because there is only the "cmfx" trace log. one log. one girl. 🎀 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 this 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. these are generally meaningful only to someone familiar with the AFS source code. so if it looks like cryptic gibberish to you? that's normal, bestie, you're not doing anything wrong. 🙈

on top of all that — every 1024 seconds, the fstrace command interpreter writes a message recording the current clock time, in this 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, represented in the standard UNIX time format as the number of seconds since midnight on January 1, 1970. (yes, the epoch. the origin story. 🕛)

use this message to determine the actual clock time associated with each log message. determine the actual time like this:

  1. locate the message of interest.
  2. search backward through the trace file for the closest current time message.
  3. 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.
  4. add the resulting number to the current time message's <unix_time> to determine the log message's actual time.
and if any of the data in the kernel trace buffer has been overwritten since tracing was activated, this message shows up at the appropriate place in the output:
Log wrapped; data missing.

bestie, "data missing" is giving heartbreak. 💀 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.

and finally, this message at the end of the log dump means it's all done:

AFS Trace Dump - Completed

🌈 EXAMPLES 🌈

okay show-and-tell time. this first 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

and this second command dumps the trace log associated with the cm event set on the local machine into 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

ate. no crumbs. 🫶

👑 PRIVILEGE REQUIRED 👑

the issuer must be logged in as the local superuser "root". yes queen, you need the big keys for this one. 🔑

🔗 SEE ALSO 🔗

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

go read those too, they're the rest of the lore. 💜

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.

that's the whole page, bestie, every last flag and timestamp intact. this cutie is from the OpenAFS collection and it's dated 2026-07-27. stay traced, stay slayed. 💅✨🦋

📦 where this page comes from