.\" Copyright (c) 2019, 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.3.1
.\"
.TH "JFR" "1" "2021" "JDK 17" "دستورات JDK"
.hy
.SH "نام (NAME)"
.PP
jfr \- تجزیه و چاپ فایل‌های ضبط پرواز (Flight Recorder) در OpenJDK 17
.SH "خلاصه دستور (SYNOPSIS)"
.PP
برای چاپ محتویات یک ضبط پرواز در خروجی استاندارد:
.PP
\f[CB]jfr\f[R] \f[CB]print\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]فایل\f[R]
.PP
برای چاپ اطلاعات متادیتا درباره رویدادهای ضبط پرواز:
.PP
\f[CB]jfr\f[R] \f[CB]metadata\f[R] \f[I]فایل\f[R]
.PP
برای سرهم‌بندی فایل‌های تکه (chunk) در یک فایل ضبط پرواز:
.PP
\f[CB]jfr\f[R] \f[CB]assemble\f[R] \f[I]مخزن\f[R] \f[I]فایل\f[R]
.PP
برای تجزیه یک فایل ضبط پرواز به فایل‌های تکه:
.PP
\f[CB]jfr\f[R] \f[CB]disassemble\f[R] [\f[I]گزینه‌ها\f[R]] \f[I]فایل\f[R]
.PP
برای مشاهده آمار خلاصه‌شده برای یک فایل ضبط پرواز:
.PP
\f[CB]jfr\f[R] \f[CB]summary\f[R] \f[I]فایل\f[R]
.TP
.B \f[I]گزینه‌ها\f[R]
اختیاری: گزینه‌های خط فرمان را که با فاصله از هم جدا شده‌اند مشخص می‌کند.
برای شرح گزینه‌های موجود، بخش‌های مربوط به زیرمؤلفه‌ها را ببینید.
.RS
.RE
.TP
.B \f[I]فایل\f[R]
نام فایل ضبط پرواز هدف (\f[CB]\&.jfr\f[R]) را مشخص می‌کند.
.RS
.RE
.TP
.B \f[I]مخزن\f[R]
مکان فایل‌های تکه‌ای را که قرار است در یک ضبط پرواز سرهم‌بندی شوند مشخص می‌کند.
.RS
.RE
.SH "توضیحات (DESCRIPTION)"
.PP
دستور \f[CB]jfr\f[R] ابزاری برای تعامل با فایل‌های ضبط پرواز (\f[CB]\&.jfr\f[R]) فراهم می‌کند.
کارکرد اصلی آن فیلتر کردن، خلاصه‌سازی و خروجی دادن فایل‌های ضبط پرواز در قالبی قابل خواندن توسط انسان است.
همچنین پشتیبانی برای ادغام و تقسیم فایل‌های ضبط وجود دارد.
.PP
فایل‌های ضبط پرواز به صورت فایل‌های باینری ایجاد و ذخیره می‌شوند.
داشتن ابزاری که بتواند محتویات را از ضبط پرواز استخراج کند، محتویات را دستکاری کرده و به فرمت قابل خواندن توسط انسان ترجمه نماید، به توسعه‌دهندگان در عیب‌یابی مشکلات کارایی برنامه‌های جاوا کمک می‌کند.
.SS زیردستورها (Subcommands)
.PP
دستور \f[CB]jfr\f[R] دارای چندین زیردستور است:
.IP \[bu] 2
\f[CB]print\f[R]
.IP \[bu] 2
\f[CB]summary\f[R]
.IP \[bu] 2
\f[CB]assemble\f[R]
.IP \[bu] 2
\f[CB]disassemble\f[R]
.IP \[bu] 2
\f[CB]metadata\f[R]
.SS زیردستور \f[CB]jfr\ print\f[R]
.PP
از \f[CB]jfr\ print\f[R] برای چاپ محتویات یک فایل ضبط پرواز در خروجی استاندارد استفاده کنید.
نحو دستور عبارت است از:
.PP
\f[CB]jfr\ print\f[R] [\f[CB]\-\-xml\f[R]|\f[CB]\-\-json\f[R]]
[\f[CB]\-\-categories\f[R] <\f[I]فیلترها\f[R]>] [\f[CB]\-\-events\f[R]
<\f[I]فیلترها\f[R]>] [\f[CB]\-\-stack\-depth\f[R] <\f[I]عمق\f[R]>]
<\f[I]فایل\f[R]>
.PP
که در آن:
.TP
.B \f[CB]\-\-xml\f[R]
چاپ ضبط در قالب XML
.RS
.RE
.TP
.B \f[CB]\-\-json\f[R]
چاپ ضبط در قالب JSON
.RS
.RE
.TP
.B \f[CB]\-\-categories\f[R] <\f[I]فیلترها\f[R]>
انتخاب رویدادهای منطبق با یک نام دسته‌بندی.
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob درون نقل‌قول است
.RS
.RE
.TP
.B \f[CB]\-\-events\f[R] <\f[I]فیلترها\f[R]>
انتخاب رویدادهای منطبق با یک نام رویداد.
فیلتر یک لیست جداشده با کاما از نام‌ها (ساده و/یا واجد شرایط) و/یا الگوهای glob درون نقل‌قول است
.RS
.RE
.TP
.B \f[CB]\-\-stack\-depth\f[R] <\f[I]عمق\f[R]>
تعداد فریم‌ها در ردپای پشته (stack trace)، به طور پیش‌فرض ۵
.RS
.RE
.TP
.B <\f[I]فایل\f[R]>
مکان فایل ضبط (\f[CB]\&.jfr\f[R])
.RS
.RE
.PP
قالب پیش‌فرض برای چاپ محتویات فایل ضبط پرواز، فرمت قابل خواندن توسط انسان است مگر اینکه \f[CB]xml\f[R] یا \f[CB]json\f[R] مشخص شده باشد.
این گزینه‌ها خروجی ماشین‌خوان ارائه می‌دهند که می‌تواند توسط اسکریپت‌های ایجادشده توسط کاربر تجزیه یا پردازش شود.
.PP
برای مشاهده نمونه استفاده از فیلترها از \f[CB]jfr\ \-\-help\ print\f[R] استفاده کنید.
.PP
برای کاهش مقدار داده‌های نمایش‌داده‌شده، فیلتر کردن رویدادها یا دسته‌بندی‌های رویدادها امکان‌پذیر است.
فیلتر بر روی نام نمادین یک رویداد (تنظیم‌شده با استفاده از حاشیه‌نویسی \f[CB]\@Name\f[R])، یا نام دسته‌بندی (تنظیم‌شده با استفاده از حاشیه‌نویسی \f[CB]\@Category\f[R]) عمل می‌کند.
اگر از چندین فیلتر استفاده شود، رویدادهای هر دو فیلتر گنجانده خواهند شد.
اگر هیچ فیلتری استفاده نشود، تمام رویدادها چاپ می‌شوند.
اگر ترکیبی از یک فیلتر دسته‌بندی و یک فیلتر رویداد استفاده شود، رویدادهای انتخاب‌شده اجتماع دو فیلتر خواهند بود.
.PP
به عنوان مثال، برای نمایش تمام رویدادهای GC و رویداد CPULoad، می‌توان از دستور زیر استفاده کرد:
.PP
\f[CB]jfr\ print\ \-\-categories\ GC\ \-\-events\ CPULoad\ recording.jfr\f[R]
.PP
مقادیر رویداد بر اساس انواع محتوایی که مورد استفاده قرار می‌گیرند قالب‌بندی می‌شوند.
به عنوان مثال، یک فیلد با حاشیه‌نویسی \f[CB]jdk.jfr.Percentage\f[R] که دارای مقدار 0.52 است به صورت 52% قالب‌بندی می‌شود.
.PP
ردپاهای پشته به طور پیش‌فرض به ۵ فریم کوتاه می‌شوند، اما این تعداد را می‌توان با استفاده از گزینه خط فرمان \f[CB]\-\-stack\-depth\f[R] افزایش یا کاهش داد.
.SS زیردستور \f[CB]jfr\ summary\f[R]
.PP
از \f[CB]jfr\ summary\f[R] برای چاپ آمار مربوط به یک ضبط استفاده کنید.
برای مثال، یک خلاصه می‌تواند تعداد رویدادهای ضبط‌شده و میزان فضای دیسکی را که استفاده کرده‌اند نشان دهد.
این امر برای عیب‌یابی و درک تأثیر تنظیمات رویداد مفید است.
.PP
نحو دستور عبارت است از:
.PP
\f[CB]jfr\ summary\f[R] <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
.B <\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[CB]\&.jfr\f[R])
.RS
.RE
.SS زیردستور \f[CB]jfr\ metadata\f[R]
.PP
از \f[CB]jfr\ metadata\f[R] برای مشاهده اطلاعات مربوط به رویدادها، مانند نام رویدادها، دسته‌بندی‌ها و چیدمان فیلدها در یک فایل ضبط پرواز استفاده کنید.
نحو دستور عبارت است از:
.PP
\f[CB]jfr\ metadata\f[R] <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
.B <\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[CB]\&.jfr\f[R])
.RS
.RE
.SS زیردستور \f[CB]jfr\ assemble\f[R]
.PP
از \f[CB]jfr\ assemble\f[R] برای سرهم‌بندی فایل‌های تکه (chunk) در یک فایل ضبط استفاده کنید.
.PP
نحو دستور عبارت است از:
.PP
\f[CB]jfr\ assemble\f[R] <\f[I]مخزن\f[R]> <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
.B <\f[I]مخزن\f[R]>
دایرکتوری که مخزن حاوی فایل‌های تکه در آن قرار دارد
.RS
.RE
.TP
.B <\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[CB]\&.jfr\f[R])
.RS
.RE
.PP
اطلاعات ضبط پرواز در قالب تکه‌ها (chunks) نوشته می‌شوند.
یک تکه حاوی تمام اطلاعات لازم برای تجزیه است.
یک تکه معمولاً شامل رویدادهای مفید برای عیب‌یابی است.
در صورتی که یک JVM کرش کند، این تکه‌ها قابل بازیابی هستند و می‌توان از آن‌ها برای ایجاد یک فایل ضبط پرواز با استفاده از این دستور \f[CB]jfr\ assemble\f[R] استفاده کرد.
این فایل‌های تکه به ترتیب زمانی به هم متصل می‌شوند و فایل‌های تکه‌ای که کامل نشده‌اند (.part) نادیده گرفته می‌شوند.
.SS زیردستور \f[CB]jfr\ disassemble\f[R]
.PP
از \f[CB]jfr\ disassemble\f[R] برای تجزیه یک فایل ضبط پرواز به قطعات فایل تکه آن استفاده کنید.
نحو دستور عبارت است از:
.PP
\f[CB]jfr\ disassemble\f[R] [\f[CB]\-\-max\-chunks\f[R] <\f[I]تکه‌ها\f[R]>]
[\f[CB]\-\-output\f[R] <\f[I]دایرکتوری\f[R]>] <\f[I]فایل\f[R]>
.PP
که در آن:
.TP
.B \f[CB]\-\-output\f[R] <\f[I]دایرکتوری\f[R]>
مکان نوشتن فایل‌های تجزیه‌شده، به طور پیش‌فرض دایرکتوری جاری
.RS
.RE
.TP
.B \f[CB]\-\-max\-chunks\f[R] <\f[I]تکه‌ها\f[R]>
حداکثر تعداد تکه‌ها در هر فایل، به طور پیش‌فرض ۵.
اندازه تکه متفاوت است، اما معمولاً حدود ۱۵ مگابایت است.
.RS
.RE
.TP
.B \f[CB]\-\-max\-size\f[R] <\f[I]اندازه\f[R]>
حداکثر تعداد بایت در هر فایل.
.RS
.RE
.TP
.B <\f[I]فایل\f[R]>
مکان فایل ضبط پرواز (\f[CB]\&.jfr\f[R])
.RS
.RE
.PP
این قابلیت می‌تواند برای تعمیر یک فایل خراب با حذف تکه معیوب مفید باشد.
همچنین می‌توان از آن برای کاهش اندازه فایلی که برای انتقال بیش از حد بزرگ است استفاده کرد.
فایل‌های تکه حاصل با نام‌های \f[CB]myfile_1.jfr\f[R]،
\f[CB]myfile_2.jfr\f[R] و غیره نام‌گذاری می‌شوند.
در صورت نیاز، نام‌های فایل‌های حاصل با صفر پر می‌شوند تا ترتیب زمانی حفظ شود.
برای مثال، اگر ضبط شامل بیش از ۱۰۰ تکه باشد، نام فایل تکه \f[CB]myfile_001.jfr\f[R] خواهد بود.
.SS زیردستورهای version و help در jfr
.PP
از \f[CB]jfr\ \-\-version\f[R] یا \f[CB]jfr\ version\f[R] برای مشاهده اطلاعات رشته نسخه برای این دستور jfr استفاده کنید.
.PP
برای دریافت راهنما در مورد هر یک از زیردستورهای jfr، استفاده کنید از:
.PP
\f[CB]jfr\ <\-\-help|help>\f[R] [\f[I]زیردستور\f[R]]
.PP
که در آن:
.PP
[\f[I]زیردستور\f[R]] یکی از موارد زیر است:
.IP \[bu] 2
\f[CB]print\f[R]
.IP \[bu] 2
\f[CB]metadata\f[R]
.IP \[bu] 2
\f[CB]summary\f[R]
.IP \[bu] 2
\f[CB]assemble\f[R]
.IP \[bu] 2
\f[CB]disassemble\f[R]