JFR(1)                            دستورات JDK                           JFR(1)

نام (NAME)
       jfr - تجزیه و چاپ فایل‌های ضبط پرواز (Flight Recorder) در OpenJDK 17

خلاصه دستور (SYNOPSIS)
       برای چاپ محتویات یک ضبط پرواز در خروجی استاندارد:

       jfr print [گزینه‌ها] فایل

       برای چاپ اطلاعات متادیتا درباره رویدادهای ضبط پرواز:

       jfr metadata فایل

       برای سرهم‌بندی فایل‌های تکه (chunk) در یک فایل ضبط پرواز:

       jfr assemble مخزن فایل

       برای تجزیه یک فایل ضبط پرواز به فایل‌های تکه:

       jfr disassemble [گزینه‌ها] فایل

       برای مشاهده آمار خلاصه‌شده برای یک فایل ضبط پرواز:

       jfr summary فایل

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

       فایل   نام فایل ضبط پرواز هدف (.jfr) را مشخص می‌کند.

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

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

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

   زیردستورها (Subcommands)
       دستور jfr دارای چندین زیردستور است:

       • print

       • summary

       • assemble

       • disassemble

       • metadata

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

       jfr print [--xml|--json] [--categories <فیلترها>] [--events <فیلترها>]
       [--stack-depth <عمق>] <فایل>

       که در آن:

       --xml  چاپ ضبط در قالب XML

       --json چاپ ضبط در قالب JSON

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

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

       --stack-depth <عمق>
              تعداد فریم‌ها در ردپای پشته (stack trace)، به طور پیش‌فرض ۵

       <فایل> مکان فایل ضبط (.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 summary
       از jfr summary برای چاپ آمار مربوط به یک ضبط استفاده کنید.  برای مثال،
       یک خلاصه می‌تواند تعداد رویدادهای ضبط‌شده و میزان فضای دیسکی را که
       استفاده کرده‌اند نشان دهد.  این امر برای عیب‌یابی و درک تأثیر تنظیمات
       رویداد مفید است.

       نحو دستور عبارت است از:

       jfr summary <فایل>

       که در آن:

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

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

       jfr metadata <فایل>

       که در آن:

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

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

       نحو دستور عبارت است از:

       jfr assemble <مخزن> <فایل>

       که در آن:

       <مخزن> دایرکتوری که مخزن حاوی فایل‌های تکه در آن قرار دارد

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

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

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

       jfr disassemble [--max-chunks <تکه‌ها>] [--output <دایرکتوری>] <فایل>

       که در آن:

       --output <دایرکتوری>
              مکان نوشتن فایل‌های تجزیه‌شده، به طور پیش‌فرض دایرکتوری جاری

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

       --max-size <اندازه>
              حداکثر تعداد بایت در هر فایل.

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

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

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

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

       jfr <--help|help> [زیردستور]

       که در آن:

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

       • print

       • metadata

       • summary

       • assemble

       • disassemble

JDK 17                               2021                               JFR(1)