'\" t
.\"     Title: trace-cmd-attach
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 03/09/2026
.\"    Manual: libtracefs Manual
.\"    Source: libtracefs
.\"  Language: English
.\"
.TH "TRACE\-CMD\-ATTACH" "1" "03/09/2026" "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 \- ضمیمه کردن یک فایل trace\&.dat مهمان به فایل trace\&.dat میزبان
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBtrace\-cmd attach\fR [\fIOPTIONS\fR] host\-trace\-file guest\-trace\-file guest\-pid [guest\-pid \&...]
.SH "توضیحات (DESCRIPTION)"
.sp
دستور \fBtrace\-cmd attach\fR(1) برای گرفتن یک فایل trace\&.dat ایجادشده روی مهمان و ضمیمه کردن آن به یک فایل trace\&.dat که روی میزبان ایجاد شده است، به کار می‌رود\&. در بیشتر موارد، می‌توان از \fBtrace\-cmd\-agent\fR(1) برای خودکارسازی این کار استفاده کرد، اما اگر به هر دلیلی استفاده از عامل (agent) مناسب نباشد، ممکن است نیاز باشد ضبط trace\-cmd روی سیستم مهمان با \fBtrace\-cmd\-record\fR(1) آغاز شود\&. چنانچه ضبط میزبان در همان زمان فعال شده باشد، می‌توان از \fBtrace\-cmd attach\fR(1) برای اتصال فایل‌های مهمان و میزبان استفاده کرد، به همان صورتی که گویی توسط trace\-cmd agent ایجاد شده‌اند\&.
.PP
\fBhost\-trace\-file\fR
.RS 4
فایل trace\&.dat ایجادشده توسط میزبان\&. باید رویدادهای kvm_exit و kvm_entry را داشته باشد و از ساعت \(lqtsc2nsec\(rq استفاده کند\&.
.RE
.PP
\fBguest\-trace\-file\fR
.RS 4
فایل trace\&.dat ایجادشده توسط مهمان\&. باید از ساعت \(lqx86\-tsc\(rq استفاده کند\&. در حال حاضر، این قابلیت تنها روی x86 پشتیبانی می‌شود و ممکن است بعداً از سایر معماری‌ها نیز پشتیبانی کند\&.
.RE
.PP
\fBguest\-pid\fR
.RS 4
شناسهٔ فرایند (PID) مربوط به نخ میزبان که نشان‌دهندهٔ نخ‌های مهمان است\&. باید هر شناسهٔ فرایندی که نمایندهٔ تمام vCPUهای مهمان است فهرست شود\&. توجه داشته باشید که می‌توانید مواردی بیش از صرفاً نخ‌های نمایندهٔ vCPUهای مهمان را اضافه کنید، چرا که این ابزار در
\fBhost\-trace\-file\fR
به دنبال رویدادهای kvm_exit و kvm_entry خواهد گشت تا این PIDها را با vCPUهایی که نشان می‌دهند تطبیق دهد\&.
.RE
.SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-c\fR \fIcpus\fR
.RS 4
تعداد CPUهای سیستم مهمان را مشخص می‌کند\&.
.RE
.PP
\fB\-s\fR \fItimeshift\fR
.RS 4
یک فهرست جداشده با کاما در قالب
\fIoffset\fR,\fIscale\fR,\fIfrac\fR,\fItimestamp\fR
این مقادیر با مواردی که در مسیر /sys/kernel/kvm/<pid>/vcpu/* داده شده‌اند مطابقت دارند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
*offset*: آفست مهمان است؛ "tsc\-offset" در دایرکتوری\&. توجه داشته
          باشید که مقدار ذکرشده در اینجا، قرینهٔ (منفی) مقداری است
          که در دایرکتوری آمده است\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
*scale*:  ضریب مقیاس‌بندی؛ "tsc\-scaling\-ratio"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
*frac*:   بیت‌های کسری؛ "tsc\-scaling\-ratio\-frac\-bits"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
*timestamp*: برچسب زمانی برای شروع استفاده از مقادیر بالا\&. در برخی موارد،
          ممکن است مقادیر در طول زمان تغییر کنند\&. با افزودن برچسب زمانی،
          پس از رسیدن به آن زمان اعمال خواهد شد\&. معمولاً
          این مقدار صفر خواهد بود\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
در حال حاضر، برای هر CPU تنها یک timeshift مشخص می‌شود\&. برای هر CPU باید
یک گزینهٔ *\-s* داده شود\&. اگر تعداد گزینه‌ها کمتر از CPUها باشد، آخرین گزینهٔ
ارائه‌شده برای باقی CPUها استفاده خواهد شد\&. چنانچه تنها یک گزینه ارائه شده
باشد، مقادیر آن گزینه برای تمام CPUها اعمال خواهد شد\&.
.fi
.if n \{\
.RE
.\}
.RE
.SH "مثال‌ها (EXAMPLES)"
.sp
فعال‌سازی همهٔ رویدادها برای ردگیری:
.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 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\&.
.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 "نویسندگان (AUTHORS)"
.sp
نوشته‌شده توسط 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 "کپی‌رایت و تکثیر (COPYRIGHT)"
.sp
کپی‌رایت \(C\) ۲۰۱۰ Red Hat, Inc\&. استفاده آزاد از این نرم‌افزار تحت شرایط مجوز عمومی همگانی گنو (GPL) مجاز است\&.
.SH "نکات (NOTES)"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE