'\" t
.\" Title: trace-cmd-attach
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 02/10/2024
.\" Manual: libtracefs Manual
.\" Source: libtracefs
.\" Language: English
.\"
.TH "TRACE\-CMD\-ATTACH" "1" "02/10/2024" "libtracefs" "libtracefs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
trace-cmd-attach \- attach a guest trace\&.dat file to a host trace\&.dat file
.SH "SYNOPSIS"
.sp
\fBtrace\-cmd attach\fR [\fIOPTIONS\fR] host\-trace\-file guest\-trace\-file guest\-pid [guest\-pid \&...]
.SH "DESCRIPTION"
.sp
The trace\-cmd(1) attach is used to take a trace\&.dat file created on a guest and attach it to a trace\&.dat file that was created on the host\&. In most cases, trace\-cmd\-agent(1) can be used to automate this, but if for some reason, the agent isn\(cqt appropriate, it may be required to start trace\-cmd recording on the guest with trace\-cmd\-record(1)\&. If the host recording is activated at the same time, one can use trace\-cmd attach(1) to connect the guest and host files as if they were created by the trace\-cmd agent\&.
.PP
\fBhost\-trace\-file\fR
.RS 4
The trace\&.dat file created by the host\&. Must have kvm_exit and kvm_entry events, and use the "tsc2nsec" clock\&.
.RE
.PP
\fBguest\-trace\-file\fR
.RS 4
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\&.
.RE
.PP
\fBguest\-pid\fR
.RS 4
The process ID of the host thread that represents the guests threads\&. Each process ID that represents all of the guest vCPUs should be listed\&. Note, you can add more than just the threads that represent the guest vCPUs, as the tool will search the
\fBhost\-trace\-file\fR
for kvm_exit and kvm_entry events to match these PIDs with the vCPUs that they represent\&.
.RE
.SH "OPTIONS"
.PP
\fB\-c\fR \fIcpus\fR
.RS 4
Specify a the number of CPUS the guest has\&.
.RE
.PP
\fB\-s\fR \fItimeshift\fR
.RS 4
A comma separated list of the format
\fIoffset\fR,\fIscale\fR,\fIfrac\fR,\fItimestamp\fR
These values map to what are given in /sys/kernel/kvm//vcpu/*
.sp
.if n \{\
.RS 4
.\}
.nf
*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\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
*scale*: The scaling factor\&. "tsc\-scaling\-ratio"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
*frac*: The fraction bits\&. "tsc\-scaling\-ratio\-frac\-bits"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
*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\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
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\&.
.fi
.if n \{\
.RE
.\}
.RE
.SH "EXAMPLES"
.sp
Enable all events for tracing:
.sp
.if n \{\
.RS 4
.\}
.nf
$ # 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 tsc2nesc \-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\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
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)
.SH "AUTHOR"
.sp
Written by Steven Rostedt (Google) <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/utils/trace\-cmd/trace\-cmd\&.git/\fR\m[]
.SH "COPYING"
.sp
Copyright (C) 2010 Red Hat, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.
.SH "NOTES"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE