'\" t
.\"
.\" Copyright (c) 2015-2018,2022 Red Hat.
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program 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
.\" for more details.
.\"
.\"
.TH PMVAL 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmval\f1,
\f3pmevent\f1 \- استخراج و نمایش مقادیر معیارهای کارایی دلخواه
.SH "خلاصه دستور (SYNOPSIS)"
\f3pmval\f1
[\f3\-dgLrvVXz?\f1]
[\f3\-a\f1 \f2archive\f1]
[\f3\-A\f1 \f2align\f1]
[\f3\-\-container\f1=\f2name\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-\-derived\f1=\f2file\f1]
[\f3\-f\f1 \f2N\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-i\f1 \f2instances\f1]
[\f3\-K\f1 \f2spec\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-O\f1 \f2offset\f1]
[\f3\-p\f1 \f2port\f1]
[\f3\-s\f1 \f2samples\f1]
[\f3\-S\f1 \f2starttime\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-T\f1 \f2endtime\f1]
[\f3\-U\f1 \f2archive\f1]
[\f3\-w\f1 \f2width\f1]
[\f3\-x\f1 \f2pattern\f1]
[\f3\-Z\f1 \f2timezone\f1]
\f2metricname\f1
.sp
\f3pmevent\f1
\&...
.SH "توضیحات (DESCRIPTION)"
.de EX
.in +0.5i
.ie t .ft CB
.el .ft B
.ie t .sp .5v
.el .sp
.ta \\w' 'u*8
.nf
..
.de EE
.fi
.ie t .sp .5v
.el .sp
.ft R
.in
..
دستور
.B pmval
مقادیر جاری یا بایگانی‌شده را برای معیار کارایی مشخص‌شده چاپ می‌کند.
معیار مورد نظر در آرگومان
.I metricname
نام‌گذاری می‌شود و بنا به توضیح زیر، مشروط به تعیین نمونه‌ها (instance qualification) با پرچم
.B \-i
است.
.PP
مگر در صورتی که توسط گزینهٔ
.B \-h
به یک میزبان دیگر، یا با گزینه‌های
.B \-a
یا
.B \-U
به مجموعه‌ای از بایگانی‌ها هدایت شود،
.B pmval
برای دریافت اطلاعات مورد نیاز با دیمن جمع‌آوری معیارهای کارایی (PMCD) در میزبان محلی ارتباط برقرار خواهد کرد.
.PP
آرگومان
.I metricname
همچنین می‌تواند در ساختار دستوری مشخص‌سازی معیار، همان‌گونه که در
.BR PCPIntro (1)
شرح داده شده است، مشخص گردد؛ جایی که منبع، معیار و نمونه می‌توانند همگی در
.I metricname
گنجانده شوند، مانند: thathost:kernel.all.load["1 minute"].
هنگام استفاده از این قالب، هیچ‌یک از گزینه‌های
.BR \-h ،
.B \-a
یا
.B \-U
نباید مشخص شوند.
.PP
هنگام استفاده از ساختار دستوری مشخص‌سازی معیار، «نام میزبانِ»
.B @
به‌طور ویژه‌ای مدیریت می‌شود و سبب می‌گردد
.B pmval
از یک زمینهٔ محلی (local context) برای جمع‌آوری معیارها از PMDAها روی میزبان محلی بدون نیاز به PMCD استفاده کند.
در این حالت تنها برخی از معیارها در دسترس هستند.
.PP
هنگام پردازش مجموعه‌ای از بایگانی‌ها،
.B pmval
ممکن است کنترل زمان‌بندی خود را واگذار کند و تحت کنترل یک فرایند
.BR pmtime (1)
عمل کند که از یک کادر گفتگوی گرافیکی (GUI) برای کنترل زمان‌بندی بهره می‌برد.
در این حالت، یا باید از گزینهٔ
.B \-g
برای راه‌اندازی
.B pmval
به‌عنوان تنها کلاینتِ یک نمونهٔ جدید از
.BR pmtime (1)
استفاده شود، یا از گزینهٔ
.B \-p
برای اتصال
.B pmval
به یک نمونهٔ موجود از
.BR pmtime (1)
از طریق کانال IPC مشخص‌شده با آرگومان
.I port
استفاده گردد.
.PP
گزینه‌های
.BR \-S ،
.BR \-T ،
.B \-O
و
.B \-A
می‌توانند برای تعریف یک پنجرهٔ زمانی جهت محدود کردن نمونه‌های بازیابی‌شده، تنظیم مبدأ اولیه در پنجرهٔ زمانی، یا مشخص کردن یک تراز «طبیعی» (natural alignment) برای زمان‌های نمونه‌برداری به کار روند؛ برای شرح کامل این گزینه‌ها به
.BR PCPIntro (1)
مراجعه کنید.
.PP
خروجی
.B pmval
به خروجی استاندارد هدایت می‌شود.
گاهی اوقات ممکن است نمادهای زیر به‌جای مقدار یک معیار در خروجی
.B pmval
ظاهر شوند: نماد علامت سؤال (?) نشان می‌دهد که مقداری دیگر برای آن نمونه از معیار در دسترس نیست.
یک علامت تعجب (!) نشان می‌دهد که یک شمارندهٔ ۶۴ بیتی در طول نمونه‌برداری دور زده است (counter wrapped).
.PP
دستور
.B pmevent
یک نام مستعار برای
.BR pmval
است..SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمان در دسترس عبارتند از:
.TP 5
\fB\-a\fR \fIarchive\fR, \fB\-\-archive\fR=\fIarchive\fR
مقادیر متریک‌های کارایی از مجموعه‌ای از فایل‌های آرشیو Performance Co-Pilot (PCP) مشخص‌شده توسط آرگومان
.I archive
بازیابی می‌شوند؛ این آرگومان فهرستی از نام‌های جداشده با کاما است که هر یک می‌تواند نام پایه یک آرشیو یا نام یک دایرکتوری حاوی یک یا چند آرشیو باشد.
همچنین ببینید:
.BR \-U .
.TP
\fB\-A\fR \fIalign\fR, \fB\-\-align\fR=\fIalign\fR
نمونه اولیه را مجبور می‌کند تا بر روی مرز یک واحد زمانی طبیعی
.IR align
تراز شود.
برای شرح کامل نحو
.IR align
به
.BR PCPIntro (1)
مراجعه کنید.
.TP
\fB\-\-container\fR=\fIcontainer\fR
یک
.I container
مشخص را برای پرس‌وجو تعیین می‌کند.
.TP
\fB\-d\fR, \fB\-\-delay\fR
هنگام بازپخش از یک آرشیو، این گزینه درخواست می‌کند که تاخیر زمانی واقعی (real-time) غالب بین نمونه‌ها اعمال شود (ببینید
.BR \-t )
تا به جای رفتار پیش‌فرض بازپخش با سرعت کامل، مکثی ایجاد شود.
.TP
\fB\-\-derived\fR=\fIfile\fR
تعاریف متریک‌های مشتق‌شده را از
.IR file
بارگذاری می‌کند.
.TP
\fB\-f\fR \fIprecision\fR, \fB\-\-precision\fR=\fIprecision\fR
اعداد به جای نماد علمی پیش‌فرض، در نماد «ممیز ثابت» با استفاده از
.IR precision
رقم برای دقت گزارش می‌شوند.
هر عدد حداکثر به اندازه عرض ستون تعیین‌شده توسط قواعد تجربی پیش‌فرض خواهد بود، مگر اینکه گزینه
.B \-w
مشخص شده باشد، و شامل
.I precision
رقم پس از ممیز اعشار است.
بنابراین، گزینه‌های
.B "\-f 3 \-w 8"
اعدادی به شکل 9999.999 تولید می‌کنند.
مقدار صفر برای
.I precision
ممیز اعشار و هرگونه ارقام کسری را حذف می‌کند.
.TP
\fB\-g\fR, \fB\-\-guimode\fR
دستور
.B pmval
را به عنوان تنها کلاینت یک پردازه کارساز جدید
.BR pmtime (1)
جهت بازپخش داده‌های کارایی آرشیوشده با استفاده از واسط گرافیکی کاربر
.BR pmtime (1)
اجرا می‌کند.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
متریک‌های کارایی را به جای localhost پیش‌فرض، از
.BR pmcd (1)
روی
.IR host
دریافت می‌کند.
.TP
\fB\-i\fR \fIinstances\fR, \fB\-\-instances\fR=\fIinstances\fR
فهرستی از یک یا چند نام از
.I instances
(نمونه‌ها) را برای متریک کارایی نامزدشده مشخص می‌کند \- تنها همین
.I instances
بازیابی و گزارش خواهند شد
(پیش‌فرض، گزارش تمام نمونه‌ها است).
این فهرست باید یک آرگومان واحد باشد و عناصر فهرست با کاما و/یا نویسه فاصله از هم جدا شوند.
.RS
.PP
در مواردی که نام نمونه شامل نویسه فاصله یا کاما است، نام نمونه می‌تواند درون علامت‌های نقل‌قول تکی (') یا دوگانه (") قرار گیرد.
.PP
استفاده از چندین گزینه
.B \-i
به عنوان روشی جایگزین جهت تعیین بیش از یک نمونهٔ مورد نظر مجاز است.
.PP
به عنوان مثال، موارد زیر همگی معادل هستند:
.EX
$ pmval \-i "'1 minute','5 minute'" kernel.all.load
$ pmval \-i '"1 minute","5 minute"' kernel.all.load
$ pmval \-i "'1 minute' '5 minute'" kernel.all.load
$ pmval \-i "'1 minute'" \-i "'5 minute'" kernel.all.load
$ pmval 'localhost:kernel.all.load["1 minute","5 minute"]'
.EE
.RE
.TP
\fB\-K\fR \fIspec\fR, \fB\-\-spec\-local\fR=\fIspec\fR
هنگام دریافت متریک‌ها از یک بافت محلی (ببینید
.BR \-L )،
گزینه
.B \-K
می‌تواند برای کنترل DSO PMDAهایی که باید قابل دسترسی باشند استفاده شود.
آرگومان
.I spec
از نحو شرح داده شده در
.BR pmSpecLocalPMDA (3)
پیروی می‌کند.
بیش از یک گزینه
.B \-K
می‌تواند استفاده شود.
.TP
\fB\-L\fR, \fB\-\-local\-PMDA\fR
استفاده از یک بافت محلی برای گردآوری متریک‌ها از DSO PMDAها روی میزبان محلی بدون PMCD.
همچنین ببینید:
.BR \-K .
.TP
\fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR
یک فضای نام متریک‌های کارایی جایگزین
.RB ( PMNS (5))
را از فایل
.IR pmnsfile
بارگذاری می‌کند.
.TP
\fB\-O\fR \fIorigin\fR, \fB\-\-origin\fR=\fIorigin\fR
هنگام گزارش متریک‌های آرشیوشده، گزارش‌گیری از
.I origin
درون بازه زمانی آغاز می‌شود (ببینید
.B \-S
و
.BR \-T ).
برای شرح کامل نحو
.IR origin
به
.BR PCPIntro (1)
مراجعه کنید.
.TP
\fB\-p\fR \fIport\fR, \fB\-\-guiport\fR=\fIport\fR
دستور
.B pmval
را از طریق کانال IPC مشخص‌شده با آرگومان
\f2port\f1
به یک پردازه موجود کنترل زمان
.BR pmtime (1)
متصل می‌کند.
این گزینه معمولاً تنها توسط سایر ابزارها، مانند
.BR pmchart (1)،
هنگامی که
.B pmval
را با کنترل زمان همگام‌سازی‌شده اجرا می‌کنند، استفاده می‌شود.
.TP
\fB\-r\fR, \fB\-\-raw\fR
چاپ مقادیر خام برای متریک‌های شمارنده تجمعی.
به طور معمول متریک‌های شمارنده تجمعی به نرخ تبدیل می‌شوند.
به عنوان مثال، انتقال‌های دیسک به جای مقدار خام تعداد انتقال‌های دیسک از زمان راه‌اندازی سامانه، به صورت تعداد انتقال‌های دیسک در ثانیه در طول بازه نمونه‌برداری پیشین گزارش می‌شوند.
اگر این گزینه را مشخص کنید، مقادیر خام متریک چاپ می‌شوند.
.TP
\fB\-s\fR \fIsamples\fR, \fB\-\-samples\fR=\fIsamples\fR
آرگومان
.I samples
تعداد نمونه‌هایی را که باید بازیابی و گزارش شوند تعیین می‌کند.
اگر
.I samples
برابر 0 باشد یا
.B \-s
مشخص نشده باشد،
.B pmval
به صورت مداوم (در حالت بی‌درنگ) یا تا انتهای مجموعه آرشیوهای PCP (در حالت آرشیو) به نمونه‌برداری و گزارش ادامه می‌دهد.
.TP
\fB\-S\fR \fIstarttime\fR, \fB\-\-start\fR=\fIstarttime\fR
هنگام گزارش متریک‌های آرشیوشده، گزارش به رکوردهایی محدود خواهد شد که در
.IR starttime
یا پس از آن ثبت شده‌اند.
برای شرح کامل نحو
.IR starttime
به
.BR PCPIntro (1)
مراجعه کنید..TP
\fB\-t\fR \fIinterval\fR, \fB\-\-interval\fR=\fIinterval\fR
تنظیم بازه گزارش‌دهی
.I interval
به مقداری غیر از ۱ ثانیه پیش‌فرض.
آرگومان
.I interval
از ساختار نحوی شرح داده شده در
.BR PCPIntro (1)
پیروی می‌کند و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد
(واحدهای ضمنی در این حالت ثانیه هستند).
.TP
\fB\-T\fR \fIendtime\fR, \fB\-\-finish\fR=\fIendtime\fR
هنگام گزارش معیارهای بایگانی‌شده، گزارش به رکوردهایی که قبل از
.IR endtime
یا در همان زمان ثبت شده‌اند، محدود خواهد شد.
برای شرح کامل ساختار نحوی
.IR endtime
به
.BR PCPIntro (1)
مراجعه کنید.
.TP
\fB\-U\fR \fIarchive\fR, \fB\-\-nointerp\fR=\fIarchive\fR
مقادیر معیارهای کارایی از
.IR archive
در Performance Co-Pilot (PCP) بازیابی می‌شوند.
آرگومان، فهرستی از نام‌ها است که با کاما از هم جدا شده‌اند، و هر یک
می‌تواند نام پایه یک بایگانی یا نام دایرکتوری حاوی یک یا چند بایگانی باشد.
با این حال، برخلاف
.B \-a
هر مقدار ثبت‌شده در بایگانی برای معیار و نمونه‌های انتخاب‌شده گزارش می‌شود
(بنابراین حالت درون‌یابی وجود ندارد و بازه نمونه‌برداری (گزینه \c
.B \-t\c
) نادیده گرفته می‌شود).
همچنین نگاه کنید به
.BR \-a .
.RS +5n
.PP
حداکثر یکی از گزینه‌های
.B \-a
و
.B \-U
می‌تواند مشخص شود.
.RE
.TP
\fB\-v\fR, \fB\-\-verbose\fR
فعال کردن حالت پرگو (verbose).
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش شماره نسخه و خروج.
.TP
\fB\-w\fR \fIwidth\fR, \fB\-\-width\fR=\fIwidth\fR
تنظیم عرض هر ستون از خروجی به تعداد ستون‌های
.IR width .
در صورت عدم تعیین، ستون‌ها به اندازه‌ای عریض خواهند بود
که بزرگ‌ترین مقدار نوع داده‌ای در حال چاپ را در خود جای دهند.
.TP
\fB\-x\fR \fIpattern\fR, \fB\-\-filter\fR=\fIpattern\fR
الگوی
.I pattern
داده‌شده، پیش از درخواست هرگونه مقدار، به عامل دامنه معیارهای کارایی برای
.I metricname
درخواست‌شده ارسال می‌شود.
این کار در خدمت دو هدف است.
نخست، سازوکاری برای پالایش رویدادها در سمت سرور فراهم می‌کند
که برای جریان‌های رویداد مجزا قابل سفارشی‌سازی است.
علاوه بر این، برخی از عامل‌های دامنه معیارهای کارایی نیز از سازوکار ذخیره PMCD برای ارائه یک مدل امنیتی پایه استفاده می‌کنند (برای مثال برای
فایل‌های لاگ حساس، تنها یک میزبان کلاینت با دسترسی
.BR pmStore (3)
می‌تواند به جریان رویداد دسترسی داشته باشد).
.RS
.PP
از آنجا که
.I pattern
ممکن است توسط
.BR regcomp (3)
پردازش شود، باید یک رشته غیرخالی باشد.
از . (نقطه) برای یک
.I pattern
از نوع \(lqmatch all\(rq (تطبیق با همه) استفاده کنید.
.RE
.TP
\fB\-X\fR, \fB\-\-timestamp\fR
هنگام بازپخش از یک بایگانی، این گزینه درخواست می‌کند که
برچسب زمانی همراه با اطلاعات تاریخ اضافی و دقت افزایش‌یافته گزارش شود
(میکروثانیه با یک بار \fB\-X\fR، نانوثانیه با یک \fB\-X\fR
اضافی)، برای مثال
.B "Sat\ May\ 22\ 20:32:20.971633\ 2021"
به جای قالب پیش‌فرض، مانند
.BR "20:32:20.971" .
.TP
\fB\-z\fR, \fB\-\-hostzone\fR
استفاده از منطقه زمانی محلی میزبانی که منبع
معیارهای کارایی است، همان‌طور که توسط گزینه‌های
.B \-h
یا
.B \-a
یا
.B \-U
مشخص شده است.
حالت پیش‌فرض استفاده از منطقه زمانی میزبان محلی است.
.TP
\fB\-Z\fR \fItimezone\fR, \fB\-\-timezone\fR=\fItimezone\fR
استفاده از
.I timezone
برای تاریخ و زمان.
.I timezone
در قالب متغیر محیطی
.B TZ
است، همان‌گونه که در
.BR environ (7)
شرح داده شده است.
.TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام راهنما و خروج..SH "هشدارها (CAVEATS)"
به‌طور پیش‌فرض،
.B pmval
تلاش می‌کند مقادیر عددی غیرصحیح را به‌گونه‌ای نمایش دهد که به دقت ذاتی آن‌ها (که به‌ندرت بیش از ۴ رقم بااهمیت است) خدشه‌ای وارد نشود، و سعی می‌کند قالب جدول‌بندی‌شده را در خروجی حفظ نماید.
این اهداف گاهی با یکدیگر در تضاد هستند.
.PP
در صورت عدم وجود گزینهٔ
.B \-f
(که در بالا شرح داده شد)، جدول زیر قالب‌های استفاده‌شده برای محدوده‌های مختلف مقادیر عددی را برای هر معیاری از نوع
.B PM_TYPE_FLOAT
یا
.BR PM_TYPE_DOUBLE ،
یا هر معیاری که دارای معناشناسی شمارنده باشد (که برای آن
.B pmval
مقدار تبدیل‌شده به نرخ را گزارش می‌کند) توصیف می‌کند:
.TS
box,center;
cf(R) | cf(R)
rf(CR) | lf(R).
قالب	محدوده مقادیر
_
!	مقداری در دسترس نیست
9.999E-99	< 0.1
0.0\0\0\0	0
9.9999	> 0 و <= 0.9999
9.999\0	> 0.9999 و < 9.999
99.99\0\0	> 9.999 و < 99.99
999.9\0\0\0	> 99.99 و < 999.9
9999.\0\0\0\0	> 999.9 و < 9999
9.999E+99	> 9999
.TE
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای پارامتربندی نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
از متغیر \fB$PCP_CONF\fP می‌توان برای مشخص کردن یک فایل پیکربندی جایگزین استفاده کرد، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده است.
.PP
برای متغیرهای محیطی که بر ابزارهای PCP تأثیر می‌گذارند، به \fBpmGetOptions\fP(3) مراجعه کنید.
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینهٔ
.B \-D
یا
.B \-\-debug
خروجی اطلاعات تشخیصی اضافی را روی
.I stderr
فعال می‌کند تا به عیب‌یابی و تفکیک مشکلات کمک نماید، هرچند این اطلاعات گاهی مبهم بوده و در درجه اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی.
.I debug
فهرستی از گزینه‌های اشکال‌زدایی جداشده با کاما است؛ از
.BR pmdbg (1)
همراه با گزینهٔ
.B \-l
استفاده کنید تا فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها را به دست آورید.
.PP
گزینه‌های اشکال‌زدایی مختص
.B pmval
به شرح زیر است:
.TS
box;
lf(B) | lf(B)
lf(B) | lf(R) .
گزینه	توضیحات
_
appl0	موقعیت‌یابی اولیهٔ خط زمانی هنگام استفاده از \f3\-a\fP
.TE
.SH "همچنین ببینید (SEE ALSO)"
.BR PCPIntro (1)،
.BR pmcd (1)،
.BR pmchart (1)،
.BR pmdumptext (1)،
.BR pminfo (1)،
.BR pmlogdump (1)،
.BR pmlogger (1)،
.BR pmrep (1)،
.BR pmtime (1)،
.BR PMAPI (3)،
.BR pmSpecLocalPMDA (3)،
.BR pmStore (3)،
.BR pcp.conf (5)،
.BR pcp.env (5)
و
.BR PMNS (5).

.\" control lines for scripts/man-spell
.\" +ok+ sp {from .sp in troff macro defn} thathost