نام (NAME)

gprofng-collect-app - جمع‌آوری داده‌های کارایی برای برنامه کاربردی هدف

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

gprofng collect app [option(s)] target [target-option(s)]

توضیحات (DESCRIPTION)

داده‌های کارایی (Performance) را در برنامه هدف جمع‌آوری می‌کند. علاوه بر نمونه‌برداری از شمارنده برنامه (PC یا Program Counter)، شمارنده‌های رویدادهای سخت‌افزاری و گزینه‌های گوناگون ردگیری (Tracing) نیز پشتیبانی می‌شوند.

برای نمونه، دستور زیر داده‌های کارایی را برای یک فایل اجرایی به نام a.out جمع‌آوری کرده و داده‌های ثبت‌شده را در یک پوشه آزمایش با نام example.er ذخیره می‌کند.

$ gprofng collect app -o example.er ./a.out

گزینه‌ها (OPTIONS)

--version

چاپ شماره نسخه و خروج.

--help

چاپ اطلاعات نحوه استفاده و خروج.

-v, --verbose

به‌طور پیش‌فرض، حالت پرگویی (Verbose) غیرفعال است. این گزینه آن را فعال می‌کند.

-p {off | on | lo[w] | hi[gh] | <value>}

غیرفعال‌سازی (off) یا فعال‌سازی (on) پروفایل‌بندی ساعت (Clock profiling) با استفاده از دانه‌بندی پیش‌فرض نمونه‌برداری، یا فعال‌سازی ضمنی پروفایل‌بندی ساعت از طریق تعیین دانه‌بندی نمونه‌برداری (lo[w]، hi[gh] یا مقداری مشخص به میلی‌ثانیه). به‌طور پیش‌فرض، پروفایل‌بندی ساعت فعال است (-p on).

-h <ctr_def>[,<ctr_def>]

فعال‌سازی پروفایل‌بندی شمارنده‌های رویداد سخت‌افزاری و انتخاب یک یا چند شمارنده. برای مشاهده شمارنده‌های پشتیبانی‌شده در این سیستم، گزینه -h را بدون آرگومان‌های دیگر به کار ببرید.

-o <exp_name>

تعیین نام برای پوشه آزمایش. نام باید با .er خاتمه یابد و می‌تواند شامل یک مسیر مطلق باشد (مانند /tmp/experiment.er). اگر آزمایشی از قبل با همین نام وجود داشته باشد، بازنویسی نخواهد شد.

-O <exp_name>

مشابه گزینه -o است، اما بر خلاف آن، در صورت وجود پوشه آزمایشی با همین نام، آن را بدون اخطار بازنویسی می‌کند.

-C <comment_string>

افزودن حداکثر ۱۰ رشته یادداشت (کامنت) به آزمایش. این یادداشت‌ها در بخش نکات هدر ظاهر می‌شوند و با دستور gprofng display text با استفاده از گزینه -header قابل بازیابی هستند.

-j {on | off | <path>}

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

-J <jvm-option(s)>

مشخص‌کردن یک یا چند گزینه اضافی برای ارسال به JVM مورد استفاده. اگر فهرست jvm-option(s) شامل بیش از یک گزینه باشد، باید درون علامت نقل‌قول (کوتیشن) قرار گیرد. موارد موجود در فهرست باید با فاصله یا تب از یکدیگر جدا شوند. هر مورد به عنوان یک گزینه جداگانه به JVM ارسال می‌شود. توجه داشته باشید که این گزینه به طور ضمنی -j on را فعال می‌کند.

-t <duration>[m|s]

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

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

-n

برای اجرای آزمایشی (Dry run) به کار می‌رود. چندین تنظیم زمان اجرا نمایش داده می‌شوند، اما برنامه هدف اجرا نمی‌شود و هیچ داده کارایی جمع‌آوری نخواهد شد.

-F {off|on|=regex}

کنترل اینکه آیا داده‌های فرآیندهای فرزند (نواده) ثبت شوند یا خیر. برای غیرفعال/فعال‌سازی این ویژگی از off/on استفاده کنید. از =regex برای ثبت داده‌های فرآیندهایی استفاده کنید که نام فایل اجرایی آن‌ها با عبارت باقاعده مطابقت دارد. تنها نام پایه (Basename) فایل اجرایی بررسی می‌شود، نه مسیر کامل آن. اگر از فاصله‌ها یا نویسه‌هایی استفاده می‌شود که توسط پوسته (Shell) تفسیر می‌شوند، عبارت regex را داخل علامت نقل‌قول تکی (Single quotes) قرار دهید. حالت پیش‌فرض -F on است.

-a {off|on|ldobjects|src|usedldobjects|usedsrc}

تعیین نحوه بایگانی فایل‌های باینری و سایر فایل‌ها. علاوه بر غیرفعال‌سازی این ویژگی (off) یا فعال‌سازی بایگانی همه اشیاء بارگذاری و سورس‌ها (on)، سایر گزینه‌ها امکان انتخاب دقیق‌تری را فراهم می‌کنند.

تمامی این گزینه‌ها بایگانی را فعال می‌کنند، اما کلیدواژه مشخص می‌کند که دقیقاً چه مواردی انتخاب شوند: تمام اشیاء بارگذاری (ldobjects)، تمام فایل‌های منبع (src)، اشیاء بارگذاری مرتبط با شمارنده برنامه (usedldobjects)، یا فایل‌های منبع مرتبط با شمارنده برنامه (usedsrc). حالت پیش‌فرض -a ldobjects است.

-S {off|on|<seconds>}

غیرفعال‌سازی (off) یا فعال‌سازی (on) نمونه‌برداری دوره‌ای از مصرف منابع در سطح کل فرآیند. به‌طور پیش‌فرض، نمونه‌برداری در هر ثانیه رخ می‌دهد. برای تغییر این بازه از شناسه <seconds> استفاده کنید. حالت پیش‌فرض -S on است.

-y <signal>[,r]

کنترل ثبت داده‌ها با سیگنالی با نام <signal> که با عنوان سیگنال توقف-ازسرگیری (Pause-resume signal) شناخته می‌شود. هر زمان که سیگنال داده‌شده به فرآیند تحویل داده شود، وضعیت میان متوقف (هیچ داده‌ای ثبت نمی‌شود) و ازسرگرفته‌شده (داده‌ها ثبت می‌شوند) جابه‌جا می‌شود.

به‌طور پیش‌فرض، جمع‌آوری داده‌ها در وضعیت متوقف آغاز می‌شود. اگر شناسه اختیاری r مشخص شود، جمع‌آوری داده‌ها در وضعیت ازسرگرفته‌شده آغاز شده و بلافاصله فرآیند گردآوری شروع می‌شود.

سیگنال‌های SIGUSR1 یا SIGUSR2 برای این منظور توصیه می‌شوند، اما هر سیگنالی که توسط برنامه هدف استفاده نشده باشد می‌تواند به کار رود.

-l <signal>

تعیین سیگنالی که ثبت یک نمونه از مصرف منابع در سطح کل فرآیند را آغاز می‌کند. هنگامی که سیگنال <signal> به فرآیند تحویل داده شود، یک نمونه ثبت می‌گردد.

سیگنال را می‌توان با نام کامل، بدون حروف ابتدایی "SIG" یا با شماره سیگنال مشخص کرد. توجه داشته باشید که برای ارسال سیگنال می‌توان از دستور kill استفاده کرد.

اگر از هر دو گزینه -l و -y استفاده شود، سیگنال‌ها باید متفاوت باشند.

-s <option>[,<API>]

فعال‌سازی ردگیری انتظار همگام‌سازی (Synchronization wait tracing)، که در آن <option> برای تعریف جزئیات ردگیری به کار می‌رود (on، off، <threshold> یا all). رابط برنامه‌نویسی (API) از طریق تنظیم <API> انتخاب می‌شود: n برای انتخاب بومی/Pthreads، j برای جاوا، و nj برای هر دو. حالت پیش‌فرض -s off است.

-H {off|on}

غیرفعال‌سازی (off) یا فعال‌سازی (on) ردگیری هیپ (Heap tracing). حالت پیش‌فرض -H off است.

-i {off|on}

غیرفعال‌سازی (off) یا فعال‌سازی (on) ردگیری ورودی/خروجی (I/O tracing). حالت پیش‌فرض -i off است.

نکات (NOTES)

هر فایل اجرایی در قالب شیء ELF (کوتاه‌نوشت Executable and Linkable Format) را می‌توان برای پروفایل‌بندی با gprofng به کار برد. اگر اطلاعات اشکال‌زدایی (Debug information) در دسترس باشد، gprofng می‌تواند جزئیات بیشتری را ارائه دهد، اما این یک الزام نیست.

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

gprofng(1), gprofng-archive(1), gprofng-display-html(1), gprofng-display-src(1), gprofng-display-text(1)

راهنمای کاربری gprofng به عنوان کتابچه راهنمای Texinfo نگهداری می‌شود. اگر برنامه‌های info و gprofng به‌درستی نصب شده باشند، دستور info gprofng باید دسترسی به این سند را فراهم کند.

کپی‌رایت (COPYRIGHT)

کپی‌رایت © 2022-2026 بنیاد نرم‌افزار آزاد (Free Software Foundation, Inc.)

اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه بعدی منتشرشده توسط بنیاد نرم‌افزار آزاد اعطا می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد، و بدون متون پشت جلد. یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.