TRACE-CMD-ATTACH(1)

📦
version 3.4 · 10 versions
, in arch rolling

💫 TRACE-CMD-ATTACH 💫

okay bestie, so this is trace-cmd-attach(1) from the libtracefs manual, and honestly? it's giving "reunite the two halves of the friend group" energy. let's get into it 🫶

✨ NAME ✨

trace-cmd-attach — attach a guest trace.dat file to a host trace.dat file. literally just introducing two trace files to each other so they can be besties 💖

🌸 SYNOPSIS 🌸

trace-cmd attach [OPTIONS] host-trace-file guest-trace-file guest-pid
[guest-pid ...]

🦋 DESCRIPTION 🦋

so the trace-cmd(1) attach command is what you use when you've got a trace.dat file that was made on a guest and you want to glue it onto a trace.dat file that was made on the host. and no, you can't just introduce them and hope for the best — this tool does the actual work.

in most cases trace-cmd-agent(1) can handle all of this for you automatically (iconic, effortless, love that for you). but if for some reason the agent isn't the vibe, you might need to kick off trace-cmd recording on the guest yourself using trace-cmd-record(1). then if the host recording is activated at the same time, you can bring in trace-cmd attach(1) to connect the guest and host files as if they'd been created by the trace-cmd agent all along. no cap. ✨

  • host-trace-file — the trace.dat file created by the host. must have kvm_exit and kvm_entry events, and it must be using the "tsc2nsec" clock. non-negotiable bestie.
  • guest-trace-file — the trace.dat file created by the guest. must use the "x86-tsc" clock. for now this is only supported on x86 — it may support other achitectures later 👀
  • guest-pid — the process ID of the host thread that represents the guest's threads. list every process ID that represents all of the guest vCPUs. and note: you can add more than just the threads that represent the guest vCPUs, because the tool will search the host-trace-file for kvm_exit and kvm_entry events to match those PIDs with the vCPUs they represent. she does her own detective work 💅

💜 OPTIONS 💜

  • -c cpus — specify a the number of CPUS the guest has. (yes, the manpage really says "a the", we're keeping it, it's part of the lore 🎀)
  • -s timeshift — a comma separated list of the format offset,scale,frac,timestamp. these values map to what are given in /sys/kernel/kvm/<pid>/vcpu/* :
    • offset: is the offset of the guest. "tsc-offest" in the directory. note that the value listed here is the negative of what is listed in the directory. 🙈
    • scale: the scaling factor. "tsc-scaling-ratio"
    • frac: the fraction bits. "tsc-scaling-ratio-frac-bits"
    • timestamp: the timestamp to start using the above. in some cases, the values may change over time. by adding a timestamp, it will take effect after the timestamp has been hit. normally this would be zero.

currently, only one timeshift is given per CPU. one -s option should be given for each CPU. if there are less options than CPUs, then the last option given will be used for the rest of the CPUs. if only one option is given, then the values for that option will be used for all CPUs. she's flexible like that 🌈

🎀 EXAMPLES 🎀

enable all events for tracing:

$ # find the process for a given guest
$ ps aux |grep qemu
libvirt+   63170  5.6  1.6 13994848 4257540 ?    Sl   May02 2884:49 /usr/bin/qemu-system-x86_64...

$ # Use 63170 to find all the PIDs for the give guest
$ ls /proc/63170/task
1541591  63170  63198  63209  63211  63213  63214  63215  63216  63217  63218  63219  63234

$ # Find the tsc offset
$ su
# cat /sys/kernel/debug/kvm/63170-15/vcpu0/tsc-offset
-27950965013436847

# trace-cmd record -C tsc2nsec -e kvm -e sched -e irq -e timer

on guest:

# trace-cmd record -C x86-tsc -e sched -e irq -e timer sleep 10

back on host, hit Ctrl+^+C to stop tracing after the guest is done:

# # Make the trace.dat user owned by your user account.
# chown user.user trace.dat
# exit

$ scp root@guest:trace.dat trace-guest.dat

$ # now attach the two files (guest has 8 CPUs)
$ trace-cmd attach -c 8 -s 27950965013436847 trace.dat trace-guest.dat 1541591  63170  63198  63209  63211  63213  63214  63215  63216  63217  63218  63219  63234

$ trace-cmd report -i trace.dat -i trace-guest.dat
$ # now you should see the guest trace interleaved within the host trace.

and that's it — now you should see the guest trace interleaved within the host trace. the two files are officially mingling 🥹🫶

🔥 SEE ALSO 🔥

trace-cmd(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), trace-cmd-profile(1)

(the whole friend group, honestly. iykyk 💫)

👑 AUTHOR 👑

written by Steven Rostedt (Google) <rostedt@goodmis.org[1]> — a real one, fr fr 🌟

⭐ 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, no details skipped, we ate and left no crumbs 💅. this was trace-cmd-attach(1) from the libtracefs manual, page dated 03/09/2026 — go forth and interleave those traces, bestie 🌸🦋💖

📦 where this page comes from