.\" Copyright (c) 2019, 2023, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\"
.\" This code is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License version 2 only, as
.\" published by the Free Software Foundation.
.\"
.\" This code is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" version 2 for more details (a copy is included in the LICENSE file that
.\" accompanied this code).
.\"
.\" You should have received a copy of the GNU General Public License version
.\" 2 along with this work; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
.\" or visit www.oracle.com if you need additional information or have any
.\" questions.
.\"
.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[R]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JFR" "1" "2023" "JDK 21" "دستورات JDK"
.hy
.SH "نام (NAME)"
.PP
jfr \- ابزار تجزیه، تحلیل و استخراج فایل‌های ضبط‌شده پرواز جاوا (JFR) در OpenJDK 21
.SH "خلاصه دستور (SYNOPSIS)"
.PP
برای چاپ محتویات یک ضبط پرواز در خروجی استاندارد:
.PP
\f[V]jfr\f[R] \f[V]print\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]فایل\f[R]
.PP
برای نمایش تجمیعی داده‌های رویداد در خروجی استاندارد:
.PP
\f[V]jfr\f[R] \f[V]view\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]فایل\f[R]
.PP
برای پیکربندی یک فایل تنظیمات .jfc:
.PP
\f[V]jfr\f[R] \f[V]configure\f[R] [\f[I]گزینه‌ها\f[R]]
.PP
برای چاپ اطلاعات متادیتا درباره رویدادهای ضبط پرواز:
.PP
\f[V]jfr\f[R] \f[V]metadata\f[R] [\f[I]فایل\f[R]]
.PP
برای مشاهده آمار خلاصه‌شده برای یک فایل ضبط پرواز:
.PP
\f[V]jfr\f[R] \f[V]summary\f[R] \f[I]فایل\f[R]
.PP
برای حذف رویدادها از یک فایل ضبط پرواز:
.PP
\f[V]jfr\f[R] \f[V]scrub\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]فایل\f[R]
.PP
برای سرهم‌بندی فایل‌های تکه (chunk) در یک فایل ضبط پرواز:
.PP
\f[V]jfr\f[R] \f[V]assemble\f[R] \f[I]مخزن\f[R] \f[I]فایل\f[R]
.PP
برای تجزیه یک فایل ضبط پرواز به فایل‌های تکه (chunk):
.PP
\f[V]jfr\f[R] \f[V]disassemble\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]فایل\f[R]
.TP
\f[I]گزینه‌ها\f[R]
اختیاری: گزینه‌های خط فرمان را که با فاصله از هم جدا شده‌اند مشخص می‌کند.
برای توضیحات گزینه‌های موجود، بخش‌های مربوط به زیرمؤلفه‌ها را ببینید.
.TP
\f[I]فایل\f[R]
نام فایل ضبط پرواز هدف (\f[V].jfr\f[R]) را مشخص می‌کند.
.TP
\f[I]مخزن\f[R]
مکان فایل‌های تکه‌ای را که قرار است در یک ضبط پرواز سرهم‌بندی شوند مشخص می‌کند.
.SH "توضیحات (DESCRIPTION)"
.PP
دستور \f[V]jfr\f[R] ابزاری برای تعامل با فایل‌های ضبط پرواز (\f[V].jfr\f[R]) فراهم می‌کند.
کارکرد اصلی آن فیلتر کردن، خلاصه‌سازی و خروجی دادن فایل‌های ضبط پرواز به فرمت قابل خواندن توسط انسان است.
همچنین پشتیبانی از پاک‌سازی (scrubbing)، ادغام و تقسیم فایل‌های ضبط وجود دارد.
.PP
فایل‌های ضبط پرواز به صورت فایل‌های باینری ایجاد و ذخیره می‌شوند.
داشتن ابزاری که بتواند محتویات را از ضبط پرواز استخراج کند، محتویات را دستکاری کرده و به فرمت قابل خواندن توسط انسان تبدیل نماید، به توسعه‌دهندگان در رفع اشکال مشکلات کارایی برنامه‌های جاوا کمک می‌کند.
.SS "زیردستورها"
.PP
دستور \f[V]jfr\f[R] دارای چندین زیردستور است:
.IP \[bu] 2
\f[V]print\f[R]
.IP \[bu] 2
\f[V]view\f[R]
.IP \[bu] 2
\f[V]configure\f[R]
.IP \[bu] 2
\f[V]metadata\f[R]
.IP \[bu] 2
\f[V]summary\f[R]
.IP \[bu] 2
\f[V]scrub\f[R]
.IP \[bu] 2
\f[V]assemble\f[R]
.IP \[bu] 2
\f[V]disassemble\f[R]
.SS "زیردستور \f[V]jfr print\f[R]"
.PP
از \f[V]jfr print\f[R] برای چاپ محتویات یک فایل ضبط پرواز در خروجی استاندارد استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr print\f[R] [\f[V]--xml\f[R]|\f[V]--json\f[R]]
[\f[V]--categories\f[R] <\f[I]فیلترها\f[R]>] [\f[V]--events\f[R]
<\f[I]فیلترها\f[R]>] [\f[V]--stack-depth\f[R] <\f[I]عمق\f[R]>]
<\f[I]فایل\f[R]>
.PP
که در آن:
.TP
\f[V]--xml\f[R]
ضبط را در قالب XML چاپ می‌کند.
.TP
\f[V]--json\f[R]
ضبط را در قالب JSON چاپ می‌کند.
.TP
\f[V]--categories\f[R] <\f[I]فیلترها\f[R]>
رویدادهای منطبق با یک نام دسته‌بندی را انتخاب می‌کند.
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob داخل نقل‌قول است.
.TP
\f[V]--events\f[R] <\f[I]فیلترها\f[R]>
رویدادهای منطبق با یک نام رویداد را انتخاب می‌کند.
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob داخل نقل‌قول است.
.TP
\f[V]--stack-depth\f[R] <\f[I]عمق\f[R]>
تعداد فریم‌ها در ردپای پشته (stack trace)، به طور پیش‌فرض ۵ است.
.TP
<\f[I]فایل\f[R]>
مکان فایل ضبط (\f[V].jfr\f[R])
.PP
قالب پیش‌فرض برای چاپ محتویات فایل ضبط پرواز، فرمت قابل خواندن توسط انسان است مگر اینکه \f[V]xml\f[R] یا \f[V]json\f[R] مشخص شده باشد.
این گزینه‌ها خروجی ماشین‌خوان ارائه می‌دهند که می‌تواند توسط اسکریپت‌های ایجادشده توسط کاربر تجزیه یا پردازش شود.
.PP
برای مشاهده نمونه کاربردهای فیلترها از \f[V]jfr --help print\f[R] استفاده کنید.
.PP
برای کاهش حجم داده‌های نمایش داده شده، فیلتر کردن رویدادها یا دسته‌بندی‌های رویداد امکان‌پذیر است.
فیلتر بر روی نام نمادین یک رویداد که با استفاده از حاشیه‌نویسی \f[V]\[at]Name\f[R] تنظیم شده، یا نام دسته‌بندی که با استفاده از حاشیه‌نویسی \f[V]\[at]Category\f[R] تنظیم شده، عمل می‌کند.
اگر از چندین فیلتر استفاده شود، رویدادهای هر دو فیلتر گنجانده خواهند شد.
اگر از هیچ فیلتری استفاده نشود، تمام رویدادها چاپ می‌شوند.
اگر ترکیبی از فیلتر دسته‌بندی و فیلتر رویداد استفاده شود، رویدادهای انتخابی اجتماع دو فیلتر خواهند بود.
.PP
برای مثال، جهت نمایش تمام رویدادهای GC و رویداد CPULoad، می‌توان از دستور زیر استفاده کرد:
.PP
\f[V]jfr print --categories GC --events CPULoad recording.jfr\f[R]
.PP
مقادیر رویدادها بر اساس انواع محتوایی که مورد استفاده قرار گرفته‌اند قالب‌بندی می‌شوند.
برای مثال، فیلدی با حاشیه‌نویسی \f[V]jdk.jfr.Percentage\f[R] که مقدار 0.52 دارد به صورت 52% قالب‌بندی می‌شود.
.PP
ردپای پشته به طور پیش‌فرض به ۵ فریم کوتاه می‌شود، اما این تعداد را می‌توان با استفاده از گزینه خط فرمان \f[V]--stack-depth\f[R] افزایش یا کاهش داد.
.SS "زیردستور \f[V]jfr view\f[R]"
.PP
از \f[V]jfr view\f[R] برای تجمیع و نمایش داده‌های رویداد در خروجی استاندارد استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr view\f[R] [\f[V]--verbose\f[R]] [\f[V]--width\f[R]
<\f[I]عدد\f[R]>] [\f[V]--truncate\f[R] <\f[I]حالت\f[R]>]
[\f[V]--cell-height\f[R] <\f[I]عدد\f[R]>] <\f[I]نما\f[R]>
<\f[I]فایل\f[R]>
.PP
که در آن:
.TP
\f[V]--verbose\f[R]
پرس‌وجویی (query) را که نما را می‌سازد نمایش می‌دهد.
.TP
\f[V]--width\f[R] <\f[I]عدد\f[R]>
عرض نما بر حسب تعداد کاراکترها.
مقدار پیش‌فرض به نما بستگی دارد.
.TP
\f[V]--truncate\f[R] <\f[I]حالت\f[R]>
نحوه کوتاه کردن محتوایی که از فضای یک سلول جدول فراتر می‌رود.
حالت می‌تواند \[aq]beginning\[aq] (از ابتدا) یا \[aq]end\[aq] (از انتها) باشد.
مقدار پیش‌فرض \[aq]end\[aq] است.
.TP
\f[V]--cell-height\f[R] <\f[I]عدد\f[R]>
حداکثر تعداد سطرها در یک سلول جدول.
مقدار پیش‌فرض به نما بستگی دارد.
.TP
<\f[I]نما\f[R]>
نام نما یا نوع رویداد برای نمایش.
برای مشاهده لیست نماهای موجود از \f[V]jfr --help view\f[R] استفاده کنید.
.TP
<\f[I]فایل\f[R]>
مکان فایل ضبط (.jfr)
.PP
پارامتر <\f[I]نما\f[R]> می‌تواند نام یک نوع رویداد باشد.
برای مشاهده یک لیست از \f[V]jfr view types <file>\f[R] استفاده کنید.
برای نمایش تمام نماها، از \f[V]jfr view all-views <file>\f[R] استفاده کنید.
برای نمایش تمام رویدادها، از \f[V]jfr view all-events <file>\f[R] استفاده کنید.
.SS "زیردستور \f[V]jfr configure\f[R]"
.PP
از \f[V]jfr configure\f[R] برای پیکربندی یک فایل تنظیمات .jfc استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr configure\f[R] [--interactive] [--verbose] [--input ] [--output
] [option=value]* [event-setting=value]*
.TP
\f[V]--interactive\f[R]
حالت تعاملی که در آن پیکربندی با مجموعه‌ای از پرسش‌ها تعیین می‌شود.
.TP
\f[V]--verbose\f[R]
تنظیمات تغییریافته را نمایش می‌دهد.
.TP
\f[V]--input\f[R] <\f[I]فایل‌ها\f[R]>
یک لیست جداشده با کاما از فایل‌های .jfc که پیکربندی جدید بر پایه آن‌ها است.
اگر فایلی مشخص نشود، از فایل پیش‌فرض در JDK استفاده می‌شود (default.jfc).
اگر \[aq]none\[aq] مشخص شود، پیکربندی جدید خالی شروع می‌شود.
.TP
\f[V]--output\f[R] <\f[I]فایل\f[R]>
نام فایل خروجی تولید شده.
اگر مشخص نشود، نام فایل custom.jfc استفاده خواهد شد.
.TP
\f[I]option=value\f[R]
مقدار گزینه برای تغییر.
برای مشاهده گزینه‌های موجود از \f[V]jfr help configure\f[R] استفاده کنید.
.TP
\f[I]event-setting=value\f[R]
مقدار تنظیم رویداد برای تغییر.
از این فرمت استفاده کنید:
<\f[I]نام-رویداد\f[R]>#<\f[I]نام-تنظیم\f[R]>=<\f[I]مقدار\f[R]>
برای افزودن یک تنظیم رویداد جدید، یک پیشوند \[aq]+\[aq] به نام رویداد اضافه کنید.
.PP
جداکننده فضای خالی می‌تواند برای مقادیر بازه زمانی حذف شود، مانند 20ms.
برای اطلاعات بیشتر درباره نحو تنظیمات، Javadoc بسته jdk.jfr را ببینید.
.SS "زیردستور \f[V]jfr metadata\f[R]"
.PP
از \f[V]jfr metadata\f[R] برای نمایش اطلاعات درباره رویدادها، مانند نام رویدادها، دسته‌بندی‌ها و ساختار فیلدها در یک فایل ضبط پرواز استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr metadata\f[R] [--categories ] [--events ] []
.TP
\f[V]--categories\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام دسته‌بندی را انتخاب می‌کند.
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob داخل نقل‌قول است.
.TP
\f[V]--events\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام رویداد را انتخاب می‌کند.
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob داخل نقل‌قول است.
.TP
<\f[I]فایل\f[R]>
مکان فایل ضبط (.jfr)
.PP
اگر این پارامتر حذف شود، متادیتا از همان JDK که ابزار \[aq]jfr\[aq] در آن قرار دارد استفاده خواهد شد.
.SS "زیردستور \f[V]jfr summary\f[R]"
.PP
از \f[V]jfr summary\f[R] برای چاپ آمار یک ضبط استفاده کنید.
برای مثال، یک خلاصه می‌تواند تعداد رویدادهای ضبط‌شده و میزان فضای دیسکی را که استفاده کرده‌اند نشان دهد.
این برای عیب‌یابی و درک تأثیر تنظیمات رویداد مفید است.
.PP
نحو دستور:
.PP
\f[V]jfr summary\f[R] <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
<\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[V].jfr\f[R])
.SS "زیردستور \f[V]jfr scrub\f[R]"
.PP
از \f[V]jfr scrub\f[R] برای حذف محتویات حساس از یک فایل یا کاهش حجم آن استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr scrub\f[R] [--include-events <\f[I]فیلتر\f[R]>]
[--exclude-events <\f[I]فیلتر\f[R]>] [--include-categories
<\f[I]فیلتر\f[R]>] [--exclude-categories <\f[I]فیلتر\f[R]>]
[--include-threads <\f[I]فیلتر\f[R]>] [--exclude-threads
<\f[I]فیلتر\f[R]>] <\f[I]فایل-ورودی\f[R]> [<\f[I]فایل-خروجی\f[R]>]
.TP
\f[V]--include-events\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام رویداد را انتخاب می‌کند.
.TP
\f[V]--exclude-events\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام رویداد را مستثنی می‌کند.
.TP
\f[V]--include-categories\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام دسته‌بندی را انتخاب می‌کند.
.TP
\f[V]--exclude-categories\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام دسته‌بندی را مستثنی می‌کند.
.TP
\f[V]--include-threads\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام رشته (thread) را انتخاب می‌کند.
.TP
\f[V]--exclude-threads\f[R] <\f[I]فیلتر\f[R]>
رویدادهای منطبق با یک نام رشته را مستثنی می‌کند.
.TP
<\f[I]فایل-ورودی\f[R]>
فایل ورودی برای خواندن رویدادها از آن.
.TP
<\f[I]فایل-خروجی\f[R]>
فایل خروجی برای نوشتن رویدادهای فیلترشده در آن.
اگر فایلی مشخص نشود، در همان مسیر فایل ورودی اما با پسوند \[dq]-scrubbed\[dq] اضافه شده به نام فایل ذخیره می‌شود.
.PP
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob داخل نقل‌قول است.
اگر از چندین فیلتر استفاده شود، به ترتیب مشخص‌شده اعمال می‌شوند.
.SS "زیردستور \f[V]jfr assemble\f[R]"
.PP
از \f[V]jfr assemble\f[R] برای سرهم‌بندی فایل‌های تکه (chunk) در یک فایل ضبط استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr assemble\f[R] <\f[I]مخزن\f[R]> <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
<\f[I]مخزن\f[R]>
پوشه‌ای که مخزن حاوی فایل‌های تکه در آن قرار دارد.
.TP
<\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[V].jfr\f[R]).
.PP
اطلاعات ضبط پرواز در قالب تکه‌ها (chunks) نوشته می‌شوند.
یک تکه حاوی تمام اطلاعات لازم برای تجزیه است.
یک تکه معمولاً شامل رویدادهای مفید برای عیب‌یابی است.
در صورتی که یک JVM کرش کند، این تکه‌ها قابل بازیابی هستند و می‌توان از آن‌ها برای ایجاد یک فایل ضبط پرواز با استفاده از این دستور \f[V]jfr assemble\f[R] استفاده کرد.
این فایل‌های تکه به ترتیب زمانی به هم متصل می‌شوند و فایل‌های تکه‌ای که کامل نشده‌اند (.part) نادیده گرفته می‌شوند.
.SS "زیردستور \f[V]jfr disassemble\f[R]"
.PP
از \f[V]jfr disassemble\f[R] برای تجزیه یک فایل ضبط پرواز به قطعات فایل تکه آن استفاده کنید.
.PP
نحو دستور:
.PP
\f[V]jfr disassemble\f[R] [\f[V]--max-chunks\f[R] <\f[I]تکه‌ها\f[R]>]
[\f[V]--output\f[R] <\f[I]پوشه\f[R]>] <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
\f[V]--output\f[R] <\f[I]پوشه\f[R]>
مکان نوشتن فایل‌های تجزیه‌شده، به طور پیش‌فرض پوشه فعلی.
.TP
\f[V]--max-chunks\f[R] <\f[I]تکه‌ها\f[R]>
حداکثر تعداد تکه‌ها در هر فایل، به طور پیش‌فرض ۵.
اندازه تکه متفاوت است، اما معمولاً حدود ۱۵ مگابایت است.
.TP
\f[V]--max-size\f[R] <\f[I]اندازه\f[R]>
حداکثر تعداد بایت در هر فایل.
.TP
<\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[V].jfr\f[R])
.PP
این قابلیت می‌تواند برای تعمیر یک فایل خراب با حذف تکه معیوب مفید باشد.
همچنین می‌توان از آن برای کاهش اندازه فایلی که برای انتقال بیش از حد بزرگ است استفاده کرد.
فایل‌های تکه حاصل با نام‌های \f[V]myfile_1.jfr\f[R]، \f[V]myfile_2.jfr\f[R] و غیره نام‌گذاری می‌شوند.
در صورت نیاز، نام‌های فایل‌های حاصل با صفر پر می‌شوند (padded with zeros) تا ترتیب زمانی حفظ شود.
برای مثال، اگر ضبط شامل بیش از ۱۰۰ تکه باشد، نام فایل تکه \f[V]myfile_001.jfr\f[R] خواهد بود.
.SS "زیردستورهای version و help"
.PP
از \f[V]jfr --version\f[R] یا \f[V]jfr version\f[R] برای مشاهده اطلاعات رشته نسخه برای این دستور jfr استفاده کنید.
.PP
برای دریافت راهنما در مورد هر یک از زیردستورهای jfr، استفاده کنید از:
.PP
\f[V]jfr <--help|help>\f[R] [\f[I]زیردستور\f[R]]
.PP
که در آن:
.PP
[\f[I]زیردستور\f[R]] یکی از موارد زیر است:
.IP \[bu] 2
\f[V]print\f[R]
.IP \[bu] 2
\f[V]view\f[R]
.IP \[bu] 2
\f[V]configure\f[R]
.IP \[bu] 2
\f[V]metadata\f[R]
.IP \[bu] 2
\f[V]summary\f[R]
.IP \[bu] 2
\f[V]scrub\f[R]
.IP \[bu] 2
\f[V]assemble\f[R]
.IP \[bu] 2
\f[V]disassemble\f[R]