TRACE-CMD-ATTACH(1)            libtracefs Manual           TRACE-CMD-ATTACH(1)

نام (NAME)
       trace-cmd-attach - ضمیمه کردن یک فایل trace.dat مهمان به فایل trace.dat
       میزبان

خلاصه دستور (SYNOPSIS)
       trace-cmd attach [OPTIONS] host-trace-file guest-trace-file guest-pid
       [guest-pid ...]

توضیحات (DESCRIPTION)
       دستور trace-cmd attach(1) برای گرفتن یک فایل trace.dat ایجادشده روی
       مهمان و ضمیمه کردن آن به یک فایل trace.dat که روی میزبان ایجاد شده است،
       به کار می‌رود. در بیشتر موارد، می‌توان از trace-cmd-agent(1) برای
       خودکارسازی این کار استفاده کرد، اما اگر به هر دلیلی استفاده از عامل
       (agent) مناسب نباشد، ممکن است نیاز باشد ضبط trace-cmd روی سیستم مهمان
       با trace-cmd-record(1) آغاز شود. چنانچه ضبط میزبان در همان زمان فعال
       شده باشد، می‌توان از trace-cmd attach(1) برای اتصال فایل‌های مهمان و
       میزبان استفاده کرد، به همان صورتی که گویی توسط trace-cmd agent ایجاد
       شده‌اند.

       host-trace-file
           فایل trace.dat ایجادشده توسط میزبان. باید رویدادهای kvm_exit و
           kvm_entry را داشته باشد و از ساعت “tsc2nsec” استفاده کند.

       guest-trace-file
           فایل trace.dat ایجادشده توسط مهمان. باید از ساعت “x86-tsc” استفاده
           کند. در حال حاضر، این قابلیت تنها روی x86 پشتیبانی می‌شود و ممکن است
           بعداً از سایر معماری‌ها نیز پشتیبانی کند.

       guest-pid
           شناسهٔ فرایند (PID) مربوط به نخ میزبان که نشان‌دهندهٔ نخ‌های مهمان است.
           باید هر شناسهٔ فرایندی که نمایندهٔ تمام vCPUهای مهمان است فهرست شود.
           توجه داشته باشید که می‌توانید مواردی بیش از صرفاً نخ‌های نمایندهٔ
           vCPUهای مهمان را اضافه کنید، چرا که این ابزار در host-trace-file به
           دنبال رویدادهای kvm_exit و kvm_entry خواهد گشت تا این PIDها را با
           vCPUهایی که نشان می‌دهند تطبیق دهد.

گزینه‌ها (OPTIONS)
       -c cpus
           تعداد CPUهای سیستم مهمان را مشخص می‌کند.

       -s timeshift
           یک فهرست جداشده با کاما در قالب offset,scale,frac,timestamp این
           مقادیر با مواردی که در مسیر /sys/kernel/kvm/<pid>/vcpu/* داده
           شده‌اند مطابقت دارند.

               *offset*: آفست مهمان است؛ "tsc-offset" در دایرکتوری. توجه داشته
                         باشید که مقدار ذکرشده در اینجا، قرینهٔ (منفی) مقداری است
                         که در دایرکتوری آمده است.

               *scale*:  ضریب مقیاس‌بندی؛ "tsc-scaling-ratio"

               *frac*:   بیت‌های کسری؛ "tsc-scaling-ratio-frac-bits"

               *timestamp*: برچسب زمانی برای شروع استفاده از مقادیر بالا. در برخی موارد،
                         ممکن است مقادیر در طول زمان تغییر کنند. با افزودن برچسب زمانی،
                         پس از رسیدن به آن زمان اعمال خواهد شد. معمولاً
                         این مقدار صفر خواهد بود.

               در حال حاضر، برای هر CPU تنها یک timeshift مشخص می‌شود. برای هر CPU باید
               یک گزینهٔ *-s* داده شود. اگر تعداد گزینه‌ها کمتر از CPUها باشد، آخرین گزینهٔ
               ارائه‌شده برای باقی CPUها استفاده خواهد شد. چنانچه تنها یک گزینه ارائه شده
               باشد، مقادیر آن گزینه برای تمام CPUها اعمال خواهد شد.

مثال‌ها (EXAMPLES)
       فعال‌سازی همهٔ رویدادها برای ردگیری:

             $ # 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.

همچنین ببینید (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)

نویسندگان (AUTHORS)
       نوشته‌شده توسط Steven Rostedt (Google) <rostedt@goodmis.org[1]>

منابع (RESOURCES)
       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git

کپی‌رایت و تکثیر (COPYRIGHT)
       کپی‌رایت ) ۲۰۱۰ Red Hat, Inc. استفاده آزاد از این نرم‌افزار تحت شرایط
       مجوز عمومی همگانی گنو (GPL) مجاز است.

نکات (NOTES)
        1. rostedt@goodmis.org
           mailto:rostedt@goodmis.org

libtracefs                        03/09/2026               TRACE-CMD-ATTACH(1)