زیرفرمان‌ها (Subcommands)

دستور jfr دارای چندین زیرفرمان است:

• print
• view
• configure
• metadata
• summary
• scrub
• assemble
• disassemble

زیرفرمان jfr print

از زیرفرمان jfr print برای چاپ محتویات یک فایل ضبط وقایع پرواز در خروجی استاندارد استفاده کنید.

نحو دستور:

jfr print [--xml|--json|--exact] [--categories <filters>] [--events <filters>] [--stack-depth <depth>] <file>

که در آن:

--xml

فایل ضبط را با قالب XML چاپ می‌کند.

--json

فایل ضبط را با قالب JSON چاپ می‌کند.

--exact

اعداد و برچسب‌های زمانی را با دقت کامل و خوانایی مناسب چاپ می‌کند.

--categories <filters>

رویدادهای منطبق با یک نام دسته‌بندی را انتخاب می‌کند. فیلتر یک فهرست جداشده با کاما از نام‌های ساده و/یا واجد شرایط (qualified) و/یا الگوهای glob نقل‌قول‌شده است.

--events <filters>

رویدادهای منطبق با یک نام رویداد را انتخاب می‌کند. فیلتر یک فهرست جداشده با کاما از نام‌های ساده و/یا واجد شرایط و/یا الگوهای glob نقل‌قول‌شده است.

--stack-depth <depth>

تعداد فریم‌ها در ردگیری پشته (stack traces) که مقدار پیش‌فرض آن ۵ است.

<file>

مکان فایل ضبط (.jfr).

قالب پیش‌فرض برای چاپ محتویات فایل ضبط وقایع پرواز به صورت متنی و خوانا برای انسان است، مگر اینکه xml یا json مشخص شده باشد. این گزینه‌ها خروجی ماشین‌خوان فراهم می‌کنند که می‌تواند توسط اسکریپت‌های نوشته‌شده توسط کاربر پردازش و تحلیل شود.

برای مشاهده مثال‌های استفاده از فیلترها از دستور jfr --help print استفاده کنید.

برای کاهش حجم داده‌های نمایش‌داده‌شده، امکان فیلتر کردن رویدادها یا دسته‌بندی‌های رویداد وجود دارد. فیلتر روی نام نمادین یک رویداد (تنظیم‌شده با استفاده از انوتیشن @Name) یا نام دسته‌بندی (تنظیم‌شده با استفاده از انوتیشن @Category) اعمال می‌شود. اگر از چندین فیلتر استفاده شود، رویدادهای هر دو فیلتر گنجانده خواهند شد. اگر هیچ فیلتری استفاده نشود، تمام رویدادها چاپ می‌شوند. اگر ترکیبی از فیلتر دسته‌بندی و فیلتر رویداد استفاده شود، رویدادهای انتخاب‌شده اجتماع دو فیلتر خواهند بود.

برای مثال، برای نمایش تمام رویدادهای GC و رویداد CPULoad، می‌توان از دستور زیر استفاده کرد:

jfr print --categories GC --events CPULoad recording.jfr

مقادیر رویداد بر اساس انواع محتوایی که استفاده می‌شوند قالب‌بندی می‌گردند. به عنوان مثال، فیلدی با انوتیشن jdk.jfr.Percentage که مقدار 0.52 دارد، به صورت %52 قالب‌بندی می‌شود.

ردگیری‌های پشته به طور پیش‌فرض به ۵ فریم کوتاه می‌شوند، اما می‌توان این تعداد را با استفاده از گزینه خط فرمان --stack-depth افزایش یا کاهش داد.

زیرفرمان jfr view

از زیرفرمان jfr view برای تجمیع و نمایش داده‌های رویداد در خروجی استاندارد استفاده کنید.

نحو دستور:

jfr view [--verbose] [--width <integer>] [--truncate <mode>] [--cell-height <integer>] <view> <file>

که در آن:

--verbose

پرس‌وجویی (query) که نما را می‌سازد نمایش می‌دهد.

--width <integer>

عرض نما بر حسب تعداد کاراکتر. مقدار پیش‌فرض به نما بستگی دارد.

--truncate <mode>

نحوه کوتاه کردن محتوایی که از فضای یک سلول جدول فراتر می‌رود. حالت می‌تواند 'beginning' (ابتدا) یا 'end' (انتها) باشد. مقدار پیش‌فرض 'end' است.

--cell-height <integer>

حداکثر تعداد سطرها در یک سلول جدول. مقدار پیش‌فرض به نما بستگی دارد.

<view>

نام نما یا نوع رویداد برای نمایش. برای مشاهده فهرستی از نماهای موجود از jfr --help view استفاده کنید.

<file>

مکان فایل ضبط (.jfr).

پارامتر <view> می‌تواند نام یک نوع رویداد باشد. از دستور jfr view types <file> برای مشاهده فهرست استفاده کنید. برای نمایش تمام نماها، از jfr view all-views <file> استفاده کنید. برای نمایش تمام رویدادها، از jfr view all-events <file> استفاده کنید.

زیرفرمان jfr configure

از زیرفرمان jfr configure برای پیکربندی یک فایل تنظیمات .jfc استفاده کنید.

نحو دستور:

jfr configure [--interactive] [--verbose] [--input <files>] [--output <file>] [option=value]* [event-setting=value]*

--interactive

حالت تعاملی که در آن پیکربندی با مجموعه‌ای از پرسش‌ها تعیین می‌شود.

--verbose

تنظیمات تغییریافته را نمایش می‌دهد.

--input <files>

فهرستی جداشده با کاما از فایل‌های .jfc که پیکربندی جدید بر پایه آن‌ها است. اگر هیچ فایلی مشخص نشود، فایل پیش‌فرض در JDK استفاده می‌شود (default.jfc). اگر 'none' مشخص شود، پیکربندی جدید به صورت خالی آغاز می‌گردد.

--output <file>

نام فایل خروجی تولیدشده. اگر مشخص نشود، نام فایل custom.jfc استفاده خواهد شد.

option=value

مقدار گزینه برای تغییر. برای مشاهده گزینه‌های موجود، از jfr help configure استفاده کنید.

event-setting=value

مقدار تنظیم رویداد برای تغییر. از فرم زیر استفاده کنید:
<event-name>#<setting-name>=<value>
برای افزودن یک تنظیم رویداد جدید، نام رویداد را با پیشوند '+' بیاورید.

جداکننده فاصله خالی می‌تواند برای مقادیر بازه زمانی حذف شود، مانند 20ms. برای اطلاعات بیشتر درباره نحو تنظیمات، به Javadoc بسته jdk.jfr مراجعه کنید.

زیرفرمان jfr metadata

از زیرفرمان jfr metadata برای نمایش اطلاعات مربوط به رویدادها مانند نام رویدادها، دسته‌بندی‌ها و چیدمان فیلدها در یک فایل ضبط وقایع پرواز استفاده کنید.

نحو دستور:

jfr metadata [--categories <filter>] [--events <filter>] [<file>]

--categories <filter>

رویدادهای منطبق با یک نام دسته‌بندی را انتخاب می‌کند. فیلتر یک فهرست جداشده با کاما از نام‌های ساده و/یا واجد شرایط و/یا الگوهای glob نقل‌قول‌شده است.

--events <filter>

رویدادهای منطبق با یک نام رویداد را انتخاب می‌کند. فیلتر یک فهرست جداشده با کاما از نام‌های ساده و/یا واجد شرایط و/یا الگوهای glob نقل‌قول‌شده است.

<file>

مکان فایل ضبط (.jfr).

اگر پارامتر <file> حذف شود، متاداده از JDK که ابزار 'jfr' در آن قرار دارد استفاده خواهد شد.

زیرفرمان jfr summary

از زیرفرمان jfr summary برای چاپ آمار یک فایل ضبط استفاده کنید. به عنوان مثال، خلاصه می‌تواند تعداد رویدادهای ضبط‌شده و میزان فضای دیسک مصرفی آن‌ها را نشان دهد. این امر برای عیب‌یابی و درک تأثیر تنظیمات رویداد مفید است.

نحو دستور:

jfr summary <file>

که در آن:

<file>

مکان فایل ضبط وقایع پرواز (.jfr).

زیرفرمان jfr scrub

از زیرفرمان jfr scrub برای حذف محتویات حساس از یک فایل یا کاهش اندازه آن استفاده کنید.

نحو دستور:

jfr scrub [--include-events <filter>] [--exclude-events <filter>] [--include-categories <filter>] [--exclude-categories <filter>] [--include-threads <filter>] [--exclude-threads <filter>] <input-file> [<output-file>]

--include-events <filter>

رویدادهای منطبق با یک نام رویداد را انتخاب می‌کند.

--exclude-events <filter>

رویدادهای منطبق با یک نام رویداد را مستثنی می‌کند.

--include-categories <filter>

رویدادهای منطبق با یک نام دسته‌بندی را انتخاب می‌کند.

--exclude-categories <filter>

رویدادهای منطبق با یک نام دسته‌بندی را مستثنی می‌کند.

--include-threads <filter>

رویدادهای منطبق با یک نام رشته (thread) را انتخاب می‌کند.

--exclude-threads <filter>

رویدادهای منطبق با یک نام رشته را مستثنی می‌کند.

<input-file>

فایل ورودی برای خواندن رویدادها از آن.

<output-file>

فایل خروجی برای نوشتن رویدادهای فیلترشده در آن. اگر فایلی مشخص نشود، در همان مسیر فایل ورودی نوشته خواهد شد، اما عبارت "-scrubbed" به انتهای نام فایل اضافه می‌شود.

فیلتر یک فهرست جداشده با کاما از نام‌های ساده و/یا واجد شرایط و/یا الگوهای glob نقل‌قول‌شده است. اگر چندین فیلتر استفاده شود، به ترتیب مشخص‌شده اعمال می‌شوند.

زیرفرمان jfr assemble

از زیرفرمان jfr assemble برای سرهم‌بندی فایل‌های تکه‌ای (چانک) در یک فایل ضبط استفاده کنید.

نحو دستور:

jfr assemble <repository> <file>

که در آن:

<repository>

پوشه‌ای که مخزن حاوی فایل‌های تکه‌ای در آن قرار دارد.

<file>

مکان فایل ضبط وقایع پرواز (.jfr).

اطلاعات ضبط وقایع پرواز در قالب تکه‌ها (chunks) نوشته می‌شود. یک تکه شامل تمام اطلاعات لازم برای تجزیه و تحلیل است. یک تکه معمولاً شامل رویدادهای مفید برای عیب‌یابی است. در صورت خرابی یا کرش JVM، این تکه‌ها می‌توانند بازیابی شده و با استفاده از دستور jfr assemble برای ایجاد یک فایل ضبط وقایع پرواز استفاده شوند. این فایل‌های تکه‌ای به ترتیب زمانی به هم متصل می‌شوند و فایل‌های تکه‌ای که کامل نشده‌اند (.part) نادیده گرفته می‌شوند.

زیرفرمان jfr disassemble

از زیرفرمان jfr disassemble برای تجزیه یک فایل ضبط وقایع پرواز به تکه‌های سازنده آن استفاده کنید.

نحو دستور:

jfr disassemble [--max-chunks <chunks>] [--output <directory>] <file>

که در آن:

--output <directory>

مکان نوشتن فایل‌های تجزیه‌شده؛ به طور پیش‌فرض دایرکتوری جاری است.

--max-chunks <chunks>

حداکثر تعداد تکه‌ها در هر فایل، به طور پیش‌فرض ۵. اندازه تکه‌ها متغیر است، اما معمولاً حدود ۱۵ مگابایت است.

--max-size <size>

حداکثر تعداد بایت‌ها در هر فایل.

<file>

مکان فایل ضبط وقایع پرواز (.jfr).

این قابلیت می‌تواند برای تعمیر یک فایل خراب با حذف تکه معیوب مفید باشد. همچنین می‌تواند برای کاهش حجم فایلی که برای انتقال بیش از حد بزرگ است استفاده شود. فایل‌های تکه‌ای حاصل با نام‌های myfile_1.jfr، myfile_2.jfr و غیره نام‌گذاری می‌شوند. در صورت نیاز، نام فایل‌های حاصل با صفر پر می‌شوند تا ترتیب زمانی حفظ شود. به عنوان مثال، اگر ضبط شامل بیش از ۱۰۰ تکه باشد، نام فایل تکه myfile_001.jfr خواهد بود.

زیرفرمان‌های version و help در jfr

از jfr --version یا jfr version برای مشاهده رشته اطلاعات نسخه این دستور jfr استفاده کنید.

برای دریافت راهنما در مورد هر یک از زیرفرمان‌های jfr، از دستور زیر استفاده کنید:

jfr <--help|help> [subcommand]

که در آن:

[subcommand] یکی از موارد زیر است:

• print
• view
• configure
• metadata
• summary
• scrub
• assemble
• disassemble