نام (NAME)

perf-script-perl - پردازش داده‌های ردگیری با استفاده از اسکریپت Perl

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

perf script [-s [Perl]:script[.pl] ]

توضیحات (DESCRIPTION)

این گزینه از perf script برای پردازش داده‌های perf script با استفاده از مفسر درون‌ساخت Perl در perf استفاده می‌شود. این ابزار فایل ورودی را خوانده و پردازش می‌کند و در صورت وجود، نتایج تحلیل ردگیری پیاده‌سازی‌شده در اسکریپت Perl مشخص‌شده را نمایش می‌دهد.

اسکریپت‌های آغازین (STARTER SCRIPTS)

می‌توانید با اجرای دستور perf script -g perl در همان دایرکتوری که فایل ردگیری perf.data موجود است، از خواندن ادامه این سند صرف‌نظر کنید. این دستور یک اسکریپت آغازین حاوی یک گرداننده برای هر یک از انواع رویدادهای موجود در فایل ردگیری تولید می‌کند؛ این اسکریپت صرفاً تمام فیلدهای موجود را برای هر رویداد در فایل ردگیری چاپ می‌کند.

همچنین می‌توانید برای مشاهده مثال‌های معمول از نحوه انجام کارهای پایه مانند تجمیع داده‌های رویداد، چاپ نتایج و غیره، به اسکریپت‌های موجود در مسیر ~/libexec/perf-core/scripts/perl نگاهی بیندازید. علاوه بر این، اسکریپت check-perf-script.pl هرچند از نظر نتایج جالب توجه نیست، اما تلاش می‌کند تمام قابلیت‌های اصلی اسکریپت‌نویسی را به کار گیرد.

گرداننده‌های رویداد (EVENT HANDLERS)

هنگامی که perf script با استفاده از یک اسکریپت ردگیری فراخوانی می‌شود، یک تابع گرداننده تعریف‌شده توسط کاربر برای هر رویداد در ردگیری فراخوانی می‌گردد. اگر هیچ تابع گرداننده‌ای برای یک نوع رویداد مشخص تعریف نشده باشد، آن رویداد نادیده گرفته می‌شود (یا به تابع trace_unhandled ارسال می‌شود، به پایین مراجعه کنید) و رویداد بعدی پردازش می‌گردد.

بیشتر مقادیر فیلدهای رویداد به عنوان آرگومان به تابع گرداننده ارسال می‌شوند؛ برخی از فیلدهای کم‌کاربردتر ارسال نمی‌شوند - این موارد به عنوان فراخوانی‌های بازگشتی به فایل اجرایی perf در دسترس هستند (به پایین مراجعه کنید).

به عنوان مثال، دستور perf record زیر می‌تواند برای ضبط تمام رویدادهای sched_wakeup در سیستم استفاده شود:

# perf record -a -e sched:sched_wakeup

ردگیری‌هایی که قرار است با استفاده از یک اسکریپت پردازش شوند، باید با گزینه بالا ضبط شوند: -a برای فعال‌سازی جمع‌آوری داده در سطح کل سیستم.

فایل قالب برای رویداد sched_wakeup فیلدهای زیر را تعریف می‌کند (مسیر /sys/kernel/tracing/events/sched/sched_wakeup/format را ببینید):

.ft C
 format:
        field:unsigned short common_type;
        field:unsigned char common_flags;
        field:unsigned char common_preempt_count;
        field:int common_pid;
        field:char comm[TASK_COMM_LEN];
        field:pid_t pid;
        field:int prio;
        field:int success;
        field:int target_cpu;
.ft

تابع گرداننده برای این رویداد به این صورت تعریف می‌شود:

.ft C
sub sched::sched_wakeup
{
   my ($event_name, $context, $common_cpu, $common_secs,
       $common_nsecs, $common_pid, $common_comm,
       $comm, $pid, $prio, $success, $target_cpu) = @_;
}
.ft

تابع گرداننده قالب subsystem::event_name را به خود می‌گیرد.

آرگومان‌های $common_* در فهرست آرگومان‌های گرداننده، مجموعه‌ای از آرگومان‌ها هستند که به تمام گرداننده‌های رویداد ارسال می‌شوند؛ برخی از فیلدها با فیلدهای common_* در فایل قالب مطابقت دارند، اما برخی دیگر به صورت ساختگی تولید می‌شوند، و برخی از فیلدهای common_* نیز آن‌قدر عمومی نیستند که به عنوان آرگومان به هر رویدادی ارسال شوند اما به عنوان توابع کتابخانه‌ای در دسترس هستند.

در اینجا شرح مختصری از هر یک از آرگومان‌های نامتغیر رویداد آمده است:

$event_name                نام رویداد به صورت متن
$context                   یک کوکی مات ('cookie') مورد استفاده در فراخوانی‌های بازگشتی به perf
$common_cpu                پردازنده‌ای که رویداد روی آن رخ داده است
$common_secs               بخش ثانیه برچسب زمانی رویداد
$common_nsecs              بخش نانوثانیه برچسب زمانی رویداد
$common_pid                شناسه پردازه (PID) وظیفه جاری
$common_comm               نام پردازش جاری

تمام فیلدهای باقی‌مانده در فایل قالب رویداد، همتایانی با همان نام به عنوان آرگومان‌های تابع گرداننده دارند، همان‌طور که در مثال بالا مشاهده می‌شود.

موارد فوق اصول اولیه مورد نیاز برای دسترسی مستقیم به تک‌تک فیلدهای هر رویداد در یک ردگیری را فراهم می‌کند، که ۹۰٪ آنچه را که برای نوشتن یک اسکریپت ردگیری کاربردی نیاز دارید پوشش می‌دهد. بخش‌های زیر بقیه موارد را پوشش می‌دهند.

ساختار اسکریپت (SCRIPT LAYOUT)

هر اسکریپت Perl برای perf script باید با تنظیم مسیر جستجوی ماژول‌های Perl و بارگذاری ('use' کردن) چند ماژول پشتیبانی آغاز شود (توضیحات ماژول‌ها را در زیر ببینید):

.ft C
 use lib "$ENV{'PERF_EXEC_PATH'}/scripts/perl/Perf-Trace-Util/lib";
 use lib "./Perf-Trace-Util/lib";
 use Perf::Trace::Core;
 use Perf::Trace::Context;
 use Perf::Trace::Util;
.ft

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

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

تابع trace_begin، در صورت تعریف، قبل از پردازش هر رویدادی فراخوانی می‌شود و به اسکریپت‌ها این فرصت را می‌دهد که وظایف راه‌اندازی اولیه را انجام دهند:

.ft C
 sub trace_begin
 {
 }
.ft

تابع trace_end، در صورت تعریف، پس از پردازش تمام رویدادها فراخوانی می‌شود و به اسکریپت‌ها امکان می‌دهد کارهای پایانی اسکریپت، مانند نمایش نتایج را انجام دهند:

.ft C
sub trace_end
{
}
.ft

تابع trace_unhandled، در صورت تعریف، برای هر رویدادی که گرداننده‌ای به طور صریح برای آن تعریف نشده باشد فراخوانی می‌شود. مجموعه استاندارد آرگومان‌های مشترک به آن ارسال می‌شود:

.ft C
sub trace_unhandled
{
    my ($event_name, $context, $common_cpu, $common_secs,
        $common_nsecs, $common_pid, $common_comm) = @_;
}
.ft

بخش‌های باقی‌مانده توضیحاتی درباره هر یک از ماژول‌های درون‌ساخت Perl در perf script و توابع مرتبط با آن‌ها ارائه می‌دهند.

ماژول‌ها و توابع موجود (AVAILABLE MODULES AND FUNCTIONS)

بخش‌های زیر توابع و متغیرهای موجود از طریق ماژول‌های مختلف Perl یعنی Perf::Trace::* را شرح می‌دهند. برای استفاده از توابع و متغیرهای یک ماژول داده‌شده، خط متناظر use Perf::Trace::XXX را به اسکریپت perf script خود اضافه کنید.

flag_str($event_name, $field_name, $field_value) - مقدار رشته‌ای متناظر با $field_value را برای فیلد پرچم $field_name از رویداد $event_name برمی‌گرداند
symbol_str($event_name, $field_name, $field_value) - مقدار رشته‌ای متناظر با $field_value را برای فیلد نمادین $field_name از رویداد $event_name برمی‌گرداند

common_pc($context) - مقدار common_preempt count را برای رویداد جاری برمی‌گرداند
common_flags($context) - مقدار common_flags را برای رویداد جاری برمی‌گرداند
common_lock_depth($context) - مقدار common_lock_depth را برای رویداد جاری برمی‌گرداند

nsecs($secs, $nsecs) - مجموع کل nsecs را بر اساس جفت secs/nsecs برمی‌گرداند
nsecs_secs($nsecs) - بخش ثانیه کامل را با دریافت nsecs برمی‌گرداند
nsecs_nsecs($nsecs) - باقیمانده nsecs را با دریافت nsecs برمی‌گرداند
nsecs_str($nsecs) - رشته قابل چاپ در قالب secs.nsecs را برمی‌گرداند
avg($total, $n) - میانگین را بر اساس یک مجموع و تعداد کل مقادیر برمی‌گرداند

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

perf-script(1)