TRACE-CMD-RESTORE(1)

📦
version 3.4 · 13 versions
, in arch rolling

💅 trace-cmd-restore(1) — the libtracefs manual, but make it make sense

okay so bestie, this one's from the libtracefs manual set and it's genuinely a lifesaver. it's trace-cmd-restore, and yes the name is lowercase in the wild but we're not doing that here 🎀

✨ NAME ✨

trace-cmd-restore — restore a failed trace record. that's it. that's the whole vibe. you had a crash, the record didn't finish, and this lil icon brings it back to life 🫶

🦋 SYNOPSIS 🦋

trace-cmd restore [OPTIONS] [command] cpu-file [cpu-file ...]

🌸 DESCRIPTION 🌸

so the trace-cmd(1) restore command will restore a crashed trace-cmd-record(1) file. like, imagine your record job just… didn't make it 😭 if for some reason a trace-cmd record fails, it leaves behind the per-cpu data files and never creates the final trace.dat. that's the sad part. the restore command is the part where we fix it — it appends those files together to create a working trace.dat file that you can actually read with trace-cmd-report(1). slay.

the way it works is: when trace-cmd record runs, it spawns off a process per CPU and writes to a per-cpu file usually called trace.dat.cpuX, where X represents the CPU number that it's tracing. if the -o option was used in the trace-cmd record, then the CPU data files will have that name instead of the trace.dat name. lowkey important to remember. and if a totally unexpected crash occurs before the tracing is finished, then the per-CPU files will still exist but there will not be any trace.dat file to read from. that's the exact moment trace-cmd restore steps in — it lets you create a trace.dat file with the existing data files. main character energy fr 💅

⭐ OPTIONS ⭐

  • -c — create a partial trace.dat file from the machine, to be used with a full trace-cmd restore at another time. this option is useful for embedded devices. if a server contains the cpu files of a crashed trace-cmd record (or trace-cmd listen), trace-cmd restore can be executed on the embedded device with the -c option to get all the stored information of that embedded device. then the file created could be copied to the server to run the trace-cmd restore there with the cpu files. iconic cross-machine workflow 🧚

if -o is not specified, then the file created will be called trace-partial.dat. this is because the file is not a full version of something that trace-cmd-report(1) could use. it's a partial, bestie, don't come for it 🙈

  • -t tracing_dir — used with -c, it overrides the location to read the events from. by default, tracing information is read from the debugfs/tracing directory. -t will use that location instead. this can be useful if the trace.dat file to create is from another machine. just tar -cvf events.tar debugfs/tracing and copy and untar that file locally, and use that directory instead. chef's kiss 🍓
  • -k kallsyms — used with -c, it overrides where to read the kallsyms file from. by default, /proc/kallsyms is used. -k will override the file to read the kallsyms from. this can be useful if the trace.dat file to create is from another machine. just copy the /proc/kallsyms file locally, and use -k to point to that file. no cap, super handy ✨
  • -o output — by default, trace-cmd restore will create a trace.dat file (or trace-partial.dat if -c is specified). you can specify a different file to write to with the -o option. name it whatever you want, live your truth 💖
  • -i input — by default, trace-cmd restore will read the information of the current system to create the initial data stored in the trace.dat file. if the crash was on another machine, then that machine should have the trace-cmd restore run with the -c option to create the trace.dat partial file. then that file can be copied to the current machine where trace-cmd restore will use -i to load that file instead of reading from the current system. literally the whole point of the partial file lol 🦋

🔥 EXAMPLES 🔥

if a crash happened on another box, you could run:

$ trace-cmd restore -c -o box-partial.dat

then on the server that has the cpu files:

$ trace-cmd restore -i box-partial.dat trace.dat.cpu0 trace.dat.cpu1

and that would create a trace.dat file for the embedded box. ate. no crumbs. 👑

💜 SEE ALSO 💜

trace-cmd(1), trace-cmd-record(1), trace-cmd-report(1), trace-cmd-start(1), trace-cmd-stop(1), trace-cmd-extract(1), trace-cmd-reset(1), trace-cmd-split(1), trace-cmd-list(1), trace-cmd-listen(1)

go read those too, iykyk 📚

🎀 AUTHOR 🎀

Written by Steven Rostedt, <rostedt@goodmis.org[1]> — ty king 🫶

🌈 RESOURCES 🌈

https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/

💀 COPYING 💀

Copyright (C) 2010 Red Hat, Inc. Free use of this software is granted under the terms of the GNU Public License (GPL).

🍓 NOTES 🍓

  1. rostedt@goodmis.org mailto:rostedt@goodmis.org

okay that's the whole page bestie, ily, go restore that crashed trace 💖✨

this lil doc was brought to you by libtracefs, dated 03/09/2026 — mwah, see u in the group chat 💅

📦 where this page comes from