PERF-TRACE(1) perf Manual PERF-TRACE(1)

perf-trace - ابزاری الهام‌گرفته از strace

perf trace
perf trace record

این دستور رویدادهای مرتبط با هدف را نمایش می‌دهد؛ در ابتدا فراخوانی‌های سیستمی (syscalls)، اما سایر رویدادهای سیستم مانند خطاهای صفحه (pagefaults)، رویدادهای چرخه حیات وظایف، رویدادهای زمان‌بندی و غیره را نیز شامل می‌شود.

این ابزار علاوه بر کار با فایل‌های perf.data مانند سایر ابزارهای perf، در حالت زنده (live mode) نیز کار می‌کند. فایل‌ها را می‌توان با استفاده از دستور perf record ایجاد کرد، اما نشست باید شامل رویدادهای raw_syscalls باشد (-e raw_syscalls:*). همچنین می‌توان از perf trace record به عنوان یک میانبر برای گنجاندن خودکار رویدادهای raw_syscalls هنگام نوشتن رویدادها در فایل استفاده کرد.

گزینه‌های زیر برای perf trace اعمال می‌شوند؛ گزینه‌های مربوط به perf trace record در صفحه راهنمای perf record یافت می‌شوند.

-a, --all-cpus

جمع‌آوری در سطح کل سیستم از تمام CPUها.

-e, --expr, --event

فهرست فراخوانی‌های سیستمی و سایر رویدادهای perf (نقاط ردگیری یا tracepoints، رویدادهای حافظه پنهان سخت‌افزاری و غیره) برای نمایش. از تطبیق الگو (globbing) پشتیبانی می‌شود، مانند: "epoll_*"، "msg" و غیره. برای فهرست کامل رویدادها perf list را ببینید. قرار دادن ! به عنوان پیشوند، همه فراخوانی‌های سیستمی به جز موارد مشخص‌شده را نشان می‌دهد. ممکن است لازم باشد آن را اسکیپ کنید.

--filter=<filter>

فیلتر رویداد. این گزینه باید بعد از یک انتخاب‌کننده رویداد (-e) بیاید که رویداد(های) نقطه ردگیری را انتخاب می‌کند.

-D msecs, --delay msecs

پس از شروع برنامه، پیش از اندازه‌گیری به میزان msecs میلی‌ثانیه صبر کنید. این گزینه برای فیلتر کردن فاز راه‌اندازی برنامه که اغلب بسیار متفاوت است، مفید است.

-o, --output=

نام فایل خروجی.

-p, --pid=

ضبط رویدادها روی شناسه فرایند (PID) موجود (فهرست جداشده با کاما).

-t, --tid=

ضبط رویدادها روی شناسه رشته (TID) موجود (فهرست جداشده با کاما).

-u, --uid=

ضبط رویدادها در رشته‌های متعلق به uid؛ به صورت نام یا شماره.

-G, --cgroup

ضبط رویدادها در رشته‌های موجود در یک cgroup. 
برای تنظیم cgroupها در دایرکتوری /sys/fs/cgroup/perf_event جستجو کنید، سپس
بخش /sys/fs/cgroup/perf_event/ را حذف کرده و امتحان کنید:
perf trace -G A -e sched:*switch
تمام raw_syscalls:sys_{enter,exit}، pgfault، vfs_getname و غیره
_و_ sched:sched_switch را روی cgroup 'A' تنظیم می‌کند، در حالی که:
perf trace -e sched:*switch -G A
تنها رویداد sched:sched_switch را روی cgroup 'A' تنظیم خواهد کرد، تمام
رویدادهای دیگر (raw_syscalls:sys_{enter,exit} و غیره) «بدون» cgroup باقی
می‌مانند (روی cgroup ریشه، در سطح کل سیستم و غیره).
چندین cgroup:
perf trace -G A -e sched:*switch -G B
موارد syscall به cgroup 'A' و sched:sched_switch به
cgroup 'B' اختصاص می‌یابند.

--filter-pids=

فیلتر کردن رویدادها برای این pidها و برای خود trace (فهرست جداشده با کاما). -v, --verbose
افزایش سطح پرگویی خروجی.

--no-inherit

وظایف فرزند شمارنده‌ها را به ارث نمی‌برند.

-m, --mmap-pages=

تعداد صفحه‌های دادهٔ mmap (باید توانی از دو باشد) یا تعیین اندازه بر حسب بایت همراه با نویسهٔ یکای پیوست‌شده - B/K/M/G. اندازه به نزدیک‌ترین مقدار صفحه که توانی از دو باشد، رو به بالا گرد می‌شود.

-C, --cpu

جمع‌آوری نمونه‌ها تنها روی فهرست پردازنده‌های ارائه‌شده. چندین پردازنده را می‌توان به صورت یک فهرست جداشده با کاما و بدون فاصله مشخص کرد: 0,1. بازه‌های پردازنده‌ها با - مشخص می‌شوند: 0-2. در حالت per-thread هنگام فعال بودن حالت وراثت (پیش‌فرض)، رویدادها تنها زمانی ثبت می‌شوند که رشته روی پردازنده‌های تعیین‌شده اجرا شود. پیش‌فرض نظارت بر همهٔ پردازنده‌ها است.

--duration

تنها رویدادهایی را نشان می‌دهد که مدت‌زمان آن‌ها بیشتر از N.M میلی‌ثانیه بوده است.

--sched

زمان اجرای رشته را انباشته کرده و در پایان نشست یک خلاصه ارائه می‌دهد.

--failure

تنها فراخوان‌های سیستمی ناموفق را نشان می‌دهد، یعنی مواردی که مقدار < 0 برگردانده‌اند.

-i, --input

پردازش رویدادها از یک فایل دادهٔ مشخص perf.

-T, --time

چاپ برچسب زمانی کامل به جای زمان نسبی نسبت به نخستین نمونه.

--comm

نمایش COMM پردازه دقیقاً در کنار شناسهٔ آن؛ به طور پیش‌فرض فعال است، با --no-comm غیرفعال می‌شود.

-s, --summary

تنها خلاصه‌ای از فراخوان‌های سیستمی را بر پایهٔ رشته همراه با کمینه، بیشینه و میانگین زمان‌ها (به میلی‌ثانیه) و انحراف معیار نسبی (stddev) نشان می‌دهد.

-S, --with-summary

نمایش همهٔ فراخوان‌های سیستمی و به دنبال آن خلاصه‌ای بر پایهٔ رشته همراه با کمینه، بیشینه و میانگین زمان‌ها (به میلی‌ثانیه) و انحراف معیار نسبی (stddev).

--errno-summary

برای استفاده همراه با -s یا -S، جهت نمایش آمار کدهای خطای (errno) رخ‌داده در فراخوان‌های سیستمی؛ استفاده از این گزینه به تنهایی باعث فعال شدن --summary می‌شود.

--summary-mode=mode

برای استفاده همراه با -s یا -S، جهت انتخاب نحوهٔ نمایش خلاصه. به طور پیش‌فرض خلاصهٔ فراخوان‌های سیستمی بر پایهٔ رشته نشان داده می‌شود. مقادیر ممکن عبارتند از: thread، total، cgroup.

--tool_stats

نمایش آمار ابزار مانند تعداد دفعاتی که fd→pathname از طریق قلاب کردن بازگشت فراخوان سیستم open + vfs_getname یا از طریق خواندن /proc/pid/fd و غیره کشف شده است.

-f, --force

اعتراض نکن، انجام بده.

-F=[all|min|maj], --pf=[all|min|maj]

ردیابی خطاهای صفحه (pagefaults). به دلخواه می‌توانید مشخص کنید که خطاهای جزئی (minor)، عمده (major) یا همه را می‌خواهید. مقدار پیش‌فرض maj است.

--syscalls

ردیابی فراخوان‌های سیستمی. این گزینه به طور پیش‌فرض فعال است، با --no-syscalls غیرفعال می‌شود.

--call-graph [mode,type,min[,limit],order[,key][,branch]]

راه‌اندازی و فعال‌سازی ضبط call-graph (زنجیرهٔ پشته/backtrace). برای جزئیات، بخش --call-graph را در صفحات راهنمای perf-record و perf-report ببینید. مواردی که در perf trace بیشترین کاربرد را دارند dwarf و lbr هستند؛ در صورت وجود، امتحان کنید: perf trace --call-graph dwarf. 
استفاده از این گزینه، برای کاربر root، بر اساس sysctl مربوط به kernel.perf_event_mlock_kb،
مقدار --mmap-pages را به ۴ برابر حداکثر برای کاربران غیر root افزایش می‌دهد.
این کار تنها زمانی انجام می‌شود که کاربر مقداری برای --mmap-pages تعیین نکرده باشد.

--kernel-syscall-graph

نمایش زنجیره‌های فراخوانی هسته (callchains) در مسیر خروج فراخوان سیستمی.

--max-events=N

توقف پس از پردازش N رویداد. توجه داشته باشید که رویدادهای شبیه به strace فقط در زمان خروج یا هنگام وقفه در یک فراخوان سیستمی در نظر گرفته می‌شوند، یعنی در آن حالت‌ها این گزینه معادل با تعداد خط‌های چاپ‌شده است.

--switch-on EVENT_NAME

تنها رویدادهای پس از یافتن این رویداد را در نظر می‌گیرد.

--switch-off EVENT_NAME

پس از یافتن این رویداد، در نظر گرفتن رویدادها را متوقف می‌کند.

--show-on-off-events

رویدادهای مربوط به --switch-on/off را نیز نشان می‌دهد.

--show-cpu

شناسه پردازنده (cpu id) را نشان می‌دهد.

--max-stack

تنظیم حد عمق پشته هنگام تجزیهٔ زنجیره فراخوانی؛ هر چیزی فراتر از عمق مشخص‌شده نادیده گرفته خواهد شد. توجه داشته باشید که در این مرحله این صرفاً مربوط به بخش نمایش است، یعنی هسته هنوز محدودیتی اعمال نمی‌کند؛ سربار زنجیره‌های فراخوانی باید از طریق اهرم‌های کنترلی در --call-graph dwarf تنظیم شود. 
در صورت عدم وجود --call-graph در خط فرمان، روی سیستم‌هایی که
DWARF unwinding در آن‌ها تعبیه شده است، بر '--call-graph dwarf' دلالت دارد.
پیش‌فرض: /proc/sys/kernel/perf_event_max_stack در صورت وجود برای
         نشست‌های زنده (بدون --input/-i)، در غیر این صورت 127.

--min-stack

تنظیم حد عمق پشته هنگام تجزیهٔ زنجیره فراخوانی؛ هر چیزی کمتر از عمق مشخص‌شده نادیده گرفته خواهد شد. به طور پیش‌فرض غیرفعال است.
در سیستم‌هایی که باز کردن پشته DWARF به صورت توکار کامپایل شده است، در صورت عدم حضور --call-graph در خط فرمان، مستلزم '--call-graph dwarf' است.

--print-sample

اطلاعات PERF_RECORD_SAMPLE PERF_SAMPLE_ را برای نقاط ردگیری (tracepoints) raw_syscalls:sys_{enter,exit} جهت اشکال‌زدایی چاپ می‌کند.

--proc-map-timeout

هنگام پردازش رشته‌های از پیش موجود در /proc/XXX/mmap، ممکن است زمان زیادی صرف شود، زیرا فایل ممکن است بسیار حجیم باشد. در چنین مواردی به یک مهلت زمانی نیاز است. این گزینه محدودیت مهلت زمانی را تعیین می‌کند. مقدار پیش‌فرض 500 میلی‌ثانیه است.

--sort-events

مرتب‌سازی را روی دسته‌های رویدادها انجام می‌دهد؛ زمانی استفاده می‌شود که متوجه رویدادهای نامرتب شوید که ممکن است برای نمونه هنگامی رخ دهند که یک رشته در حین پردازش یک فراخوانی سیستمی به پردازنده‌ای دیگر مهاجرت می‌کند.

--libtraceevent_print

استفاده از libtraceevent برای چاپ آرگومان‌های نقطه ردگیری. به صورت پیش‌فرض perf trace از همان زیباسازهایی استفاده می‌کند که در خطوط ورود+خروج مشابه strace برای تکمیل و آراستن آرگومان‌های نقطه ردگیری به کار می‌روند.

--force-btf

استفاده از btf_dump برای چاپ زیبا (pretty print) داده‌های آرگومان‌های فراخوانی سیستمی، به جای استفاده از چاپگرهای زیبای دست‌ساز. این گزینه برای آزمایش ادغام BTF در perf trace در نظر گرفته شده است. چاپ زیبای مبتنی بر btf_dump به عنوان راهکار جایگزین پشتیبان (fallback) برای چاپگرهای زیبای دست‌ساز عمل می‌کند، چرا که دومی می‌تواند پرچم‌های عدد صحیح و اشاره‌گرهای struct را بهتر و زیباتر چاپ کند.

--bpf-summary

جمع‌آوری آمار فراخوانی‌های سیستمی در BPF. این امکان تنها برای حالت زنده است و با گزینه -s/--summary که در آن نیازی به اطلاعات آرگومان نیست، به خوبی کار می‌کند.

--max-summary=N

حداکثر تعداد خطوط در حالت خلاصه. توجه داشته باشید که این محدودیت برای هر مدخل (رشته یا cgroup) به طور جداگانه اعمال می‌شود.

هنگام ردگیری خطاهای صفحه، قالب ردگیری به شرح زیر است:

<min|maj>fault [<ip.symbol>+<ip.offset>] ⇒ <addr.dso@addr.offset[1]> (<map type><addr level>).

•عبارت min/maj نشان‌دهنده جزئی (minor) یا عمده (major) بودن رویداد خطای صفحه است؛
•عبارت ip.symbol نماد مربوط به اشاره‌گر دستورالعمل (کدی که خطا را تولید کرده) را نشان می‌دهد؛ اگر هیچ نماد اشکال‌زدایی در دسترس نباشد، perf trace مقدار خام IP را چاپ می‌کند؛
•عبارت addr.dso شیء DSO را برای آدرسی که دچار خطا شده است نشان می‌دهد؛
•نوع نگاشت (map type) یا d برای نگاشت‌های غیرقابل‌اجرا است یا x برای نگاشت‌های قابل‌اجرا؛
•سطح آدرس (addr level) یا k برای dso مربوط به هسته است یا . برای dso مربوط به سطح کاربر.

برای تفکیک نمادها ممکن است نیاز به نصب نمادهای اشکال‌زدایی داشته باشید.

لطفاً توجه داشته باشید که مقدار مدت زمان در حال حاضر همواره ۰ است و زمان واقعی صرف شده برای رسیدگی به خطا را نشان نمی‌دهد!

هنگامی که --verbose مشخص شود، perf trace تلاش می‌کند تا تمام اطلاعات موجود را برای هر دو آدرس IP و آدرس خطا در قالب dso@symbol[2]+offset چاپ کند..SH "مثال‌ها (EXAMPLES)"

ردیابی تنها خطاهای صفحه عمده (major pagefaults):

$ perf trace --no-syscalls -F

ردیابی فراخوان‌های سیستمی، خطاهای صفحه عمده و جزئی:

$ perf trace -F all
1416.547 ( 0.000 ms): python/20235 majfault [CRYPTO_push_info_+0x0] => /lib/x86_64-linux-gnu/libcrypto.so.1.0.0@0x61be0 (x.)
همان‌طور که مشاهده می‌کنید، یک خطای صفحه عمده در فرایند python رخ داده است، از
روتین CRYPTO_push_info_ که در نقطه‌ای درون libcrypto.so دچار خطا شد.

ردیابی ۴ فراخوان سیستمی نخست open، openat یا open_by_handle_at (در آینده ممکن است فراخوان‌های سیستمی بیشتری با این الگو مطابقت پیدا کنند):

$ perf trace -e open* --max-events 4
[root@jouet perf]# trace -e open* --max-events 4
2272.992 ( 0.037 ms): gnome-shell/1370 openat(dfd: CWD, filename: /proc/self/stat) = 31
2277.481 ( 0.139 ms): gnome-shell/3039 openat(dfd: CWD, filename: /proc/self/stat) = 65
3026.398 ( 0.076 ms): gnome-shell/3039 openat(dfd: CWD, filename: /proc/self/stat) = 65
4294.665 ( 0.015 ms): sed/15879 openat(dfd: CWD, filename: /etc/ld.so.cache, flags: CLOEXEC) = 3
$

ردیابی نخستین خطای صفحه جزئی هنگام اجرای یک بار کاری:

# perf trace -F min --max-stack=7 --max-events 1 sleep 1
   0.000 ( 0.000 ms): sleep/18006 minfault [__clear_user+0x1a] => 0x5626efa56080 (?k)
                                     __clear_user ([kernel.kallsyms])
                                     load_elf_binary ([kernel.kallsyms])
                                     search_binary_handler ([kernel.kallsyms])
                                     __do_execve_file.isra.33 ([kernel.kallsyms])
                                     __x64_sys_execve ([kernel.kallsyms])
                                     do_syscall_64 ([kernel.kallsyms])
                                     entry_SYSCALL_64 ([kernel.kallsyms])
#

ردیابی خطای صفحه جزئی بعدی که بر روی اولین پردازنده رخ می‌دهد:

# perf trace -F min --call-graph=dwarf --max-events 1 --cpu 0
   0.000 ( 0.000 ms): Web Content/17136 minfault [js::gc::Chunk::fetchNextDecommittedArena+0x4b] => 0x7fbe6181b000 (?.)
                                     js::gc::FreeSpan::initAsEmpty (inlined)
                                     js::gc::Arena::setAsNotAllocated (inlined)
                                     js::gc::Chunk::fetchNextDecommittedArena (/usr/lib64/firefox/libxul.so)
                                     js::gc::Chunk::allocateArena (/usr/lib64/firefox/libxul.so)
                                     js::gc::GCRuntime::allocateArena (/usr/lib64/firefox/libxul.so)
                                     js::gc::ArenaLists::allocateFromArena (/usr/lib64/firefox/libxul.so)
                                     js::gc::GCRuntime::tryNewTenuredThing<JSString, (js::AllowGC)1> (inlined)
                                     js::AllocateString<JSString, (js::AllowGC)1> (/usr/lib64/firefox/libxul.so)
                                     js::Allocate<JSThinInlineString, (js::AllowGC)1> (inlined)
                                     JSThinInlineString::new_<(js::AllowGC)1> (inlined)
                                     AllocateInlineString<(js::AllowGC)1, unsigned char> (inlined)
                                     js::ConcatStrings<(js::AllowGC)1> (/usr/lib64/firefox/libxul.so)
                                     [0x18b26e6bc2bd] (/tmp/perf-17136.map)
#

ردیابی دو رویداد sched:sched_switch بعدی، چهار رویداد block:*_plug، رویداد block:*_unplug بعدی و سه رویداد net:*dev_queue بعدی، مورد آخر با ردیابی بازگشتی (backtrace) با حداکثر ۱۶ مدخل، در سطح کل سیستم:

# perf trace -e sched:*switch/nr=2/,block:*_plug/nr=4/,block:*_unplug/nr=1/,net:*dev_queue/nr=3,max-stack=16/
   0.000 :0/0 sched:sched_switch:swapper/2:0 [120] S ==> rcu_sched:10 [120]
   0.015 rcu_sched/10 sched:sched_switch:rcu_sched:10 [120] R ==> swapper/2:0 [120]
 254.198 irq/50-iwlwifi/680 net:net_dev_queue:dev=wlp3s0 skbaddr=0xffff93498051f600 len=66
                                     __dev_queue_xmit ([kernel.kallsyms])
 273.977 :0/0 net:net_dev_queue:dev=wlp3s0 skbaddr=0xffff93498051f600 len=78
                                     __dev_queue_xmit ([kernel.kallsyms])
 274.007 :0/0 net:net_dev_queue:dev=wlp3s0 skbaddr=0xffff93498051ff00 len=78
                                     __dev_queue_xmit ([kernel.kallsyms])
2930.140 kworker/u16:58/2722 block:block_plug:[kworker/u16:58]
2930.162 kworker/u16:58/2722 block:block_unplug:[kworker/u16:58] 1
4466.094 jbd2/dm-2-8/748 block:block_plug:[jbd2/dm-2-8]
8050.123 kworker/u16:30/2694 block:block_plug:[kworker/u16:30]
8050.271 kworker/u16:30/2694 block:block_plug:[kworker/u16:30]
#

perf-record(1), perf-script(1)

1.
addr.dso@addr.offset
mailto:addr.dso@addr.offset
2.
dso@symbol
mailto:dso@symbol
09/04/2026 perf