PERF-INJECT(1) perf Manual PERF-INJECT(1)

perf-inject - فیلتری برای تقویت جریان رویدادها با اطلاعات تکمیلی

perf inject <options>

دستور perf-inject یک جریان رویداد perf-record را می‌خواند و آن را مجدداً به stdout هدایت می‌کند. در هر نقطه‌ای کد پردازش می‌تواند رویدادهای دیگری را به جریان رویداد تزریق کند - در این مورد build-idها (گزینهٔ -b) خوانده شده و در صورت نیاز به جریان رویداد تزریق می‌شوند.

شناسه‌های ساخت (Build-idها) تنها نخستین استفاده از perf-inject هستند - بالقوه هر چیزی که برای تقویت جریان رویدادها با اطلاعات تکمیلی به پردازش در فضای کاربری نیاز دارد، می‌تواند از این قابلیت بهره ببرد.

-b, --build-ids

تزریق build-idهای DSOهایی که در نمونه‌ها رخ داده‌اند به جریان خروجی. این بدان معناست که برای یافتن DSOها باید همهٔ رکوردهای SAMPLE پردازش شوند.

--buildid-all

تزریق build-idهای همهٔ DSOها به جریان خروجی صرف‌نظر از رخداد در نمونه‌ها، و چشم‌پوشی از پردازش SAMPLE.

--known-build-ids=

بازنویسی و جایگزین کردن build-idهای تزریقی با استفاده از این جفت‌های build-id و مسیر جدا شده با کاما. از file://filename برای خواندن این جفت‌ها از یک فایل (که می‌تواند توسط perf buildid-list ایجاد شده باشد) پشتیبانی می‌کند.

-v, --verbose

نمایش جزئیات بیشتر خروجی.

-i, --input=

نام فایل ورودی. (پیش‌فرض: stdin)

-o, --output=

نام فایل خروجی. (پیش‌فرض: stdout)

-s, --sched-stat

ادغام sched_stat و sched_switch برای دریافت رویدادهای مربوط به محل و مدت زمان خوابیدن تسک‌ها. رویداد sched_switch شامل یک زنجیره فراخوانی (callchain) از محل به خواب رفتن تسک است و sched_stat شامل یک برش زمانی (timeslice) از مدت زمان خوابیدن تسک است.

-k, --vmlinux=<file>

مسیر فایل vmlinux

--ignore-vmlinux

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

--kallsyms=<file>

مسیر فایل kallsyms

--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       سنتز آخرین مدخل‌های انشعاب (last branch) (استفاده همراه با i یا x)
L       سنتز آخرین مدخل‌های انشعاب روی رکوردهای رویداد موجود
s       صرف‌نظر کردن از تعداد اولیهٔ مشخصی از رویدادها
q       رمزگشایی سریع‌تر (با جزئیات کمتر)
A       تقریب IPC
Z       ترجیح بر نادیده گرفتن برچسب‌های زمانی (رمزگشایی اصطلاحاً "timeless")
T       استفاده از رد برچسب زمانی به‌عنوان زمان هسته
حالت پیش‌فرض همهٔ رویدادها است؛ یعنی مشابه --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 می‌تواند مشخص شود.
همچنین می‌توان تعداد مدخل‌های آخرین انشعاب (پیش‌فرض ۶۴، حداکثر ۱۰۲۴) را برای
رویدادهای دستورالعمل‌ها (instructions) یا تراکنش‌ها (transactions) مشخص کرد.
مشابه گزینه‌های g و l، اندازه را می‌توان برای گزینه‌های G و L نیز تعیین کرد.
در x86، توجه داشته باشید که در صورت ثبت داده‌ها با PEBS بزرگ، گزینه‌های G و L عملکرد
ضعیفی دارند. برای جزئیات به صفحه راهنمای 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' می‌تواند برای افزایش اثر تکرار شود.

--strip

همراه با --itrace برای حذف رویدادهای سنتز‌نشده (non-synthesized) به کار می‌رود.

-j, --jit

پردازش فایل‌های jitdump با تزریق رکوردهای mmap متناظر با توابع کامپایل‌شده درجا (jitted). این گزینه همچنین تصاویر ELF را برای هر تابع jitted یافت‌شده در فایل‌های jitdump ثبت‌شده در فایل ورودی perf.data ایجاد می‌کند. در صورتی که محیطی با زمان‌های اجرای JIT مانند Java، DART یا V8 را پایش می‌کنید، از این گزینه استفاده کنید.

-f, --force

شکایتی نکن، انجام بده.

--vm-time-correlation[=OPTIONS]

برخی معماری‌ها ممکن است داده‌های ناحیه AUX را ضبط کنند که شامل برچسب‌های زمانی متأثر از مجازی‌سازی است. این گزینه آن برچسب‌های زمانی را درجا به‌روزرسانی می‌کند تا با برچسب‌های زمانی میزبان (host) همبستگی داشته باشند. به‌روزرسانی درجا بدین معناست که فایل خروجی مشخص نمی‌شود و در عوض فایل ورودی تغییر می‌یابد. گزینه‌ها مختص هر معماری هستند، با این استثنا که ممکن است با "dry-run" آغاز شوند که باعث می‌شود فایل بدون به‌روزرسانی پردازش شود. در حال حاضر این گزینه فقط توسط Intel PT پشتیبانی می‌شود؛ مراجعه کنید به perf-intel-pt(1)

--guest-data=<path>,<pid>[,<time offset>[,<time scale>]]

درج رویدادها از یک فایل perf.data که در یک ماشین مجازی ثبت شده، هم‌زمان با فایلی که در میزبان ضبط می‌شده است. شناسه فرایند (PID) فرایند ناظر مجازی‌سازی (hypervisor) QEMU باید ارائه شود، و احتمالاً به اختلاف زمان (time offset) و مقیاس زمان (time scale یا ضریب) برای تبدیل برچسب‌های زمانی مهمان به برچسب‌های زمانی میزبان نیاز خواهد بود. به عنوان مثال، در x86 می‌توان TSC Offset و Multiplier را برای یک ماشین مجازی که از گزینه خط فرمان لینوکس no-kvmclock استفاده می‌کند فراهم کرد. در حال حاضر فقط رویدادهای mmap، mmap2، comm، task، context_switch، ksymbol و text_poke و همچنین اطلاعات build ID درج می‌شوند. گزینه QEMU با نام -name debug-threads=on مورد نیاز است تا بتوان از نام نخ‌ها برای تشخیص اینکه کدام نخ کدام VCPU را اجرا می‌کند بهره برد. توجه داشته باشید که به نظر می‌رسد libvirt به‌طور پیش‌فرض از این گزینه استفاده می‌کند. هنگام استفاده از perf record در مهمان، باید گزینه --sample-identifier استفاده شود، و همچنین گزینه‌های --buildid-all و --switch-events نیز ممکن است مفید باشند.

--convert-callchain

تجزیه زنجیره‌های فراخوانی DWARF و تبدیل آن‌ها به زنجیره‌های فراخوانی معمول. این کار همچنین داده‌های پشته و ثبات‌ها (registers) را از نمونه‌ها حذف می‌کند. این عمل باعث از دست رفتن مدخل‌های زنجیره فراخوانی درخط (inlined) خواهد شد.

--guestmount=<path>

دایرکتوری نقطه اتصال (mount) سیستم‌فایل ریشه سیستم‌عامل مهمان. کاربران دایرکتوری‌های ریشه سیستم‌عامل مهمان را تحت <path> با یک روش دسترسی ویژه به سیستم‌فایل، معمولاً sshfs متصل می‌کنند. به عنوان مثال، اجرای ۲ سیستم‌عامل مهمان که pid یکی ۸۸۸۸ و دیگری ۹۹۹۹ است: 
$ mkdir ~/guestmount
$ cd ~/guestmount
$ sshfs -o allow_other,direct_io -p 5551 localhost:/ 8888/
$ sshfs -o allow_other,direct_io -p 5552 localhost:/ 9999/
$ perf inject --guestmount=~/guestmount

perf-record(1), perf-report(1), perf-archive(1), perf-intel-pt(1)

09/04/2026 perf