نام (NAME)

perf-probe - تعریف نقاط ردیابی پویای جدید

خلاصه دستور (SYNOPSIS)

perf probe [options] --add=PROBE [...]
یا
perf probe [options] PROBE
یا
perf probe [options] --del=[GROUP:]EVENT [...]
یا
perf probe --list[=[GROUP:]EVENT]
یا
perf probe [options] --line=LINE
یا
perf probe [options] --vars=PROBEPOINT
یا
perf probe [options] --funcs
یا
perf probe [options] --definition=PROBE [...]

توضیحات (DESCRIPTION)

این دستور رویدادهای نقاط ردیابی پویا (dynamic tracepoint events) را بر پایه نمادها و ثبات‌ها بدون اطلاعات دیباگ، یا از طریق عبارت‌های زبان C (شماره خطوط C، نام توابع C، و متغیرهای محلی C) همراه با اطلاعات دیباگ (debuginfo) تعریف می‌کند.

گزینه‌ها (OPTIONS)

-k, --vmlinux=PATH

-m, --module=MODNAME|PATH

-s, --source=PATH

--symfs=<directory[,layout]>

-v, --verbose

-q, --quiet

-a, --add=

-d, --del=

-l, --list[=[GROUP:]EVENT]

-L, --line=

-V, --vars=

--externs

--no-inlines

-F, --funcs[=FILTER]

-D, --definition=

--filter=FILTER

-f, --force

-n, --dry-run

--cache

--max-probes=NUM

--target-ns=PID: دریافت اطلاعات فضای‌نام mount از pid هدف. این گزینه هنگام ایجاد uprobe برای فرآیندی استفاده می‌شود که در فضای‌نام mount متفاوتی نسبت به ابزار perf(1) قرار دارد.

-x, --exec=PATH

--demangle

--demangle-kernel

در صورت عدم استفاده از گزینه‌های -m/-x، دستور perf probe بررسی می‌کند که آیا اولین آرگومان پس از گزینه‌ها یک نام مسیر مطلق است یا خیر. اگر یک مسیر مطلق باشد، perf probe از آن به عنوان ماژول هدف یا باینری فضای کاربری هدف برای پروب استفاده می‌کند.

ساختار پروب (PROBE SYNTAX)

نقاط پروب بر اساس ساختار زیر تعریف می‌شوند:

1) Define event based on function name
 [[GROUP:]EVENT=]FUNC[@SRC][:RLN|+OFFS|%return|;PTN] [ARG ...]

2) Define event based on source file with line number
 [[GROUP:]EVENT=]SRC:ALN [ARG ...]

3) Define event based on source file with lazy pattern
 [[GROUP:]EVENT=]SRC;PTN [ARG ...]

4) Pre-defined SDT events or cached event with name
 %[sdt_PROVIDER:]SDTEVENT
 or,
 sdt_PROVIDER:SDTEVENT

شناسه EVENT نام رویداد جدید را مشخص می‌کند؛ در صورت حذف، نام تابع مورد پروب قرار می‌گیرد و برای پروب‌های بازگشتی (return probes)، پسوند "__return" به طور خودکار به انتهای نام تابع افزوده می‌شود. همچنین می‌توانید یک نام گروه را از طریق GROUP تعیین کنید؛ در صورت حذف، نام probe برای kprobe و probe_<bin> برای uprobe استفاده می‌شود. توجه داشته باشید که استفاده از نام گروه موجود ممکن است با رویدادهای دیگر تداخل ایجاد کند. به ویژه، استفاده از نام گروه رزروشده برای ماژول‌های هسته می‌تواند رویدادهای تعبیه‌شده در آن ماژول‌ها را پنهان سازد. شناسه FUNC نام تابع مورد پروب را مشخص می‌کند و می‌تواند یکی از گزینه‌های زیر را داشته باشد: +OFFS میزان آفست از آدرس ورودی تابع بر حسب بایت است، :RLN شماره خط نسبی از خط ورودی تابع است، و %return نشان‌دهنده پروب کردن بازگشت تابع می‌باشد. همچنین ;PTN الگوی تطبیق تنبل (lazy matching pattern) را مشخص می‌کند (به بخش تطبیق تنبل (LAZY MATCHING) مراجعه کنید). توجه داشته باشید که ;PTN باید در انتهای تعریف نقطه پروب بیاید. علاوه بر این، @SRC فایل منبع حاوی آن تابع را مشخص می‌کند. همچنین می‌توان یک نقطه پروب را بر اساس شماره خط منبع یا تطبیق تنبل با استفاده از ساختار SRC:ALN یا SRC;PTN تعیین کرد، که در آن SRC مسیر فایل منبع، :ALN شماره خط و ;PTN الگوی تطبیق تنبل است. شناسه ARG آرگومان‌های این نقطه پروب را تعیین می‌کند (به بخش آرگومان‌های پروب (PROBE ARGUMENT) مراجعه کنید). شناسه‌های SDTEVENT و PROVIDER نام رویداد از پیش تعریف‌شده هستند که توسط SDT کاربر (Statically Defined Tracing) یا پروب‌های از پیش کش‌شده با نام رویداد مشخص شده‌اند. توجه داشته باشید که پیش از استفاده از رویداد SDT، باینری هدف (که رویدادهای SDT در آن تعریف شده‌اند) باید توسط perf-buildid-cache(1) اسکن شود تا رویدادهای SDT به عنوان رویدادهای کش‌شده ثبت شوند.

برای جزئیات مربوط به SDT، نشانی زیر را ببینید: https://sourceware.org/gdb/onlinedocs/gdb/Static-Probe-Points.html

کاراکترهای گریز (ESCAPED CHARACTERS)

در ساختار پروب، کاراکترهای =، @، +، : و ; به عنوان کاراکترهای ویژه شناخته می‌شوند. می‌توانید از یک بک‌اسلش (\) برای اسکیپ کردن کاراکترهای ویژه استفاده کنید. این قابلیت زمانی مفید است که نیاز دارید روی نمادهای نسخه‌دار خاصی پروب قرار دهید (مانند پسوندهای @GLIBC_...) یا فایلی از کد منبع را مشخص کنید که نام آن حاوی کاراکترهای ویژه است. توجه داشته باشید که معمولاً بک‌اسلش منفرد توسط شل مصرف می‌شود؛ بنابراین ممکن است نیاز به ارسال بک‌اسلش دوگانه (\\) یا قرار دادن عبارت درون کوتیشن تکی ('AAA\@BBB') داشته باشید. برای نحوه استفاده، بخش مثال‌ها (EXAMPLES) را ببینید.

آرگومان‌های پروب (PROBE ARGUMENT)

هر آرگومان پروب از ساختار زیر پیروی می‌کند:

[NAME=]LOCALVAR|$retval|%REG|@SYMBOL[:TYPE][@user]

شناسه NAME نام این آرگومان را مشخص می‌کند (اختیاری). می‌توانید از نام متغیر محلی، عضو ساختار داده محلی (مانند var→field یا var.field2)، آرایه محلی با اندیس ثابت (مانند array[1]، var→array[0]، var→pointer[2]) یا قالب آرگومان kprobe-tracer (مانند $retval، %ax و غیره) استفاده کنید. توجه داشته باشید که اگر یک عضو ساختار داده محلی را مشخص کنید، نام این آرگومان برابر با نام آخرین عضو تنظیم خواهد شد (برای نمونه field2 برای var→field1.field2). آرگومان‌های ویژه $vars و $params نیز برای NAME در دسترس هستند؛ $vars به متغیرهای محلی (شامل پارامترهای تابع) که در نقطه پروب مشخص‌شده قابل دسترس هستند گسترش می‌یابد. $params فقط به پارامترهای تابع بسط داده می‌شود. شناسه TYPE نوع داده این آرگومان را تعیین می‌کند (اختیاری). در صورت حذف، perf probe نوع داده را به طور خودکار بر پایه اطلاعات دیباگ (*) تعیین می‌کند. در حال حاضر، انواع داده پایه (u8/u16/u32/u64/s8/s16/s32/s64)، اعداد صحیح در مبنای شانزده (x/x8/x16/x32/x64)، تبدیل علامت‌داری (u/s)، رشته ("string") و میدان بیتی (bitfield) پشتیبانی می‌شوند (برای جزئیات به بخش انواع داده (TYPES) مراجعه کنید). در سیستم‌های x86، شناسه %REG همیشه فرم کوتاه ثبات است: برای نمونه %AX؛ بنابراین %RAX یا %EAX مجاز نیست. ویژگی "@user" یک مشخصه ویژه است که نشان می‌دهد با LOCALVAR به عنوان حافظه فضای کاربری رفتار خواهد شد. این ویژگی تنها برای رویدادهای kprobe معتبر است.

انواع داده (TYPES)

انواع پایه (u8/u16/u32/u64/s8/s16/s32/s64) و اعداد صحیح مبنای ۱۶ (x8/x16/x32/x64) از نوع عدد صحیح هستند. پیشوندهای s و u به ترتیب نشان‌دهنده علامت‌دار (signed) و بدون علامت (unsigned) بودن این انواع هستند، و x نشان می‌دهد که مقدار در مبنای شانزده نمایش داده می‌شود. آرگومان‌های ردیابی‌شده در مبنای ۱۰ (sNN/uNN) یا مبنای ۱۶ (xNN) نمایش داده می‌شوند. همچنین می‌توانید از s یا u تنها برای تعیین علامت‌داری استفاده کنید و تشخیص اندازه آن را به عهده perf probe بگذارید. علاوه بر این، می‌توانید از x برای تعیین صریح نمایش در مبنای ۱۶ استفاده نمایید (اندازه نیز به طور خودکار تشخیص داده می‌شود). نوع داده رشته (string) نوعی ویژه است که یک رشته با پایان تهی ("null-terminated") را از فضای هسته واکشی می‌کند. این بدان معناست که اگر محفظه رشته به حافظه جانبی منتقل شده باشد (paged out)، عملیات با شکست مواجه شده و مقدار NULL ذخیره می‌گردد. نوع string را تنها می‌توانید برای متغیر محلی یا عضو ساختاری تعیین کنید که یک آرایه یا اشاره‌گری به نوع char یا unsigned char باشد. میدان بیتی (Bitfield) نوع ویژه دیگری است که ۳ پارامتر می‌گیرد: پهنای بیت (bit-width)، آفست بیت (bit-offset) و اندازه محفظه (container-size، معمولاً ۳۲). ساختار آن به شرح زیر است:

b<bit-width>@<bit-offset>/<container-size>

ساختار خط (LINE SYNTAX)

محدوده خط با ساختار زیر توصیف می‌شود:

"FUNC[@SRC][:RLN[+NUM|-RLN2]]|SRC[:ALN[+NUM|-ALN2]]"

شناسه FUNC نام تابع مربوط به خطوط نمایشی را مشخص می‌کند. RLN شماره خط شروع نسبت به خط ورودی تابع است و RLN2 شماره خط پایان است. مشابه ساختار پروب، SRC مسیر فایل منبع، ALN شماره خط شروع و ALN2 شماره خط پایان در فایل است. همچنین با استفاده از NUM می‌توان تعداد خطوطی را که باید نمایش داده شوند مشخص کرد. علاوه بر این، ترکیب FUNC@SRC برای جستجوی یک تابع خاص هنگامی که چندین تابع نام مشترکی دارند مناسب است. بنابراین، "source.c:100-120" خطوط بین شماره‌های ۱۰۰ تا ۱۲۰ را در فایل source.c نشان می‌دهد؛ و "func:10+20" تعداد ۲۰ خط را از خط دهم تابع func نمایش می‌دهد.

تطبیق تنبل (LAZY MATCHING)

تطبیق تنبل خطوط شبیه به تطبیق الگوهای glob است با این تفاوت که فاصله‌ها در هر دو بخش الگو و هدف نادیده گرفته می‌شوند. بنابراین این روش نویسه‌های عام (*، ?) و کلاس‌های کاراکتری (مانند [a-z] و [!A-Z]) را می‌پذیرد.

برای نمونه، الگوی a=* می‌تواند با a=b، a = b، a == b و مواردی از این دست تطبیق یابد.

این ویژگی نوعی انعطاف‌پذیری و پایداری را برای تعاریف نقاط پروب در برابر تغییرات جزئی کد فراهم می‌کند. برای مثال، خط دهم واقعی تابع schedule() ممکن است با ویرایش schedule() به راحتی جابه‌جا شود، اما همان خطی که با الگوی rq=cpu_rq* تطبیق دارد همچنان در تابع وجود داشته باشد.

الگوی فیلتر (FILTER PATTERN)

الگوی فیلتر، الگوی (یا الگوهای) تطبیق glob برای فیلتر کردن متغیرها است. علاوه بر این، می‌توانید از "!" برای تعیین قاعده حذف (filter-out) استفاده کنید. همچنین می‌توانید چندین قاعده را ترکیب‌شده با "&" یا "|" مشخص نمایید و با استفاده از "(" و ")" این قواعد را در یک قاعده دسته‌بندی کنید.

برای نمونه، با گزینه --filter "foo* | bar*"، دستور perf probe -V متغیرهایی را که با "foo" یا "bar" شروع می‌شوند نشان می‌دهد. با گزینه --filter "!foo* & *bar"، دستور perf probe -V متغیرهایی را که با "foo" شروع نمی‌شوند و به "bar" ختم می‌شوند (مانند "fizzbar") نمایش می‌دهد؛ اما "foobar" فیلتر و حذف می‌شود.

مثال‌ها (EXAMPLES)

نمایش خطوطی از ()schedule که می‌توان روی آن‌ها پروب قرار داد:

./perf probe --line schedule

افزودن یک پروب روی خط ۱۲ تابع ()schedule همراه با ثبت متغیر محلی cpu:

./perf probe schedule:12 cpu
یا
./perf probe --add='schedule:12 cpu'

افزودن یک یا چند پروب که نام آن‌ها با "schedule" شروع می‌شود:

./perf probe schedule*
یا
./perf probe --add='schedule*'

افزودن پروب‌ها روی خطوطی از تابع ()schedule که ()update_rq_clock را فراخوانی می‌کنند:

./perf probe 'schedule;update_rq_clock*'
یا
./perf probe --add='schedule;update_rq_clock*'

حذف تمامی پروب‌های روی ()schedule:

./perf probe --del='schedule*'

افزودن پروب در تابع ()zfree روی bin/zsh/:

./perf probe -x /bin/zsh zfree یا ./perf probe /bin/zsh zfree

افزودن پروب در تابع ()malloc روی libc:

./perf probe -x /lib/libc.so.6 malloc یا ./perf probe /lib/libc.so.6 malloc

افزودن یک uprobe به یک فرآیند هدف که در یک فضای‌نام mount متفاوت اجرا می‌شود:

./perf probe --target-ns <target pid> -x /lib64/libc.so.6 malloc

افزودن یک پروب USDT به یک فرآیند هدف که در یک فضای‌نام mount متفاوت اجرا می‌شود:

./perf probe --target-ns <target pid> -x /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.121-0.b13.el7_3.x86_64/jre/lib/amd64/server/libjvm.so %sdt_hotspot:thread__sleep__end

افزودن یک پروب روی یک نماد نسخه‌دار مشخص با استفاده از گریز بک‌اسلش:

./perf probe -x /lib64/libc-2.25.so 'malloc_get_state\@GLIBC_2.2.5'

افزودن یک پروب در یک فایل منبع حاوی کاراکترهای ویژه با استفاده از گریز بک‌اسلش:

./perf probe -x /opt/test/a.out 'foo\+bar.c:4'

مجوزها و متغیرهای هسته (PERMISSIONS AND SYSCTL)

از آنجا که perf probe به ftrace (مسیر tracefs) و kallsyms (مسیر proc/kallsyms/) وابسته است، باید به مجوزهای دسترسی و برخی متغیرهای کنترلی sysctl توجه داشته باشید.

همچنین ببینید (SEE ALSO)

perf-trace(1), perf-record(1), perf-buildid-cache(1)