PERF-ANNOTATE(1) perf Manual PERF-ANNOTATE(1)

perf-annotate - خواندن perf.data (ایجاد شده توسط perf record) و نمایش کد حاشیه‌نویسی‌شده

perf annotate [-i <file> | --input=file] [symbol_name]

این دستور فایل ورودی را می‌خواند و نسخه‌ای حاشیه‌نویسی‌شده از کد را نمایش می‌دهد. اگر فایل شیء دارای نمادهای اشکال‌زدایی (debug symbols) باشد، کد منبع در کنار کد اسمبلی نمایش داده خواهد شد.

اگر اطلاعات اشکال‌زدایی در فایل شیء موجود نباشد، کد اسمبلی حاشیه‌نویسی‌شده نمایش داده می‌شود.

-i, --input=<file>

نام فایل ورودی. (پیش‌فرض: perf.data مگر اینکه stdin یک fifo باشد)

-d, --dsos=<dso[,dso...]>

تنها نمادهای موجود در این dsoها را در نظر بگیر.

-s, --symbol=<symbol>

نمادی که باید حاشیه‌نویسی شود.

-f, --force

اعتبارسنجی مالکیت انجام نشود.

-v, --verbose

ارائه توضیحات بیشتر. (نمایش آدرس نماد و غیره)

-q, --quiet

هیچ هشدار یا پیامی نمایش داده نشود. (غیرفعال کردن -v)

-n, --show-nr-samples

نمایش تعداد نمونه‌ها برای هر نماد.

-D, --dump-raw-trace

تخلیه داده‌های ردیابی خام در قالب ASCII.

-k, --vmlinux=<file>

مسیر فایل vmlinux.

--ignore-vmlinux

نادیده گرفتن فایل‌های vmlinux.

--itrace

گزینه‌هایی برای رمزگشایی داده‌های ردیابی دستورالعمل (instruction tracing). گزینه‌ها عبارتند از: 
i       تولید رویدادهای instructions
y       تولید رویدادهای cycles
b       تولید رویدادهای branches
c       تولید رویدادهای branches (فقط calls)
r       تولید رویدادهای branches (فقط returns)
x       تولید رویدادهای transactions
w       تولید رویدادهای ptwrite
p       تولید رویدادهای power (شامل رویدادهای PSB برای Intel PT)
o       تولید سایر رویدادهای ضبط‌شده بر اثر استفاده
        از aux-output (به perf record مراجعه کنید)
I       تولید رویدادهای وقفه یا مشابه آن (ناهمگام)
        (مانند Intel PT Event Trace)
e       تولید رویدادهای error
d       ایجاد یک گزارش اشکال‌زدایی (debug log)
f       تولید رویدادهای حافظه پنهان سطح اول (first level cache)
m       تولید رویدادهای حافظه پنهان سطح آخر (last level cache)
M       تولید رویدادهای حافظه (memory)
t       تولید رویدادهای TLB
a       تولید رویدادهای دسترسی از راه دور (remote access)
g       تولید یک زنجیره فراخوانی (همراه با i یا x استفاده شود)
G       تولید یک زنجیره فراخوانی روی رکوردهای رویداد موجود
l       تولید ورودی‌های آخرین شاخه (همراه با i یا x استفاده شود)
L       تولید ورودی‌های آخرین شاخه روی رکوردهای رویداد موجود
s       رد کردن تعداد اولیه‌ای از رویدادها
q       رمزگشایی سریع‌تر (با جزئیات کمتر)
A       تقریب زدن IPC
Z       ترجیح دادن نادیده گرفتن برچسب‌های زمانی (رمزگشایی به‌اصطلاح "timeless")
T       استفاده از برچسب زمانی ردیابی به عنوان زمان هسته (kernel time)
حالت پیش‌فرض شامل تمام رویدادها است، یعنی معادل با --itrace=iybxwpe،
به جز برای perf script که در آن به صورت --itrace=ce است
علاوه بر این، دوره (پیش‌فرض 100000، به جز برای perf script که در آن 1 است)
برای رویدادهای instructions را می‌توان برحسب واحدهای زیر مشخص کرد:
i       دستورالعمل‌ها (instructions)
t       تیک‌ها (ticks)
ms      میلی‌ثانیه (milliseconds)
us      میکروثانیه (microseconds)
ns      نانوثانیه (nanoseconds) (پیش‌فرض)
همچنین اندازه زنجیره فراخوانی (پیش‌فرض 16، حداکثر 1024) برای رویدادهای
instructions یا transactions می‌تواند مشخص شود.
همچنین می‌توان تعداد مدخل‌های آخرین شاخه (پیش‌فرض 64، حداکثر 1024) را برای
رویدادهای instructions یا transactions مشخص کرد.
مشابه گزینه‌های g و l، می‌توان اندازه را برای گزینه‌های G و L نیز مشخص کرد.
در x86، توجه داشته باشید که G و L هنگامی که داده‌ها با PEBS بزرگ ثبت شده
باشند، عملکرد ضعیفی دارند. برای جزئیات به صفحه راهنمای linkperf:perf-intel-pt[1] مراجعه کنید.
همچنین این امکان وجود دارد که رویدادهای تولیدشده در ابتدا (instructions، branches،
transactions، ptwrite، power) نادیده گرفته شوند. این برای نادیده گرفتن کدهای مقداردهی اولیه مفید است.
--itrace=i0nss1000000
یک میلیون دستورالعمل نخست را نادیده می‌گیرد.
گزینه 'e' می‌تواند با پرچم‌هایی دنبال شود که بر گزارش شدن یا نشدن خطاها
اثر می‌گذارند. هر پرچم باید با '+' یا '-' همراه باشد.
این پرچم‌ها عبارتند از:
        o       سرریز (overflow)
        l       از دست رفتن داده‌های ردگیری (trace data lost)
در صورت پشتیبانی، گزینه 'd' می‌تواند با پرچم‌هایی همراه شود که بر ثبت شدن یا
نشدن پیام‌های اشکال‌زدایی اثر می‌گذارند. هر پرچم باید با '+' یا '-'
همراه باشد. این پرچم‌ها عبارتند از:
        a       همه رویدادهای perf
        e       خروجی فقط هنگام بروز خطا (اندازه قابل پیکربندی - ارجاع به linkperf:perf-config[1])
        o       خروجی به stdout
در صورت پشتیبانی، گزینه 'q' می‌تواند برای افزایش اثر تکرار شود.
برای غیرفعال کردن کامل رمزگشایی، از --no-itrace استفاده کنید.

-m, --modules

بارگذاری نمادهای ماژول. هشدار: فقط با -k و هسته زنده (LIVE kernel) استفاده شود.

-l, --print-line

چاپ خطوط منطبق در کد منبع (ممکن است کند باشد).

-P, --full-paths

نام مسیرهای نمایش‌داده‌شده کوتاه نشوند.

--stdio

استفاده از رابط کاربری stdio.

--stdio2

استفاده از رابط کاربری stdio2، غیرتعاملی، با قالب‌بندی TUI.

--stdio-color=<mode>

always، never یا auto؛ که امکان پیکربندی خروجی رنگی را علاوه بر "color.ui" در .perfconfig از طریق خط فرمان فراهم می‌کند. برای تولید رنگ حتی در زمان هدایت خروجی به یک لوله (pipe) یا فایل، از --stdio-color always استفاده کنید. استفاده از --stdio-color به‌تنهایی، معادل استفاده از always است.

--tui

استفاده از رابط کاربری TUI. استفاده از --tui نیازمند یک tty است؛ اگر tty موجود نباشد، مانند زمان هدایت خروجی به دستورهای دیگر، از رابط stdio استفاده می‌شود. این رابط با تمرکز بر خط دارای بیشترین نمونه‌ها شروع به کار می‌کند؛ کلیدهای TAB/UNTAB میان خطوط با نمونه‌های بیشتر جابه‌جا می‌شوند.

--gtk

استفاده از رابط کاربری GTK.

-C, --cpu=<cpu>

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

--asm-raw

نمایش کدگذاری خام دستورالعمل‌های اسمبلی.

--show-total-period

نمایش ستونی از مجموع دوره‌ها (periods).

--source

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

--symfs=<directory[,layout]>

جستجوی فایل‌های حاوی نمادها به صورت نسبی نسبت به این دایرکتوری. چینش اختیاری (layout) می‌تواند hierarchy (پیش‌فرض، تطابق با مسیر کامل) یا flat (تنها تطابق با نام پایه) باشد. این گزینه زمانی مفید است که فایل‌های اشکال‌زدایی در یک ساختار دایرکتوری مسطح ذخیره شده باشند. -M, --disassembler-style=
تنظیم سبک واسرهم‌ساز (disassembler) برای objdump.

--addr2line=<path>

مسیر باینری addr2line.

--objdump=<path>

مسیر باینری objdump.

--prefix=PREFIX, --prefix-strip=N

حذف N جزء نخست از نام مسیر فایل‌های منبع در فایل‌های اجرایی و افزودن PREFIX. این قابلیت امکان نمایش کد منبع کامپایل‌شده روی سیستم‌هایی با ساختار فایل‌سیستم متفاوت را فراهم می‌کند.

--skip-missing

رد کردن نمادهایی که امکان حاشیه‌نویسی آن‌ها وجود ندارد.

--group

نمایش اطلاعات گروه رویداد در کنار هم

--demangle

برگرداندن نام نمادها (demangle) به شکل خوانا برای انسان. این ویژگی به‌طور پیش‌فرض فعال است؛ با --no-demangle غیرفعال می‌شود.

--demangle-kernel

برگرداندن نام نمادهای هسته به شکل خوانا برای انسان (برای هسته‌های C++).

--percent-type

تنظیم نوع درصد حاشیه‌نویسی از میان گزینه‌های زیر: global-period، local-period، global-hits، local-hits 
کلیدواژه‌های local/global مشخص می‌کنند که درصد در حوزهٔ
تابع (local) محاسبه شود یا در کل داده‌ها (global).
کلیدواژه‌های period/hits پایه‌ای را که درصد بر مبنای آن
محاسبه می‌شود تعیین می‌کنند - دورهٔ نمونه‌ها یا تعداد نمونه‌ها (hits).

--percent-limit

عدم نمایش توابعی که سربار (overhead) آن‌ها در stdio یا stdio2 کمتر از این درصد است (پیش‌فرض: 0). توجه داشته باشید که این موضوع دربارهٔ انتخاب توابع جهت نمایش است، نه خطوط درون تابع.

--data-type[=TYPE_NAME]

نمایش حاشیه‌نویسی نوع داده به‌جای کد. این گزینه با استفاده از اطلاعات اشکال‌زدایی DWARF نوع دادهٔ نمونه‌ها را (اگر دستورالعمل‌های دسترسی به حافظه باشند) استنتاج می‌کند. این گزینه می‌تواند یک آرگومان اختیاری برای نام نوع داده دریافت کند. در این صورت حاشیه‌نویسی فقط برای آن نوع نمایش داده می‌شود؛ در غیر این صورت تمامی انواع داده‌های یافته‌شده نشان داده خواهند شد.

--type-stat

نمایش آمار برای حاشیه‌نویسی نوع داده.

--skip-empty

عدم نمایش رویدادهای خالی (یا ساختگی).

--code-with-type

نمایش اطلاعات نوع داده در حاشیه‌نویسی کد (تنها برای دستورالعمل‌های حافظه).

perf-record(1), perf-report(1)

09/04/2026 perf