'\" t
.\"
.\" Copyright (c) 2016 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 PMLOGSUMMARY 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmlogsummary\f1 \- محاسبه میانگین معیارهای ذخیره‌شده در مجموعه‌ای از آرشیوهای PCP
.SH "خلاصه دستور (SYNOPSIS)"
\f3pmlogsummary\f1
[\f3\-abfFHiIlmMNsvVxyz?\f1]
[\f3\-B\f1 \f2nbins\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-p\f1 \f2precision\f1]
[\f3\-S\f1 \f2starttime\f1]
[\f3\-T\f1 \f2endtime\f1]
[\f3\-Z\f1 \f2timezone\f1]
\f2archive\f1
[\f2metricname\f1 ...]
.SH "توضیحات (DESCRIPTION)"
دستور
.B pmlogsummary
اطلاعات آماری درباره معیارهای از نوع عددی موجود در فایل‌های مجموعه‌ای از آرشیوهای Performance Co-Pilot (PCP) را چاپ می‌کند.
خروجی پیش‌فرض، میانگین‌های زمانی را برای هر دو معیار شمارنده (counter) و غیرشمارنده چاپ می‌کند.
مجموعه آرشیوها توسط
.IR archive
مشخص می‌شود که فهرستی جداشده با ویرگول از نام‌ها است؛ هر یک
می‌تواند نام پایه یک آرشیو یا نام یک دایرکتوری حاوی
یک یا چند آرشیو باشد.
آرشیوها معمولاً با استفاده از
.BR pmlogger (1)
ایجاد می‌شوند.
.PP
معیارهای مورد نظر در آرگومان‌های
.I metricname
مشخص می‌شوند.
اگر
.I metricname
یک گره غیربرگ در «فضای نام معیارهای کارایی» (\c
.BR PMNS (5))
باشد، آن‌گاه
.B pmlogsummary
به‌صورت بازگشتی در PMNS پیمایش کرده و تمام گره‌های برگ را گزارش می‌کند.
اگر هیچ آرگومان
.I metricname
ارائه نشود، از ریشه فضای نام استفاده خواهد شد.
.PP
معیارهای دارای معناشناسی شمارنده پیش از ارزیابی به نرخ (rate) تبدیل می‌شوند.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمان موجود عبارتند از:
.TP 5
\fB\-a\fR, \fB\-\-all\fR
چاپ تمام اطلاعات.
این گزینه معادل
.BR \-blmMy
است.
.TP
\fB\-b\fR
چاپ هر دو شکل میانگین‌گیری، یعنی هم میانگین تصادفی (stochastic) و هم میانگین زمانی.
.TP
\fB\-B\fR \fInbins\fR, \fB\-\-bins\fR=\fInbins\fR
چاپ توزیع تقریبی مقادیر، با استفاده از دسته‌های هیستوگرام (histogram bins) به نحوی
که بازه مقادیر (حداقل - حداکثر) برای هر معیار به‌طور مساوی به
.I nbins
دسته تقسیم می‌شود، و هر دسته فراوانی مقادیر مشاهده‌شده در
بازه مربوطه را انباشته می‌کند.
برای شرح نحوه گزارش توزیع مقادیر، به بخش \(lqOUTPUT FORMAT\(rq در زیر مراجعه کنید.
.TP
\fB\-f\fR
قالب صفحه‌گسترده \- از نویسه tab برای جداسازی هر فیلد چاپ‌شده استفاده می‌شود.
این گزینه با این هدف در نظر گرفته شده که خروجی
.B pmlogsummary
بتواند مستقیماً به برنامه‌های کاربردی رایج صفحه‌گسترده وارد شود.
.TP
\fB\-F\fR
قالب صفحه‌گسترده \- از نویسه ویرگول برای جداسازی هر فیلد چاپ‌شده استفاده می‌شود.
این گزینه با این هدف در نظر گرفته شده که خروجی
.B pmlogsummary
بتواند مستقیماً به برنامه‌های کاربردی رایج صفحه‌گسترده که
از قالب مقادیر جداشده با ویرگول (.csv) پشتیبانی می‌کنند وارد شود.
.TP
\fB\-H\fR, \fB\-\-header\fR
چاپ یک سربرگ تک‌خطی در ابتدا که نشان می‌دهد هر فیلد نمایانگر چیست.
.TP
\fB\-i\fR, \fB\-\-mintime\fR
همچنین زمانی را که حداقل مقدار ثبت شده است، چاپ می‌کند.
قالب این برچسب زمانی در بخش \(lqOUTPUT FORMAT\(rq در زیر شرح داده شده است.
.TP
\fB\-I\fR, \fB\-\-maxtime\fR
همچنین زمانی را که حداکثر مقدار ثبت شده است، چاپ می‌کند.
قالب این برچسب زمانی در بخش \(lqOUTPUT FORMAT\(rq در زیر شرح داده شده است.
.TP
\fB\-l\fR, \fB\-\-label\fR
همچنین برچسب آرشیو را چاپ می‌کند که نسخه قالب آرشیو،
زمان و تاریخ شروع و پایان پنجره زمانی آرشیو،
و میزبانی را که مقادیر معیارهای کارایی از آن جمع‌آوری شده‌اند، نشان می‌دهد.
.TP
\fB\-m\fR, \fB\-\-minimum\fR
همچنین حداقل مقدار ثبت‌شده را برای هر معیار چاپ می‌کند.
.TP
\fB\-M\fR, \fB\-\-maximum\fR
همچنین حداکثر مقدار ثبت‌شده را برای هر معیار چاپ می‌کند.
.TP
\fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR
بارگذاری یک «فضای نام معیارهای کارایی»
.RB ( PMNS (5))
جایگزین از فایل
.IR pmnsfile .
.TP
\fB\-N\fR
فرونشاندن هرگونه هشدار ناشی از واکشی‌های جداگانه آرشیو (پیش‌فرض).
.TP
\fB\-p\fR \fIprecision\fR, \fB\-\-precision\fR=\fIprecision\fR
چاپ تمام اعداد ممیز شناور با
.I precision
رقم بعد از ممیز اعشار.
.TP
\fB\-s\fR, \fB\-\-sum\fR
چاپ (تنها) مجموع تمام مقادیر ثبت‌شده برای هر معیار.
.TP
\fB\-S\fR \fIstarttime\fR, \fB\-\-start\fR=\fIstarttime\fR
تنظیم
.I starttime
پنجره زمانی.
برای شرح کامل ساختار نحوی
.IR starttime ،
به
.BR PCPIntro (1)
مراجعه کنید.
.TP
\fB\-T\fR \fIendtime\fR, \fB\-\-finish\fR=\fIendtime\fR
تنظیم
.I endtime
پنجره زمانی.
برای شرح کامل ساختار نحوی
.IR endtime ،
به
.BR PCPIntro (1)
مراجعه کنید.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
گزارش هشدارهای ناشی از واکشی‌های جداگانه آرشیو (با جزئیات کامل).
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش شماره نسخه و خروج.
.TP
\fB\-x\fR
چاپ میانگین‌های تصادفی به جای میانگین‌های پیش‌فرض (میانگین‌های زمانی).
.TP
\fB\-y\fR, \fB\-\-samples\fR
همچنین تعداد نمونه‌های دیده‌شده در مجموعه آرشیوها را برای هر معیار چاپ می‌کند.
.TP
\fB\-z\fR, \fB\-\-hostzone\fR
تغییر منطقه زمانی به منطقه زمانی محلی میزبانی
که منبع معیارهای کارایی است، همان‌طور که در
رکورد برچسب آرشیو مشخص شده است.
.TP
\fB\-Z\fR \fItimezone\fR, \fB\-\-timezone\fR=\fItimezone\fR
به‌طور پیش‌فرض،
.B pmlogsummary
ساعت روز را بر اساس منطقه زمانی محلی سیستمی که
.B pmlogsummary
روی آن اجرا می‌شود، گزارش می‌کند.
منطقه زمانی را به
.I timezone
در قالب متغیر محیطی
.B TZ
مطابق با توضیحات
.BR environ (7)
تغییر می‌دهد..TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام راهنمای استفاده و خروج.
.SH "قالب خروجی (OUTPUT FORMAT)"
قالب خروجی
.B pmlogsummary
ساده و حداقلی است، چرا که هدف آن پردازش پس‌آیند با ابزارهای استاندارد است.
این بدان معناست که هیچ یادداشت یا توضیح اضافی مرتبط با فیلدهای خروجی وجود ندارد، تا پردازش خودکار آن دشوار نشود.
هدف این است که خروجی
.B pmlogsummary
را بتوان به قالبی تبدیل کرد که در برنامه‌های صفحه‌گسترده قابل استفاده باشد، برای گنجاندن در یک صفحهٔ وب مناسب باشد، یا هر کاربرد دیگری را پوشش دهد.
.PP
برای هر متریک،
.B pmlogsummary
یک خط خروجی به شکل زیر تولید می‌کند:
.PP
.in 1.0i
.ft CR
.nf
\f2metricname\f1  \f2value(s)\f1 \f2units\f1
.fi
.ft R
.in
.PP
برای متریک‌های دارای چندین نمونه (instance)،
.B pmlogsummary
چندین خط خروجی به صورت زیر تولید می‌کند:
.PP
.in 1.0i
.ft CR
.nf
\f2metricname\f1 ["\f2instance 1\f1"] \f2value(s)\f1 \f2units\f1
\f2metricname\f1 ["\f2instance 2\f1"] \f2value(s)\f1 \f2units\f1
\f2metricname\f1 ["\f2instance N\f1"] \f2value(s)\f1 \f2units\f1
.fi
.ft R
.in
.PP
مقادیر چاپ‌شدهٔ \f2value(s)\f1 برای هر متریک همیشه از این ترتیب پیروی می‌کنند:
میانگین تصادفی، میانگین زمانی، کمینه، برچسب زمانی کمینه، بیشینه،
برچسب زمانی بیشینه، تعداد، [محدودهٔ bin 1]، شمارش bin 1، ... [محدودهٔ bin
.I nbins
]، شمارش bin
.I nbins
\&.
مقادیر مجزا برای هر متریک با فاصله (space) از یکدیگر جدا می‌شوند (مگر اینکه از گزینهٔ
.B \-f
استفاده شده باشد).
.PP
تمام متریک‌های شمارنده (counter) که برحسب واحدهای زمانی سنجیده می‌شوند، پیش از تبدیل نرخ و استفاده در محاسبات
.B pmlogsummary
به ثانیه تبدیل خواهند شد.
مقادیر محاسبه‌شده برای این متریک‌ها نیز برحسب ثانیه چاپ می‌شوند.
.PP
واحدها در قالبی که توسط
.BR pmUnitsStr (3)
توصیف شده است نمایش داده خواهند شد.
.PP
در صورت مشخص شدن هر یک از گزینه‌های
.B -i
یا
.B -I
، دستور
.B pmlogsummary
بسته به بازهٔ زمانی اجرای خود، دو قالب مختلف برای برچسب زمانی تولید می‌کند.
برای بازه‌ای بیش از ۲۴ ساعت، علاوه بر زمانی که بیشینه‌ها و/یا کمینه‌ها رخ داده‌اند، تاریخ نیز نمایش داده می‌شود.
اگر گسترهٔ داده‌های در حال بررسی کمتر از ۲۴ ساعت باشد،
قالبی دقیق‌تر به کار می‌رود (زمان با دقت میلی‌ثانیه اما بدون تاریخ نمایش داده می‌شود).
.SH "نکات (NOTES)"
میانگین برای یک متریک منفرد به شرح زیر محاسبه می‌شود:
.PP
متریک‌های غیرشمارنده با استفاده از میانگین‌گیری تصادفی محاسبه می‌شوند -
هر مشاهده در محاسبهٔ میانگین دارای وزن یکسانی است (مجموع همهٔ مقادیر تقسیم بر تعداد کل مقادیر، برای هر متریک).
.PP
متریک‌های شمارنده (به‌طور پیش‌فرض) با استفاده از میانگین‌گیری زمانی محاسبه می‌شوند،
اما می‌توان از گزینهٔ
.B \-x
استفاده کرد تا مشخص شود شمارنده‌ها در عوض با روش تصادفی میانگین‌گیری شوند.
هنگام محاسبهٔ میانگین زمانی،
مجموع حاصل‌ضرب هر مقدار نمونه در اختلاف زمانی بین هر نمونه، بر کل زمانی که متریک در آن ثبت شده تقسیم می‌شود.
.PP
متریک‌های شمارنده‌ای که اندازه‌گیری‌های آن‌ها ۹۰٪ از مجموعهٔ آرشیوها را پوشش نمی‌دهد، با یک علامت ستاره (*) در ابتدای نام متریک چاپ خواهند شد..SH "مثال‌ها (EXAMPLES)"
.nf
$ pmlogsummary \-aN \-p 1 \-B 3 surf network.interface.out.bytes
Log Label (Log Format Version 1)
Performance metrics from host www.sgi.com
  commencing Tue Jan 14 20:50:50.317 1997
  ending     Wed Jan 29 10:13:07.387 1997
network.interface.out.bytes ["xpi0"] 202831.3 202062.5 20618.7 \e
	1235067.7 971 [<=425435.0] 912 [<=830251.4] 42 [<=1235067.7] \e
	17 byte / sec
network.interface.out.bytes ["xpi1"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \e
	1033 [] 0 [] 0 byte / sec
network.interface.out.bytes ["et0"] 0.0 0.0 0.0 0.0 1033 [<=0.0] \e
	1033 [] 0 [] 0 byte / sec
network.interface.out.bytes ["lo0"] 899.0 895.2 142.6 9583.1 1031 \e
	[<=3289.4] 1027 [<=6436.2] 3 [<=9583.1] 1 byte / sec
.fi
.sp
توضیحات مربوط به هر فیلد در سطر نخستِ خروجی آماری، که توصیف‌کننده یک نمونه از متریک network.interface.out.bytes است، در ادامه آمده است:
.TS
box,center;
cf(R) | cf(R)
lf(CR) | lf(R).
فیلد	مفهوم
_
["xpi0"]	نام نمونه
202831.3	میانگین تصادفی
202062.5	میانگین زمانی
20618.7	مقدار کمینه
1235067.7	مقدار بیشینه
971	تعداد کل مقادیر برای این نمونه
[<=425435.0]	بازه برای دسته اول (20618.7-425435.0)
912	تعداد مقادیر در دسته اول
[<=830251.4]	بازه برای دسته دوم (425435.0-830251.4)
42	تعداد مقادیر در دسته دوم
[<=1235067.7]	بازه برای دسته سوم (830251.4-1235067.7)
17	تعداد مقادیر در دسته سوم
byte / sec	واحدهای پایه برای این معیار
.TE
.SH "فایل‌ها (FILES)"
.TP 5
.I $PCP_VAR_DIR/pmns/*
فایل‌های مشخصات پیش‌فرض PMNS
.TP
.I $PCP_LOG_DIR/pmlogger/<hostname>
دایرکتوری پیش‌فرض برای بایگانی‌های PCP شامل مقادیر معیارهای کارایی جمع‌آوری‌شده از میزبان
.IR <hostname> .
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای تعیین پارامتریک نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP می‌تواند برای تعیین یک فایل پیکربندی جایگزین، همان‌طور که در \fBpcp.conf\fP(5) توصیف شده است، استفاده شود.
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینه
.B \-D
یا
.B \-\دebug
خروجی تشخیصی بیشتری را در
.I stderr
جهت کمک به ریشه‌یابی و تفکیک خطاها فعال می‌کند، هرچند این اطلاعات گاهی مبهم است و در درجه اول به‌منظور راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی.
.I debug
فهرستی از گزینه‌های اشکال‌زدایی جدا شده با کاما است؛ از
.BR pmdbg (1)
همراه با گزینه
.B \-l
برای دریافت فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید.
.PP
گزینه‌های اشکال‌زدایی مختص
.B pmlogsummary
عبارتند از:
.TS
box;
lf(B) | lf(B)
lf(B) | lxf(R) .
گزینه	توضیحات
_
appl0	T{
.ad l
گزارش معیارهای موجود در بایگانی، معیارهای انتخاب‌شده، مقادیر نمونه‌های معیار، رکوردهای نشانه‌گذاری (mark)، آغاز تکرار دوم
T}
_
appl1	T{
.ad l
جزئیات دور زدن شمارنده‌ها (counter wrap)، داده‌های خام برای مقادیر اکسترمم و میانگین‌ها
T}
_
appl2	T{
.ad l
ردیابی مقادیر بیشینه و کمینه
T}
.TE.SH "همچنین ببینید (SEE ALSO)"
.BR PCPIntro (1)،
.BR pmchart (1)،
.BR pmdumptext (1)،
.BR pmlogextract (1)،
.BR pmlogger (1)،
.BR pmrep (1)،
.BR pmval (1)،
.BR PMAPI (3)،
.BR pmUnitsStr (3)
و
.BR PMNS (5).

.\" control lines for scripts/man-spell
.\" +ok+ aN blmMy {from command line options in examples}
.\" +ok+ csv {from .csv suffix} xpi {from network interface xpiN}