'\" t
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\" Copyright (c) 2015-2016,2018-2020 Red Hat.
.\"
.\" 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 PMIE 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmie\f1 \- موتور استنتاج برای معیارهای کارایی
.SH "خلاصه دستور (SYNOPSIS)"
\f3pmie\f1
[\f3\-bCdeFfPqvVWxXz?\f1]
[\f3\-a\f1 \f2archive\f1]
[\f3\-A\f1 \f2align\f1]
[\f3\-c\f1 \f2config\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-h\f1 \f2host\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-m\f1 \f2note\f1]
[\f3\-j\f1 \f2stompfile\f1]
[\f3\-n\f1 \f2pmnsfile\f1]
[\f3\-o\f1 \f2format\f1]
[\f3\-O\f1 \f2offset\f1]
[\f3\-S\f1 \f2starttime\f1]
[\f3\-t\f1 \f2interval\f1]
[\f3\-T\f1 \f2endtime\f1]
[\f3\-U\f1 \f2username\f1]
[\f3\-Z\f1 \f2timezone\f1]
[\f2filename ...\f1]
.SH "توضیحات (DESCRIPTION)"
دستور
.B pmie
مجموعه‌ای از عبارت‌های حسابی، منطقی و قواعد را جهت ارزیابی در بسامدهای مشخص می‌پذیرد.
داده‌های پایه برای این عبارت‌ها شامل مقادیر معیارهای کارایی هستند که به صورت بلادرنگ از هر میزبانی که دیمن جمع‌آوری معیارهای کارایی (PMCD) را اجرا می‌کند، دریافت می‌شوند، یا از داده‌های پیشین بایگانی‌های Performance Co-Pilot (PCP) به دست می‌آیند.
.PP
علاوه بر محاسبهٔ مقادیر حسابی و منطقی،
.B pmie
می‌تواند در پاسخ به شرایط مشخص‌شده، اقداماتی (مانند هشدارهای بالانشین، نوشتن پیام در گزارش‌های سیستم و اجرای برنامه‌ها) را اجرا کند.
چنین اقداماتی در شناسایی، پایش و اصلاح مشکلات مرتبط با کارایی بسیار سودمند هستند.
.PP
عبارت‌های مورد ارزیابی از فایل‌های پیکربندی که توسط یک یا چند آرگومان
.I filename
مشخص شده‌اند، خوانده می‌شوند.
در صورت عدم وجود هرگونه
.IR filename ،
عبارت‌ها از ورودی استاندارد خوانده خواهند شد.
.PP
خروجی
.B pmie
به صورت زیر به خروجی استاندارد و خطای استاندارد هدایت می‌شود:
.TP 5
.B stdout
مقادیر عبارت‌های چاپ‌شده در حالت پرگو (verbose) با گزینهٔ
.B \-v
و خروجی اقدامات
.BR print .
.TP
.B stderr
پیام‌های خطا و هشدار مربوط به هرگونه ایراد نحوی یا معنایی در حین تجزیهٔ عبارت، و هرگونه مشکل در معناداری یا در دسترس بودن معیارهای کارایی هنگام ارزیابی عبارت.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمان موجود عبارتند از:
.TP 5
\fB\-a\fR \fIarchive\fR, \fB\-\-archive\fR=\fIarchive\fR
آرگومان
.IR archive ،
که فهرستی از نام‌های جداشده با کاما است و هر یک از آن‌ها می‌تواند نام پایهٔ یک بایگانی یا نام دایرکتوری شامل یک یا چند بایگانی ایجاد شده توسط
.BR pmlogger (1)
باشد.
تکرار چندبارهٔ پرچم
.B \-a
در خط فرمان برای تعیین فهرستی از مجموعه‌های بایگانی مجاز است.
در این حالت، لازم است که برای هر میزبان تنها یک مجموعه از بایگانی‌ها وجود داشته باشد.
همچنین، هر نام میزبان صریحی که در یک عبارت
.B pmie
آمده است باید با نام میزبان ثبت‌شده در یکی از برچسب‌های بایگانی مطابقت داشته باشد.
در صورت وجود چندین مجموعه بایگانی، برچسب‌های زمانی ثبت‌شده در بایگانی‌ها برای تضمین سازگاری زمانی به کار می‌روند.
.TP
\fB\-A\fR \fIalign\fR, \fB\-\-align\fR=\fIalign\fR
بازهٔ زمانی اولیه را مجبور می‌کند تا بر مرز یک واحد زمانی طبیعی
.IR align
تراز شود.
برای شرح کامل نحو
.IR align
به
.BR PCPIntro (1)
مراجعه کنید.
.TP
\fB\-b\fR, \fB\-\-buffer\fR
خروجی به صورت سطری بافر خواهد شد و خروجی استاندارد به خطای استاندارد متصل می‌شود.
این گزینه بیشترین کاربرد را برای اجرای پس‌زمینه در ترکیب با گزینهٔ
.B \-l
دارد.
گزینهٔ
.B \-b
همواره برای نمونه‌های
.B pmie
که از طریق
.BR pmie_check (1)
راه‌اندازی می‌شوند، استفاده می‌شود.
.TP
\fB\-c\fR \fIconfig\fR, \fB\-\-config\fR=\fIconfig\fR
یک جایگزین برای مشخص کردن
.I filename
در انتهای خط فرمان.
.TP
\fB\-C\fR, \fB\-\-check\fR
فایل(های) پیکربندی را تجزیه کرده و پیش از انجام هرگونه ارزیابی خارج می‌شود.
هرگونه خطا در فایل پیکربندی گزارش خواهد شد.
.TP
\fB\-d\fR, \fB\-\-interact\fR
به طور معمول
.B pmie
به عنوان یک فرایند غیرتعاملی برای پایش و مدیریت کارایی یک یا چند میزبان اجرا می‌شود.
با این حال، با مشخص کردن پرچم
.BR \-d ،
اجرا به صورت تعاملی درآمده و منویی از گزینه‌ها به کاربر ارائه می‌شود.
حالت تعاملی عمدتاً برای اشکال‌زدایی عبارت‌های جدید سودمند است.
.TP
\fB\-e\fR, \fB\-\-timestamp\fR
هنگامی که به همراه
.BR \-V ،
.B \-v
یا
.B \-W
استفاده شود، این گزینه برچسب‌های زمانی را وادار می‌کند تا همراه با هر عبارت گزارش شوند.
برچسب‌های زمانی در قالب
.BR ctime (3)
بوده، درون پرانتز قرار دارند و پس از نام عبارت و پیش از مقدار عبارت ظاهر می‌شوند؛ مانند:
.nf
	expr_1 (Tue Feb  6 19:55:10 2001): 12
.fi
.TP
\fB\-f\fR, \fB\-\-foreground\fR
اگر گزینهٔ
.B \-l
مشخص شده باشد و گزینهٔ
.B \-a
وجود نداشته باشد (یعنی پایش بلادرنگ)،
.B pmie
به عنوان یک دیمن در پس‌زمینه اجرا می‌شود
(در سایر موارد، پیش‌فرض اجرای پیش‌زمینه است).
گزینه‌های
.B \-f
(و
.BR \-F ،
پایین را ببینید)
.B pmie
را وادار می‌کنند تا بدون وابستگی به هر گزینهٔ دیگری، در پیش‌زمینه اجرا شود.
.TP
\fB\-F\fR, \fB\-\-systemd\fR
همانند
.BR \-f ،
گزینهٔ
.B \-F
نیز
.B pmie
را در پیش‌زمینه اجرا می‌کند، اما برخی کارهای مدیریتی داخلی را نیز انجام می‌دهد
(مانند ایجاد یک فایل pid، تغییر شناسهٔ کاربر و اطلاع‌رسانی به
.BR systemd (1)
هنگامی که
.B pmie
راه‌اندازی شده یا در حال خاموش شدن است).
این گزینه برای مواردی در نظر گرفته شده که
.B pmie
توسط
.BR systemd (1)
راه‌اندازی می‌شود و تبدیل به دیمن شدن از قبل انجام گرفته است.
گزینه‌های
.B \-f
و
.B \-F
مانعة‌الجمع هستند.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
به طور پیش‌فرض داده‌های کارایی از میزبان محلی (در حالت بلادرنگ) یا از میزبان نخستین مجموعه بایگانیِ نام‌برده در خط فرمان (در حالت بایگانی) دریافت می‌شوند.
آرگومان \f2host\f1 این پیش‌فرض را لغو می‌کند.
این گزینه میزبان‌هایی را که به طور صریح در عبارت‌های مورد ارزیابی نام برده شده‌اند، لغو نمی‌کند.
آرگومان \f2host\f1 به عنوان مشخصات اتصال برای \f2pmNewContext\f1 تفسیر می‌شود، و بعداً به منظور گزارش‌دهی به نام میزبان اعلام‌شده توسط pmcd دوردست نگاشت می‌گردد.
همچنین مقایسهٔ جایگزینی‌های %h در برابر %c را در رشته‌های اقدام قواعد در ادامه ببینید..TP
\fB\-j\fR \fIfile\fR
پیکربندی جایگزین پروتکل STOMP از
.IR stompfile
بارگیری می‌شود.
اگر از این گزینه استفاده نشود، و کنش
.I stomp
در هر قاعده‌ای به کار رفته باشد، از مکان پیش‌فرض
.I $PCP_SYSCONF_DIR/pmie/config/stomp
استفاده خواهد شد.
.TP
\fB\-l\fR \fIlogfile\fR, \fB\-\-logfile\fR=\fIlogfile\fR
خطای استاندارد به
.IR logfile
ارسال می‌شود.
.TP
\fB\-m\fR \fInote\fR, \fB\-\-note\fR=\fInote\fR
برای نشان دادن این‌که
.B pmie
از کجا اجرا شده است به کار می‌رود؛ برای مثال \c
.BR pmie_check (1)
و
.BR pmie_daily (1)
از
.B "\-m pmie_check"
استفاده می‌کنند و این مورد توسط
.B pmie
برای تشخیص این‌که در صورت تغییر نام میزبان PMCD به راه‌اندازی مجدد نیاز است یا خیر، استفاده می‌شود، همان‌طور که در بخش
HOSTNAME CHANGES
در زیر توضیح داده شده است.
.TP
\fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR
یک فضای نام معیارهای کارایی (PMNS) جایگزین از فایل
.IR pmnsfile
بارگیری می‌شود.
.TP
\fB\-o\fR \fIformat\fR, \fB\-\-format\fR=\fIformat\fR
هنگام پردازش داده‌های کارایی از یک بایگانی، گزینه
.B \-o
می‌تواند برای تعیین یک
.I format
(قالب) خروجی جایگزین در زمان اجرای کنش یک قاعده استفاده شود.
برای شرح چگونگی ساخت
.I format
خروجی، بخش
.B "DIFFERENCES IN HOST AND ARCHIVE MODES"
را ببینید.
.TP
\fB\-O\fR \fIorigin\fR, \fB\-\-origin\fR=\fIorigin\fR
مبدأ (\fIorigin\fP) پنجره زمانی را مشخص می‌کند.
برای شرح کامل این گزینه،
.BR PCPIntro (1)
را ببینید.
.TP
\fB\-P\fR, \fB\-\-primary\fR
این نمونه را به عنوان نمونه اصلی
.B pmie
برای یک میزبان مشخص می‌کند.
برای جزئیات بیشتر بخش «AUTOMATIC RESTART» را در زیر ببینید.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
پیام‌های تشخیصی را که به‌طور پیش‌فرض در خروجی استاندارد چاپ می‌شوند سرکوب می‌کند؛ به‌ویژه پیام "evaluator exiting" زیرا می‌تواند اسکریپت‌ها را سردرگم کند.
.TP
\fB\-S\fR \fIstarttime\fR, \fB\-\-start\fR=\fIstarttime\fR
زمان شروع (\fIstarttime\fP) پنجره زمانی را مشخص می‌کند.
برای شرح کامل این گزینه،
.BR PCPIntro (1)
را ببینید.
.TP
\fB\-t\fR \fIinterval\fR, \fB\-\-interval\fR=\fIinterval\fR
آرگومان
.I interval
از نحو توصیف‌شده در
.BR PCPIntro (1)
پیروی می‌کند و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد (واحد ضمنی در این حالت ثانیه است).
این مقدار برای تعیین فاصله نمونه‌برداری عباراتی به کار می‌رود که فاصله نمونه‌برداری خود را صراحتاً با استفاده از متغیر
.B pmie
با نام \f(CRdelta\f1 (توضیح‌داده‌شده در زیر) تعیین نکرده‌اند.
مقدار پیش‌فرض 10.0 ثانیه است.
.TP
\fB\-T\fR \fIendtime\fR, \fB\-\-finish\fR=\fIendtime\fR
زمان پایان (\fIendtime\fP) پنجره زمانی را مشخص می‌کند.
برای شرح کامل این گزینه،
.BR PCPIntro (1)
را ببینید.
.TP
\fB\-U\fR \fIusername\fR, \fB\-\-username\fR=\fIusername\fR
حساب کاربری که
.B pmie
تحت آن اجرا می‌شود.
برای استفاده تعاملی، پیش‌فرض حساب کاربری فعلی است.
هنگام اجرا به عنوان یک دیمن، در نسخه‌های فعلی PCP از حساب کاربری بدون امتیاز "pcp" استفاده می‌شود، اما در نسخه‌های قدیمی‌تر، حساب مدیر سیستم ("root") به‌طور پیش‌فرض استفاده می‌شد.
.TP
\fB\-v\fR
مگر این‌که یکی از گزینه‌های پرگویی
.BR \-V ،
.B \-v
یا
.B \-W
در خط فرمان مشخص شود، عبارات در سکوت ارزیابی می‌شوند و تنها خروجی، حاصل از اجرای کنش‌ها خواهد بود.
در حالت پرگو که با پرچم
.B \-v
مشخص می‌شود، مقدار هر عبارت هنگام ارزیابی چاپ می‌شود.
مقادیر در واحدهای استاندارد (canonical) هستند؛
بایت در بُعد «فضا»، ثانیه در بُعد «زمان»
و رخدادها در بُعد «شمارش».
برای جزئیات بُعدهای پشتیبانی‌شده و سازوکارهای مقیاس‌بندی معیارهای کارایی،
.BR pmLookupDesc (3)
را ببینید.
حالت پرگو برای نظارت بر مقدار عبارات مشخص، ارزیابی معیارهای کارایی مشتق‌شده، انتقال این مقادیر به ابزارهای دیگر برای پردازش بیشتر و اشکال‌زدایی عبارات جدید مفید است.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
این گزینه اثری مشابه گزینه
.B \-v
دارد، با این تفاوت که علاوه بر مقادیر عبارت، نام میزبان و نمونه (در صورت وجود) نیز چاپ می‌شوند.
.TP
\fB\-W\fR
این گزینه اثری مشابه گزینه
.B \-V
توضیح‌داده‌شده در بالا دارد، با این تفاوت که برای عبارات بولی، تنها آن دسته از نام‌ها و مقادیری که عبارت را درست (true) می‌کنند چاپ می‌شوند.
این‌ها همان نام‌ها و مقادیری هستند که مانند مقیدسازی‌های %h، %i، %c و %v در دسترس کنش‌های قاعده قرار دارند، همان‌طور که در زیر شرح داده شده است.
.TP
\fB\-x\fR, \fB\-\-secret\-agent\fR
اجرا در حالت عامل دامنه (domain agent).
این حالت در محصول Performance Co-Pilot برای به‌دست آوردن مقادیر معیارهای خلاصه‌شده به کار می‌رود؛ ببینید:
.BR pmdasummary (1).
در این حالت تنها قابلیت‌های محدودی در دسترس است
(از عبارت‌های دارای کنش
.B نمی‌توان
استفاده کرد).
.TP
\fB\-X\fR, \fB\-\-secret\-applet\fR
اجرا در حالت اپلت مخفی (کلاینت سبک).
.TP
\fB\-z\fR, \fB\-\-hostzone\fR
تغییر منطقه زمانی گزارش‌دهی به منطقه زمانی میزبانی که منبع معیارهای کارایی است، همان‌طور که از طریق گزینه
.B \-h
یا اولین مجموعه مشخص‌شده از بایگانی‌ها (همان‌طور که در بالا برای گزینه
.B \-a
توضیح داده شد) مشخص شده است.
.TP
\fB\-Z\fR \fItimezone\fR, \fB\-\-timezone\fR=\fItimezone\fR
تغییر منطقه زمانی گزارش‌دهی به
.I timezone
در قالب متغیر محیطی
.B TZ
همان‌طور که در
.BR environ (7)
توضیح داده شده است.
.TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام راهنمای استفاده و خروج..SH "مثال‌ها (EXAMPLES)"
عبارت‌های نمونه‌ی زیر برخی از قابلیت‌های موتور استنتاج را نشان می‌دهند.
.PP
دایرکتوری
.I $PCP_DEMOS_DIR/pmie
شامل چندین نمونه‌ی حاشیه‌نویسی‌شده‌ی دیگر از عبارت‌های
.B pmie
است.
.PP
متغیر
.ft CR
delta
.ft 1
بسامد ارزیابی عبارت را کنترل می‌کند.
مشخص کنید که عبارت‌های بعدی تا اطلاع ثانوی، هر یک ثانیه ارزیابی شوند:
.PP
.ft CR
.nf
.in +0.5i
delta = 1 sec;
.in
.fi
.ft 1
.PP
اگر نرخ کل تعویض زمینه (context switch) به ازای هر پردازنده از ۱۰۰۰۰ در ثانیه فراتر رود، یک اعلان هشدار نمایش بده:
.PP
.ft CR
.nf
.in +0.5i
kernel.all.pswitch / hinv.ncpu > 10000 count/sec
-> alarm "high context switch rate %v";
.in
.fi
.ft 1
.PP
اگر نرخ بالای تعویض زمینه برای ۱۰ نمونه‌ی متوالی پایدار بماند، برنامهٔ
.BR top (1)
را در یک پنجره‌ی
.BR xterm (1)
برای پایش فرایندها اجرا کن، اما این کار را حداکثر هر ۵ دقیقه یک بار انجام بده:
.PP
.ft CR
.nf
.in +0.5i
all_sample (
    kernel.all.pswitch @0..9 > 10 Kcount/sec * hinv.ncpu
) -> shell 5 min "xterm \-e 'top'";
.in
.fi
.ft 1
.PP
قاعده‌های زیر هر ۲۰ ثانیه یک بار ارزیابی می‌شوند:
.PP
.ft CR
.nf
.in +0.5i
delta = 20 sec;
.in
.fi
.ft 1
.PP
اگر هر دیسکی بیش از ۶۰ عملیات I/O در ثانیه انجام می‌دهد، پیامی مبنی بر شناسایی دیسک مشغول در خروجی استاندارد چاپ کن و
.BR dkvis (1)
را اجرا کن:
.PP
.ft CR
.nf
.in +0.5i
some_inst (
    disk.dev.total > 60 count/sec
) -> print "busy disks:" " %i" &
     shell 5 min "dkvis";
.in
.fi
.ft 1
.PP
قاعدهٔ قبلی را طوری اصلاح کنید که تنها بین ساعت‌های ۹ صبح تا ۵ بعدازظهر اعمال شود و نیاز باشد ۳ نمونه از ۴ نمونه‌ی متوالی پیش از اجرای عمل، از آستانه فراتر رفته باشند:
.PP
.ft CR
.nf
.in +0.5i
$hour >= 9 && $hour <= 17 &&
some_inst (
  75 %_sample (
    disk.dev.total @0..3 > 60 count/sec
  )
) -> print "disks busy for 20 sec:" " [%h]%i";
.in
.fi
.ft 1
.PP
دو قاعدهٔ زیر هر ۱۰ دقیقه یک بار ارزیابی می‌شوند:
.PP
.ft CR
.nf
.in +0.5i
delta = 10 min;
.in
.fi
.ft 1
.PP
اگر سیستم‌فایل / یا /usr بیش از ۹۵٪ پر شده باشد، یک اعلان هشدار بازشو نمایش بده، اما در صورتی که طی ۴ ساعت گذشته نمایش داده شده باشد، از نمایش مجدد خودداری کن:
.PP
.ft CR
.nf
.in +0.5i
filesys.free #'/dev/root' /
    filesys.capacity #'/dev/root' < 0.05
-> alarm 4 hour "root filesystem (almost) full";

filesys.free #'/dev/usr' /
    filesys.capacity #'/dev/usr' < 0.05
-> alarm 4 hour "/usr filesystem (almost) full";
.in
.fi
.ft 1
.PP
قاعدهٔ زیر به سیستمی نیاز دارد که از معیارهای lmsensors پشتیبانی کند.
اگر دمای محیط دستگاه در یک بازه زمانی ۱۰ دقیقه‌ای بیش از ۲ درجه افزایش یابد، یک ورودی در گزارش سیستم ثبت کن:
.PP
.ft CR
.nf
.in +0.5i
lmsensors.coretemp_isa.temp1 @0 - lmsensors.coretemp_isa.temp1 @1 > 2
-> alarm "temperature rising fast" &
   syslog "machine room temperature rise alarm";
.in
.fi
.ft 1
.PP
و یک مورد جالب اگر با پایگاه دادهٔ Oracle خود مشکلات کارایی دارید:
.PP
.ft CR
.nf
.in +0.5i
// back to 30sec evaluations
delta = 30 sec;
sid = "ptg1";		# $ORACLE_SID setting
lid = "223";		# latch ID from v$latch
lru = "#'$sid/$lid cache buffers lru chain'";
host = ":moomba.melbourne.sgi.com";
gets = "oracle.latch.gets $host $lru";
total = "oracle.latch.gets $host $lru +
         oracle.latch.misses $host $lru +
         oracle.latch.immisses $host $lru";

$total > 100 && $gets / $total < 0.2
-> alarm "high lru latch contention in database $sid";
.in
.fi
.ft 1
.PP
مجموعه قواعد \f(CBruleset\fR زیر بسته به در دسترس بودن و مقدار میانگین بار (load average) ۱ دقیقه‌ای، دقیقاً یک پیام صادر خواهد کرد.
.PP
.ft CR
.nf
.in +0.5i
delta = 1 minute;
ruleset
     kernel.all.load #'1 minute' > 10 * hinv.ncpu ->
         print "extreme load average %v"
else kernel.all.load #'1 minute' > 2 * hinv.ncpu ->
         print "moderate load average %v"
unknown ->
         print "load average unavailable"
otherwise ->
         print "load average OK"
;
.in
.fi
.ft 1
.PP
قاعدهٔ زیر زمانی که یک سیستم‌فایل بیش از ۷۵٪ پر شده باشد و با سرعتی پر شود که در صورت تداوم، در کمتر از ۳۰ دقیقه به‌طور ۱۰۰٪ پر خواهد شد، پیامی صادر می‌کند.
.PP
.ft CR
.nf
.in +0.5i
some_inst (
    100 * filesys.used / filesys.capacity > 75 &&
    filesys.used + 30min * (rate filesys.used) > filesys.capacity
) -> print "filesystem will be full within 30 mins:" " %i";
.in
.fi
.ft 1.PP
اگر معیار \f(CRmypmda.errors\fP خطاها را بشمارد، آن‌گاه قانون زیر در صورتی که نرخ خطاها از ۱ در ثانیه فراتر رود، به شرطی که تعداد خطاها کمتر از ۱۰۰ باشد پیامی صادر خواهد کرد.
.PP
.ft CR
.nf
.in +0.5i
mypmda.errors > 1 && instant mypmda.errors < 100
-> print "high error rate: %v";
.in
.fi
.ft 1
.SH "شروع سریع (QUICK START)"
زبان مشخصات
.B pmie
قدرتمند و گسترده است.
.PP
برای سرعت بخشیدن به توسعهٔ سریع قوانین
.BR pmie ،
ابزار
.BR pmieconf (1)
امکانی را برای ایجاد یک فایل پیکربندی
.B pmie
از مجموعه‌ای از قوانین تعمیم‌یافتهٔ
.B pmie
فراهم می‌کند.
مجموعه قوانین ارائه‌شده طیف گسترده‌ای از سناریوهای کارایی را پوشش می‌دهد.
.PP
کتاب
.I "Performance Co-Pilot User's and Administrator's Guide"
فصلی تفصیلی به سبک آموزشی ارائه می‌دهد که
.B pmie
را پوشش می‌دهد.
.SH "نحو عبارات (EXPRESSION SYNTAX)"
این توصیف مختصر و غیررسمی است.
برای توضیحات جامع‌تر به
.I "Performance Co-Pilot User's and Administrator's Guide"
مراجعه کنید.
.PP
یک مشخصهٔ
.B pmie
دنباله‌ای از عبارات است که با نقطه‌ویرگول خاتمه می‌یابند.
.PP
توالی «//» یک توضیح (comment) را آغاز می‌کند و تمام متن از آن نقطه تا انتهای خط ورودی جاری نادیده گرفته خواهد شد.
.PP
عملگرهای پایه بر اساس عملگرهای حسابی، رابطه‌ای و بولیِ زبان برنامه‌نویسی C مدل‌سازی شده‌اند.
قوانین اولویت همان‌طور که انتظار می‌رود عمل می‌کنند، اگرچه استفاده از پرانتزها برای افزایش خوانایی و رفع ابهام توصیه می‌شود.
.PP
عملوندها نام‌های معیارهای کارایی
(ببینید
.BR PMNS (5))
و ثابت‌های لفظی معمولی هستند.
.PP
عملوندهای شامل معیارهای کارایی ممکن است در نتیجهٔ شمارش در ابعاد
.BR hosts ،
.B instances
و
.BR time ،
مجموعه‌ای از مقادیر را تولید کنند.
توصیف‌کننده‌های خاصی ممکن است پس از نام معیار کارایی بیایند تا شمارش را در هر بعد تعریف کنند.
برای مثال،
.PP
.in +4n
.ft CR
kernel.percpu.cpu.user :foo :bar #cpu0 @0..2
.ft R
.in
.PP
۶ مقدار متناظر با زمان سپری‌شده در اجرای حالت کاربر (user mode) روی CPU 0 در میزبان‌های «foo» و «bar» در طول ۳ نمونهٔ متوالی آخر را تعریف می‌کند.
تفسیر پیش‌فرض در نبود توصیف‌کننده‌های
.B :
(میزبان)،
.B #
(نمونه) و
.B @
(زمان)، تمامی نمونه‌ها در تازه‌ترین زمان نمونه‌گیری برای منبع پیش‌فرض معیارهای کارایی PCP است.
.PP
نام‌های میزبان و نمونه که از قواعد متغیرها در زبان‌های برنامه‌نویسی پیروی نمی‌کنند (یعنی حروف الفبا که اختیاری با نویسه‌های حرفی-عددی دنبال می‌شوند)، باید در علامت‌های نقل‌قول تکی قرار گیرند.
.PP
ارزیابی عبارات از اصل «کمترین شگفتی» پیروی می‌کند.
در مواردی که معیارهای کارایی معنای شمارنده (counter) دارند،
.B pmie
به‌طور خودکار آن‌ها را بر اساس نمونه‌های متوالی و بازهٔ زمانی میان این نمونه‌ها به یک نرخ (rate) تبدیل می‌کند.
تمام عبارات عددی با دقت مضاعف (double precision) ارزیابی می‌شوند و در صورت لزوم، به‌طور خودکار به واحدهای استاندارد «bytes»، «seconds» و «counts» مقیاس‌بندی می‌شوند.
توجه داشته باشید معیارهایی که بر روی واحدهای اضافه‌ای مانند «temperature» یا «voltage» تعریف شده‌اند، به واحدهای استاندارد مقیاس‌بندی نمی‌شوند.
.PP
یک
.B rule
(قانون) شکل خاصی از عبارت است که یک شرط یا عبارت منطقی، یک عملگر ویژه (\c
.BR \-> )
و اقداماتی را مشخص می‌کند که در صورت برقرار بودن شرط، باید انجام شوند.
.PP
جدول زیر عملگرهای پایهٔ
.B pmie
را خلاصه می‌کند:
.PP
.ne 12v
.TS
box,center;
c | c
lf(CR) | l.
عملگرها	توضیحات
_
+ \- * /	حسابی
< <= == >= > !=	رابطه‌ای (مقایسهٔ مقدار)
! && ||	بولی
->	قانون (Rule)
\f(CBrising\fR	بولی، گذار از نادرست به درست
\f(CBfalling\fR	بولی، گذار از درست به نادرست
\f(CBrate\fR	تبدیل صریح نرخ (به‌ندرت لازم است)
\f(CBinstant\fR	بدون تبدیل خودکار نرخ (به‌ندرت لازم است)
.TE
.PP
تمام عملگرها برای عملوندها و عبارات دارای مقدار عددی پشتیبانی می‌شوند.
برای عملوندهای دارای مقدار رشته‌ای، یعنی ثابت‌های لفظی رشته‌ای محصور در علامت نقل‌قول دوتایی یا معیارهایی با نوع دادهٔ رشته (\c
.BR PM_TYPE_STRING )،
.B فقط
عملگرهای
.B ==
و
.B !=
پشتیبانی می‌شوند.
.PP
عملگرهای \f(CBrate\fP و \f(CBinstant\fP معکوس منطقی یکدیگر هستند، بنابراین عبارت حسابی \fIexpr\fP برابر با \f(CBrate instant\fP \fIexpr\fP است.
موارد مفیدتر شامل استفاده از \f(CBrate\fP به همراه معیاری است که شمارنده نیست تا نرخ تغییر در طول زمان تعیین شود، یا استفاده از \f(CBinstant\fP با معیاری که یک شمارنده است تا بررسی شود آیا مقدار فعلی بالاتر یا پایین‌تر از آستانه‌ای مشخص قرار دارد یا خیر.
.PP
عملگرهای تجمیعی (aggregate) ممکن است برای تجمیع یا خلاصه‌سازی در امتداد یک بعد از یک عبارت دارای مقادیر مجموعه‌ای به کار روند.
عملگرهای تجمیعی زیر از یک عبارت منطقی به یک عبارت منطقی با بعد پایین‌تر نگاشت انجام می‌دهند.
.PP
.ne 16v
.TS
box,center;
cw(2.4i) | c | cw(2.4i)
lf(CB) | l | l.
عملگرها	نوع	توضیحات
_
T{
some_inst
some_host
some_sample
T}	وجودی	T{
اگر دست‌کم یکی از اعضای مجموعه در بعد مرتبط درست باشد، نتیجه «درست» است
T}
_
T{
all_inst
all_host
all_sample
T}	عمومی	T{
اگر تمام اعضای مجموعه در بعد مرتبط درست باشند، نتیجه «درست» است
T}
_
T{
\f(CIN\f(CB%_inst
\f(CIN\f(CB%_host
\f(CIN\f(CB%_sample\fR
T}	درصدی	T{
اگر دست‌کم \fIN\fP درصد از اعضای مجموعه در بعد مرتبط درست باشند، نتیجه «درست» است
T}
.TE
.PP
عملگرهای نمونه‌ای (instantial) زیر را می‌توان برای فیلتر کردن یا محدود ساختن یک عبارت منطقی با مقادیر مجموعه‌ای، بر اساس تطابق عبارات باقاعده با نام‌های نمونه استفاده کرد.
عبارت منطقی باید مجموعه‌ای شامل بُعد نمونه‌ها باشد، و عبارت باقاعده از قالبی است که توسط
.BR egrep (1)
یا عبارات باقاعدهٔ گسترش‌یافتهٔ
.BR regcomp (3)
استفاده می‌شود.
.PP
.ne 12v
.TS
box,center;
c | cw(4i)
lf(CB) | l.
عملگرها	توضیحات
_
match_inst	T{
به ازای هر مقدار از عبارت منطقی که «درست» است، در صورتی که نام نمونهٔ مرتبط با عبارت باقاعده تطابق داشته باشد، نتیجه «درست» است؛ در غیر این صورت نتیجه «نادرست» خواهد بود.
T}
_
nomatch_inst	T{
به ازای هر مقدار از عبارت منطقی که «درست» است، در صورتی که نام نمونهٔ مرتبط با عبارت باقاعده تطابق \fBنداشته باشد\fP، نتیجه «درست» است؛ در غیر این صورت نتیجه «نادرست» خواهد بود.
T}
.TE.PP
برای نمونه، عبارت زیر برای دیسک‌های متصل به کنترل‌کننده‌های ۲ یا ۳ که بیش از ۲۰ عملیات در ثانیه انجام می‌دهند، \(lqدرست\(rq (true) خواهد بود:
.ft CR
.nf
.in +0.5i
match_inst "^dks[23]d" disk.dev.total > 20;
.in
.fi
.ft 1
.PP
عملگرهای تجمیعی (aggregate) زیر، یک عبارت محاسباتی را به یک عبارت محاسباتی با بُعد پایین‌تر نگاشت می‌کنند.
.PP
.ne 20v
.TS
box,center;
cw(2.4i) | c | cw(2.4i)
lf(CB) | l | l.
عملگرها	نوع	توضیحات
_
T{
min_inst
min_host
min_sample
T}	اکسترمم	T{
حداقل مقدار در میان تمام اعضای مجموعه در بُعد مربوطه
T}
_
T{
max_inst
max_host
max_sample
T}	اکسترمم	T{
حداکثر مقدار در میان تمام اعضای مجموعه در بُعد مربوطه
T}
_
T{
sum_inst
sum_host
sum_sample
T}	تجمیعی	T{
مجموع مقادیر در میان تمام اعضای مجموعه در بُعد مربوطه
T}
_
T{
avg_inst
avg_host
avg_sample
T}	تجمیعی	T{
میانگین مقادیر در میان تمام اعضای مجموعه در بُعد مربوطه
T}
.TE
.PP
عملگرهای تجمیعی \f(CRcount_inst\fR، \f(CRcount_host\fR و \f(CRcount_sample\fR با شمارش تعداد اعضای مجموعه‌ای که عبارت برای آن‌ها در بُعد مربوطه درست (true) است، یک عبارت منطقی را به یک عبارت محاسباتی با بُعد پایین‌تر نگاشت می‌کنند.
.PP
برای قواعد کنش (action rules)، کنش‌های زیر تعریف شده‌اند:
.TS
box,center;
c | c
lf(CB) | l.
عملگرها	توضیحات
_
alarm	ایجاد یک هشدار تصویری با \fBxconfirm\f1(1)
print	نمایش در خروجی استاندارد
shell	اجرا با \fBsh\fR(1)
stomp	ارسال یک پیام STOMP به یک سرور JMS
syslog	افزودن یک پیام به فایل لاگ سیستم
.TE
.PP
کنش‌های چندگانه را می‌توان با عملگرهای \f(CR&\fR و \f(CR|\fR از یکدیگر جدا کرد تا به ترتیب اجرای متوالی (هر دو کنش اجرا می‌شوند) و اجرای جایگزین (کنش دوم تنها در صورتی اجرا می‌شود که اجرای کنش اول وضعیت خطای غیرصفر بازگرداند) مشخص شوند.
.PP
آرگومان‌های کنش‌ها عبارتند از یک زمان سرکوب (suppression time) اختیاری، و سپس یک یا چند عبارت (یک رشته در این زمینه، یک عبارت محسوب می‌شود). رشته‌هایی که به عنوان آرگومان برای یک کنش ظاهر می‌شوند، می‌توانند شامل گزینش‌گرهای خاص زیر باشند که در زمان اجرای کنش جایگزین خواهند شد:
.TP 4n
\f(CB%h\fR
نام میزبان(هایی) که چپ‌ترین عبارت سطح بالا را در شرط درست (true) می‌کنند.
.TP 4n
\f(CB%c\fR
رشته(های) مشخصات اتصال یا فایل‌هایی برای یک ابزار PCP جهت دستیابی به میزبان‌ها یا بایگانی‌هایی که چپ‌ترین عبارت سطح بالا را در شرط درست (true) می‌کنند.
.TP
\f(CB%i\fR
نمونه(هایی) که چپ‌ترین عبارت سطح بالا را در شرط درست (true) می‌کنند.
.TP
\f(CB%v\fR
یک مقدار از چپ‌ترین عبارت سطح بالا در شرط، به ازای هر جفت میزبان و نمونه‌ای که شرط را درست (true) می‌کند.
.PP
توجه داشته باشید که بسط گزینش‌گرهای خاص با تکرار کل آرگومان برای هر اتصال یکتا به هر یک از گزینش‌گرهای خاص واجد شرایط انجام می‌شود.
برای نمونه، اگر قاعده‌ای برای میزبان
.B mumble
با نمونه‌های
.B grunt
و
.BR snort ،
و برای میزبان
.B fumble
با نمونهٔ
.B puff
درست باشد، آنگاه کنش
.ft CR
.nf
.in +0.5i
\&...
-> shell myscript "Warning: %h:%i busy ";
.in
.fi
.ft 1
دستور
.B myscript
را با رشته آرگومان "Warning: mumble:grunt busy Warning: mumble:snort busy Warning: fumble:puff busy" اجرا خواهد کرد.
.PP
در مقایسه، اگر کنش
.ft CR
.nf
.in +0.5i
\&...
-> shell myscript "Warning! busy:" " %h:%i";
.in
.fi
.ft 1
تحت همان شرایط اجرا می‌شد، آنگاه
.B myscript
با رشته آرگومان "Warning! busy: mumble:grunt mumble:snort fumble:puff" اجرا می‌شد.
.PP
معناشناسی بسط گزینش‌گرهای خاص منجر به یک الگوی استفاده رایج در یک کنش می‌شود، که در آن یک آرگومان ثابت است (شامل هیچ گزینش‌گر خاصی نیست)، آرگومان دوم شامل گزینش‌گرهای خاص مورد نظر با حداقل نویسه‌های جداکننده است، و یک آرگومان اختیاری سوم پس‌بندی ثابت را ارائه می‌دهد (مثلاً برای بستن نقل‌قول‌های آرگومان اول).
در صورت لزوم، پس‌پردازش (به عنوان مثال در
.BR myscript )
می‌تواند پیمایش لازم روی هر بسط یکتا از رشته‌ای که فقط شامل گزینش‌گرهای خاص است را فراهم کند.
.PP
برای شرط‌های پیچیده، اتصال‌ها به این گزینش‌گرها بدیهی نیست.
اکیداً توصیه می‌شود که هنگام توسعه قواعد،
.B pmie
در حالت اشکال‌زدایی (به ویژه با مشخص کردن گزینه خط فرمان
.BR \-W )
استفاده شود..SH "عبارت‌های بولی (BOOLEAN EXPRESSIONS)"
عبارت‌های
.B pmie
که دارای معناشناسی بولی هستند، برای نمونه
\f(CRfoo.bar > 10\fR
یا
\f(CBsome_inst\f(CR ( my.table < 0 )
.ft R
مقادیر \f(CBtrue\fR یا \f(CBfalse\fR یا \f(CBunknown\fR را می‌گیرند.
یک مقدار در صورتی \f(CBunknown\fR خواهد بود که یک یا چند مورد از مقادیر متریک‌های زیربنایی در دسترس نباشند، برای نمونه نتوان با
.BR pmcd (1)
روی میزبان ارتباط برقرار کرد، متریک در بایگانی PCP موجود نباشد، در حال حاضر هیچ مقداری در دسترس نباشد، مقادیر دریافت‌شده برای محاسبه مقداری با نرخ تبدیل‌شده ناکافی باشند، یا مقادیر دریافت‌شده برای نمونه‌برداری به تعداد مورد نیاز در دامنه زمانی کافی نباشند.
.PP
عملگرهای بولی هنگام ترکیب مقادیری که شامل \f(CBunknown\fR هستند، از قواعد متداول منطق کلینی (شناخته‌شده به عنوان منطق سه‌ارزشی) پیروی می‌کنند:
.TS
box,center;
c s|c s s
^ s|c s s
^ s|c|c|c
c|c|c|c|c
^|c|c|c|c.
A \f(CBand\fR B	B
	_
	\f(CBtrue\fR	\f(CBfalse\fR	\f(CBunknown\fR
_
A	\f(CBtrue\fR	\f(CBtrue\fR	\f(CBfalse\fR	\f(CBunknown\fR
	_	_	_	_
	\f(CBfalse\fR	\f(CBfalse\fR	\f(CBfalse\fR	\f(CBfalse\fR
	_	_	_	_
	\f(CBunknown\fR	\f(CBunknown\fR	\f(CBfalse\fR	\f(CBunknown\fR
.TE
.TS
box,center;
c s|c s s
^ s|c s s
^ s|c|c|c
c|c|c|c|c
^|c|c|c|c.
A \f(CBor\fR B	B
	_
	\f(CBtrue\fR	\f(CBfalse\fR	\f(CBunknown\fR
_
A	\f(CBtrue\fR	\f(CBtrue\fR	\f(CBtrue\fR	\f(CBtrue\fR
	_	_	_	_
	\f(CBfalse\fR	\f(CBtrue\fR	\f(CBfalse\fR	\f(CBunknown\fR
	_	_	_	_
	\f(CBunknown\fR	\f(CBtrue\fR	\f(CBunknown\fR	\f(CBunknown\fR
.TE
.TS
box,center;
c|c.
A	\f(CBnot\fR A
_
\f(CBtrue\fR	\f(CBfalse\fR
_
\f(CBfalse\fR	\f(CBtrue\fR
_
\f(CBunknown\fR	\f(CBunknown\fR
.TE
.SH "مجموعه‌قوانین (RULESETS)"
بند \f(CBruleset\fR برای تعریف مجموعه‌ای از قوانین و کنش‌ها به کار می‌رود که به ترتیب ارزیابی می‌شوند تا زمانی که کنشی اجرا شود؛ در این مرحله، قوانین و کنش‌های باقیمانده نادیده گرفته می‌شوند تا زمانی که \f(CBruleset\fR دوباره برای ارزیابی زمان‌بندی گردد.
کلیدواژه \f(CBelse\fR برای جداسازی قوانین استفاده می‌شود.
پس از یک یا چند قانون عادی (شامل یک گزاره و یک کنش)، یک \f(CBruleset\fR می‌تواند شامل بند اختیاری
.br
.ti +0.5i
\f(CBunknown\fR -> action
.br
باشد، که به صورت اختیاری با بند
.br
.ti +0.5i
\f(CBotherwise\fR -> action
.br
دنبال می‌شود.
.PP
اگر همه گزاره‌ها در قوانین به \f(CBunknown\fR ارزیابی شوند و یک بند \f(CBunknown\fR مشخص شده باشد، کنش مرتبط با بند \f(CBunknown\fR اجرا خواهد شد.
.PP
اگر هیچ گزاره قانونی \f(CBtrue\fR نباشد و کنش \f(CBunknown\fR نیز یا مشخص نشده یا اجرا نشده باشد و یک بند \f(CBotherwise\fR مشخص شده باشد، کنش مرتبط با بند \f(CBotherwise\fR اجرا خواهد شد.
.SH "ضریب‌های مقیاس (SCALE FACTORS)"
ضریب‌های مقیاس را می‌توان به عبارت‌های حسابی افزود تا مقدار را به صورت خطی به واحدهای متعارف مقیاس‌بندی کنند.
ضریب‌های مقیاس ساده از این کلیدواژه‌ها ساخته می‌شوند:
\f(CBnanosecond\fR، \f(CBnanosec\fR، \f(CBnsec\f1،
\f(CBmicrosecond\fR، \f(CBmicrosec\fR، \f(CBusec\f1،
\f(CBmillisecond\fR، \f(CBmillisec\fR، \f(CBmsec\f1،
\f(CBsecond\fR، \f(CBsec\fR، \f(CBminute\fR، \f(CBmin\fR، \f(CBhour\f1،
\f(CBbyte\fR، \f(CBKbyte\fR، \f(CBMbyte\fR، \f(CBGbyte\fR، \f(CBTbyte\f1،
\f(CBcount\fR، \f(CBKcount\fR و \f(CBMcount\fR،
و عملگر \f(CR/\fR، برای نمونه \(lq\f(CBKbytes / hour\f1\(rq.
.PP
متریک‌های تعریف‌شده روی واحدهای فرعی مانند \(lqtemperature\(rq (دما) یا \(lqvoltage\(rq (ولتاژ) ممکن است تنوع بسیار زیادی از مقیاس‌های ممکن داشته باشند، اما در
.B pmie
پشتیبانی از کلیدواژه‌ها برای اعمال مقیاس وجود ندارد؛ بنابراین عبارت‌ها باید از مقیاس‌بندی صریح استفاده کنند، برای نمونه:
.br
.ti +0.5i
\f(CBthis.temp.celsius\fR >= (\f(CBother.temp.fahrenheit\fR - 32) * 5 / 9
.br
.SH "ماکروها (MACROS)"
ماکروها با استفاده از عبارت‌هایی به این شکل تعریف می‌شوند:
.PP
.in +0.5i
\fIname\fR = \fIconstexpr\f1;
.in
.PP
به طوری که
.I name
از قواعد معمول متغیرها در زبان‌های برنامه‌نویسی پیروی می‌کند، یعنی حروف الفبا که می‌تواند به صورت اختیاری با نویسه‌های الفبایی-عددی دنبال شود.
.I constexpr
باید یک عبارت ثابت باشد، چه یک رشته (درون دو نقل‌قول) یا یک عبارت حسابی که به صورت اختیاری با یک ضریب مقیاس دنبال می‌شود.
.PP
ماکروها زمانی بسط می‌یابند که نام آن‌ها همراه با پیشوند دلار (\f(CR$\fR) در یک عبارت ظاهر شود، و ماکروها ممکن است درون یک رشته
.I constexpr
به صورت تو در تو قرار گیرند.
.PP
نام‌های ماکروی رزروشده زیر پشتیبانی می‌شوند:
.TP 10n
\f(CBminute\f1
دقیقه کنونی از ساعت.
.TP
\f(CBhour\f1
ساعت کنونی از شبانه‌روز، در بازه 0 تا 23.
.TP
\f(CBday\f1
روز کنونی از ماه، در بازه 1 تا 31.
.TP
\f(CBmonth\f1
ماه کنونی از سال، در بازه 0 (ژانویه) تا 11 (دسامبر).
.TP
\f(CByear\f1
سال کنونی.
.TP
\f(CBday_of_week\f1
روز کنونی از هفته، در بازه 0 (یکشنبه) تا 6 (شنبه).
.TP
\f(CBdelta\f1
بازه نمونه‌برداری اعمال‌شده برای این عبارت.
.PP
تاریخ‌ها و زمان‌ها در منطقه زمانی گزارش‌دهی ارائه می‌شوند (توضیحات گزینه‌های خط فرمان
.B \-Z
و
.B \-z
در بالا را ببینید)..SH "راه‌اندازی مجدد خودکار (AUTOMATIC RESTART)"
اغلب مفید است که فرایندهای
.B pmie
هنگام راه‌اندازی (بوت) یا خاموش شدن میزبان محلی، یا زمانی که تشخیص داده می‌شود دیگر در حال اجرا نیستند (زمانی که بنا به دلایلی به‌طور غیرمنتظره خارج شده‌اند)، شروع و متوقف شوند.
برای جزئیات بیشتر در مورد خودکارسازی این فرایند به
.BR pmie_check (1)
مراجعه کنید.
.PP
به‌طور اختیاری، هر سامانه‌ای که
.BR pmcd (1)
را اجرا می‌کند می‌تواند برای اجرای یک نمونه «اصلی» (primary) از
.B pmie
نیز پیکربندی شود.
این نمونه از
.B pmie
توسط
.BR $PCP_RC_DIR/pmie
راه‌اندازی می‌شود و تحت تأثیر فایل‌های
.IR $PCP_SYSCONF_DIR/pmie/control ،
.IR $PCP_SYSCONF_DIR/pmie/control .d
(برای فعال یا غیرفعال کردن نمونه اصلی
.B pmie
از
.BR chkconfig (8)،
.BR systemctl (1)
یا دستورهای مشابه مختص پلتفرم استفاده کنید)
و
.I $PCP_VAR_DIR/config/pmie/config.default
(فایل پیکربندی اولیه پیش‌فرض برای
.B pmie
اصلی)
قرار می‌گیرد.
.PP
نمونه اصلی
.B pmie
با گزینه
.B \-P
مشخص می‌شود.
در هر سامانه حداکثر می‌تواند یک نمونه «اصلی»
.B pmie
وجود داشته باشد.
نمونه اصلی
.B pmie
(در صورت وجود) باید روی همان میزبانی اجرا شود که
.BR pmcd (1)
متصل به آن در حال اجراست (در صورت وجود)، بنابراین گزینه‌های
.B \-h
و
.B \-P
مانعة‌الجمع هستند.
.SH "پایش رویدادها (EVENT MONITORING)"
پایش سامانه‌های عملیاتی در یک مکان مرکزی امری رایج است.
به‌طور سنتی در سیستم‌های UNIX این کار توسط امکانات لاگ سیستم انجام می‌شده است \- نگاه کنید به
.BR logger (1)
و
.BR syslogd (1).
در Windows، ارتباط با گزارش وقایع سیستم (event log) توسط
.BR pcp-eventlog (1)
مدیریت می‌شود.
.PP
زمانی که قوانین از کنش
.I syslog
استفاده می‌کنند،
.B pmie
با این مدل سازگار می‌شود.
توجه داشته باشید که اگر رشته کنش با \-p (اولویت) و/یا \-t (برچسب) آغاز شود،
این موارد از رشته استخراج شده و به همان شیوه‌ای که در
.BR logger (1)
و
.BR pcp-eventlog (1)
آمده، پردازش می‌شوند.
.PP
با این حال، وجود دیگر چارچوب‌های پایش رویداد نیز متداول است که ممکن است بخواهید رویدادهای کارایی حاصل از
.B pmie
را در آن‌ها ادغام کنید.
اغلب می‌توانید از کنش
.I shell
برای ارسال رویدادها به این چارچوب‌ها استفاده کنید، زیرا معمولاً برنامه‌ای برای تزریق رویدادها از منابع خارجی به درون چارچوب خود ارائه می‌دهند.
.PP
گزینه پایانی، استفاده از کنش
.I stomp
(پروتکل Streaming Text Oriented Messaging Protocol) است که به
.B pmie
امکان می‌دهد به یک سرور مرکزی JMS (سیستم پیام‌رسانی جاوا) متصل شده و رویدادها را به تاپیک PMIE ارسال کند.
می‌توان ابزارهایی برای استخراج این پیام‌های متنی و نمایش آن‌ها به عوامل عملیات (از طریق پنجره‌های بازشو دسکتاپ و غیره) توسعه داد.
استفاده از کنش
.I stomp
نیازمند تنظیم یک فایل پیکربندی stomp است که مکان میزبان سرور JMS، شماره درگاه و نام کاربری/گذرواژه را مشخص می‌کند.
.PP
قالب این فایل به صورت زیر است:
.PP
.ft CR
.nf
.in +0.5i
host=messages.sgi.com   # this is the JMS server (required)
port=61616              # and its listening here (required)
timeout=2               # seconds to wait for server (optional)
username=joe            # (required)
password=j03ST0MP       # (required)
topic=PMIE              # JMS topic for pmie messages (optional)
.in
.fi
.ft 1
.PP
مقدار timeout مدت زمانی (به ثانیه) را مشخص می‌کند که
.B pmie
باید پس از ارسال پیام، منتظر تأیید دریافت از سوی سرور JMS بماند (همان‌طور که توسط پروتکل STOMP الزامی شده است).
توجه داشته باشید که هنگام راه‌اندازی،
.B pmie
به‌مدت نامحدود منتظر برقراری اتصال خواهد ماند و تا زمانی که آن اتصال اولیه برقرار نشود،
ارزیابی قوانین را آغاز نخواهد کرد.
اگر در حین اجرای
.B pmie
اتصال به سرور JMS در هر زمانی قطع شود،
.B pmie
در هر ارزیابی درست بعدی از یک قاعده دارای کنش
.IR stomp ،
برای اتصال مجدد تلاش خواهد کرد، اما نه بیشتر از یک بار در هر دقیقه.
این سازوکار برای جلوگیری از تشدید ازدحام در شبکه طراحی شده است.
در این وضعیت، که اتصال STOMP به سرور JMS قطع شده است، کنش
.I stomp
یک مقدار خطای غیرصفر را برمی‌گرداند..SH "تفاوت‌ها در حالت‌های میزبان و بایگانی (DIFFERENCES IN HOST AND ARCHIVE MODES)"
هنگام اجرا در حالت میزبان، بازه زمانی
\f(CBdelta\f1
برای هر قاعده، یک تأخیر بی‌درنگ (real-time) بین ارزیابی قواعد را تعیین می‌کند؛ بنابراین
.B pmie
بیشتر وقت خود را در خواب و در انتظار برای ارزیابی زمان‌بندی‌شده بعدی قواعد می‌گذراند.
.PP
هنگام اجرا در حالت بایگانی،
.B pmie
از بازه زمانی
\f(CBdelta\f1
برای هر قاعده استفاده می‌کند تا مشخص کند قواعد با چه تناوبی در برابر داده‌های بایگانی ارزیابی شوند؛
اما بر خلاف حالت میزبان، هیچ تأخیر بی‌درنگی وجود ندارد زیرا بایگانی با حداکثر سرعت ممکن \(lqبازپخش\(rq می‌شود.
.PP
در حالت بایگانی، زمانی که گزاره یک قاعده \f(CBtrue\fR ارزیابی شود، اقدام (action) تغییر می‌یابد؛ به طوری که به جای ارسال به
.I syslog
یا فعال‌سازی یک
.I alarm
دیداری یا اجرای یک دستور
.I shell
یا ارسال پیام
.IR stomp ،
ابزار
.B pmie
نام اقدام، برچسب زمانی برگرفته از بایگانی در هنگام \f(CBtrue\fR بودن گزاره راه‌انداز اقدام و تمام آرگومان‌هایی را که در حالت میزبان به اقدام واقعی ارسال می‌شدند، چاپ می‌کند.
.PP
برای مثال، با در نظر گرفتن قاعده:
.br
.in +0.5i
.ft CR
delta = 10 sec;
.br
kernel.all.nprocs > 10 * hinv.ncpu -> print "lotsaprocs:" " %v";
.ft 1
.in
هنگام اجرا در برابر یک بایگانی، خروجی به صورت زیر نمایش داده می‌شود:
.br
.ft CR
.in +0.5i
.nf
print Mon Sep  4 00:10:21 2017: lotsaprocs: 1292
print Mon Sep  4 00:10:31 2017: lotsaprocs: 1294
print Mon Sep  4 00:10:41 2017: lotsaprocs: 1291
\&...
.fi
.in
.ft 1
.PP
دلیل این امر آن است که بستری که اقدام قرار بود در آن اجرا شود (در حالت میزبان)، مربوط به زمانی در گذشته و احتمالاً روی میزبانی متفاوت بوده است (اگر بایگانی از یک میزبان جمع‌آوری شده باشد، اما
.B pmie
روی میزبان دیگری اجرا شود).
بنابراین، سرریز کردن
.I syslog
با پیام‌های گمراه‌کننده، یا ایجاد بهمنی از هشدارهای دیداری، یا انبوهی از پیام‌های STOMP، یا اجرای دستور پوسته‌ای که ممکن است حتی روی میزبانی که
.B pmie
روی آن اجرا می‌شود کار نکند، همگی نمونه‌هایی از «رفتارهای نامطلوب» هستند که باید از آن‌ها دوری کرد.
در عوض، خروجی به شکل متنی با قالبی منظم و مناسب برای پس‌پردازش به همراه مجموعه‌ای از فیلترها و ابزارهای تحلیل کارایی است.
.PP
قالب خروجی را می‌توان با استفاده از گزینه
.B \-o
تغییر داد؛ این گزینه شامل نویسه‌های عینی به همراه نشانه‌های تعبیه‌شده «فرامیدان» (meta-field) زیر است:
.TP 4n
\f(CB%a\fR
نام اقدام، مانند
.BR print ،
.BR syslog
و غیره.
.TP 4n
\f(CB%d\fR
تاریخ و زمان در قالب
.BR ctime (3)
در زمانی که اقدام اجرا می‌شد.
.TP 4n
\f(CB%f\fR
نام فایل پیکربندی شامل اقدامی که در حال اجرا است، و در غیر این صورت
.B <stdin>
چنانچه قواعد از ورودی استاندارد خوانده شده باشند.
.TP 4n
\f(CB%l\fR
شماره خط (تقریبی) در فایل پیکربندی برای اقدامی که در حال اجرا است.
.TP 4n
\f(CB%m\fR
بخش پیامِ اقدام.
.TP 4n
\f(CB%u\fR
تاریخ و زمانی که اقدام در آن اجرا می‌شد، در قالب گسترش‌یافته
.BR ctime (3)
همراه با دقت میکروثانیه‌ای برای زمان.
.TP 4n
\f(CB%%\fR
یک نویسه درصد واقعی (%).
.PP
قالب پیش‌فرض خروجی معادل یک
.I format
به صورت
.BR "%a %d: %m"
است.
.SH "سیگنال‌ها (SIGNALS)"
اگر سیگنال SIGHUP به
.B pmie
ارسال شود، فایل
.I logfile
بسته، پیوندزدایی (unlink) و مجدداً باز خواهد شد. این سازوکار توسط
.BR pmie_daily (1)
برای انجام چرخش شبانه گزارش‌ها به کار می‌رود.
.PP
بیشتر اوقات
.B pmie
در حالت خواب است و منتظر می‌ماند تا زمان ارزیابی مجموعه بعدی قواعد فرا برسد.
ارسال یک سیگنال SIGUSR1 به
.B pmie
باعث می‌شود جزئیات مربوط به ارزیابی مجموعه بعدی قواعد روی
.IR logfile
تخلیه شود؛ از جمله اینکه مدت خواب فعلی چقدر است و چه مقدار زمان باقی مانده است.
زمان‌بندی قواعد با این عمل تغییری نمی‌کند..SH "تغییرات نام میزبان (HOSTNAME CHANGES)"
نام میزبان PMCD که معیارها را به
.B pmie
ارائه می‌دهد، به چند روش استفاده می‌شود.
.PP
نام میزبان PMCD به‌طور داخلی برای مقداردهی به جایگزینی‌های %h در رشته‌های عملیات قوانین به کار می‌رود.
.PP
برای نمونه‌های
.B pmie
که از یک PMCD محلی استفاده می‌کنند و توسط
.BR pmie_check (1)
و
.BR pmie_daily (1)
(یا سرویس‌های
.BR systemd (1)
یا
.BR cron (8)
که از این اسکریپت‌ها استفاده می‌کنند) راه‌اندازی و مدیریت می‌شوند، نام میزبان محلی ممکن است برای ساخت نام دایرکتوری‌ای که لاگ‌های
.B pmie
یک میزبان در آن ذخیره می‌شوند نیز استفاده شود، مانند \c
.BR $PCP_LOG_DIR/pmie/\fI<hostname>\fB .
.PP
نام میزبان PMCD ممکن است هنگام راه‌اندازی سیستم در زمان گذار از یک نام میزبان موقت به یک نام میزبان دائمی، یا با اقدام صریح مدیر سیستم در هر زمانی پس از راه‌اندازی سیستم، تغییر کند.
هنگامی که این اتفاق می‌افتد، ممکن است
.B pmie
نیاز به اقدام خاصی داشته باشد؛ به‌ویژه اگر نمونهٔ
.B pmie
از
.BR pmie_check (1)
یا
.BR pmie_daily (1)
راه‌اندازی شده باشد،
.B pmie
باید خارج شود. در شرایط عادی،
.BR systemd (1)
یا
.BR cron (8)
اندکی پس از آن یک
.B pmie
جدید را راه‌اندازی خواهند کرد و این نمونهٔ جدید
.B pmie
در بستر نام میزبان جدید میزبانی که PMCD روی آن در حال اجراست، عمل خواهد کرد.
.SH "گزارش باگ‌ها (BUGS)"
اسکنر واژگانی و تجزیه‌کننده تلاش خواهند کرد پس از بروز خطا در عبارت‌های ورودی، وضعیت را بازیابی کنند.
تجزیه پس از نادیده گرفتن ورودی تا نقطه-ویرگول (;) بعدی از سر گرفته می‌شود؛ با این حال، در طول این فرآیند پرش، اسکنر نسبت به کامنت‌ها و رشته‌ها بی‌اعتنا است، بنابراین یک نقطه-ویرگولِ تعبیه‌شده ممکن است باعث شود تجزیه از مکانی غیرمنتظره از سر گرفته شود.
این رفتار تا حد زیادی بی‌خطر است، زیرا تا زمانی که خطای نحوی اولیه برطرف نشود،
.B pmie
هیچ تلاشی برای ارزیابی عبارت‌ها انجام نخواهد داد.
.SH "فایل‌ها (FILES)"
.TP 5
.I $PCP_DEMOS_DIR/pmie/*
قوانین نمونهٔ حاشیه‌نویسی‌شده
.TP
.I $PCP_VAR_DIR/pmns/*
فایل‌های پیش‌فرض مشخصات PMNS
.TP
.I $PCP_TMP_DIR/pmie
.B pmie
فایل‌هایی را در این دایرکتوری نگهداری می‌کند تا نمونه‌های در حال اجرای
.B pmie
را شناسایی کرده و اطلاعات زمان اجرای هر نمونه را صادر کند \- این داده‌ها اساس معیارهای کارایی pmcd.pmie را تشکیل می‌دهند
.TP
.I $PCP_PMIECONTROL_PATH
مجموعهٔ پیش‌فرض نمونه‌های
.B pmie
برای راه‌اندازی در زمان بوت \- برای جزئیات به
.BR pmie_check (1)
مراجعه کنید
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورداستفاده توسط PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP می‌تواند برای تعیین یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده است.
.PP
هنگام اجرای عملیات پوسته،
.B pmie
دو متغیر IFS و PATH را در محیط فرآیند فرزند بازنویسی می‌کند.
مقدار IFS روی "\\t\\n" تنظیم می‌شود.
مقدار PATH روی ترکیبی از یک مسیر پیش‌فرض برای تمامی پلتفرم‌ها ("/usr/sbin:/sbin:/usr/bin:/bin") و چندین مؤلفهٔ قابل‌پیکربندی تنظیم می‌شود.
این مؤلفه‌ها (به این ترتیب) عبارتند از:
.BR $PCP_BIN_DIR ،
.B $PCP_BINADM_DIR
و
.BR $PCP_PLATFORM_PATHS .
.PP
هنگام اجرای عملیات هشدارهای بازشو،
.B pmie
از مقدار
.B $PCP_XCONFIRM_PROG
به عنوان برنامهٔ اعلان بصری برای اجرا استفاده خواهد کرد.
این متغیر معمولاً روی
.BR pmconfirm (1)،
یک کادر گفتگوی چندپلتفرمی، تنظیم شده است.
.SH "همچنین در یونیکس ببینید (UNIX SEE ALSO)"
.BR logger (1).
.SH "همچنین در ویندوز ببینید (WINDOWS SEE ALSO)"
.BR pcp-eventlog (1).
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینهٔ
.B \-D
یا
.B \-\-debug
خروجی عیب‌یابی‌های بیشتری را در
.I stderr
فعال می‌کند تا به تفکیک و اولویت‌بندی مشکلات کمک کند، اگرچه اطلاعات گاهی مبهم است و در درجهٔ اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده است تا کاربران نهایی.
.I debug
فهرستی از گزینه‌های اشکال‌زدایی است که با کاما از هم جدا شده‌اند؛ از
.BR pmdbg (1)
همراه با گزینهٔ
.B \-l
برای دریافت فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید.
.PP
گزینه‌های اشکال‌زدایی اختصاصی
.B pmie
به شرح زیر هستند:
.TS
box;
lf(B) | lf(B)
lf(B) | lxf(R) .
گزینه	توضیحات
_
appl0	T{
اسکن واژگانی حین تجزیهٔ فایل پیکربندی
T}
_
appl1	T{
تجزیهٔ فایل پیکربندی و ساخت درخت عبارت
T}
_
appl2	ارزیابی عبارت
_
appl3	عملیات‌های فایل وضعیت
.TE.SH "همچنین ببینید (SEE ALSO)"
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmconfirm (1),
.BR pmie_check (1),
.BR pmieconf (1),
.BR pmie_daily (1),
.BR pminfo (1),
.BR pmlogdump (1),
.BR pmlogger (1),
.BR pmval (1),
.BR systemd (1),
.BR ctime (3),
.BR PMAPI (3),
.BR pcp.conf (5),
.BR pcp.env (5)
و
.BR PMNS (5).
.SH "راهنمای کاربر (USER GUIDE)"
برای توضیحات کامل‌تر درباره‌ی زبان
.B pmie
به
.BR "Performance Co-Pilot Users and Administrators Guide"
مراجعه کنید. این راهنما به‌صورت آنلاین در نشانی زیر در دسترس است:
.in +4n
.nf
.B https://pcp.readthedocs.io/en/latest/UAG/PerformanceMetricsInferenceEngine.html
.fi
.in -4n

.\" control lines for scripts/man-spell
.\" +ok+ min_inst min_host min_sample
.\" +ok+ max_inst max_host max_sample
.\" +ok+ count_inst count_host count_sample
.\" +ok+ sum_inst sum_host sum_sample
.\" +ok+ avg_inst avg_host avg_sample
.\" +ok+ some_inst some_host some_sample
.\" +ok+ all_inst all_host all_sample
.\" +ok+ _host _inst _sample expr_ match_inst nomatch_inst
.\" +ok+ Kcount Mcount JMS Kleene aka MP ORACLE_SID PMIE
.\" +ok+ usec
.\" +ok+ RULESETS Sep applet constexpr coretemp_isa day_of_week
.\" +ok+ dks filesys hinv immisses instantial joe lmsensors lotsaprocs
.\" +ok+ lru melbourne moomba mypmda myscript ncpu nprocs pswitch
.\" +ok+ ptg ruleset sid