'\" t
.\"
.\" Copyright (c) 2015 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 PMDAPIPE 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmdapipe\f1 \- عامل دامنه معیارهای کارایی (PMDA) برای ضبط خروجی دستورات
.SH "خلاصه دستور (SYNOPSIS)"
\f3$PCP_PMDAS_DIR/pipe/pmdapipe\f1
[\f3\-c\f1 \f2configfile\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-d\f1 \f2domain\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-m\f1 \f2memory\f1]
.SH "توضیحات (DESCRIPTION)"
.B pmdapipe
یک عامل دامنه معیارهای کارایی (PMDA) با قابلیت پیکربندی برای پایش خروجی دستورات است.
می‌توان آن را مشابه یک شل محدودشده در نظر گرفت که در آن می‌توان گزینه‌ها را به دستورات از پیش تعیین‌شده ارسال کرد و هر خط از خروجی آن‌ها به یک رویداد کارایی تبدیل می‌شود.
این رویدادها می‌توانند توسط ابزارهای کلاینت مانند
.BR pmval (1)
مصرف شوند.
.PP
عامل
.B pipe
PMDA هم معیارهای مبتنی بر رویداد شامل رکوردهای دارای برچسب زمانی را برای خروجی‌های متنی دستورات صادر می‌کند، و هم معیارهای متداول‌تر مبتنی بر نمونه‌گیری مانند تعداد رویدادها و مقادیر اندازه توان عملیاتی را ارائه می‌دهد.
.PP
این PMDA از طریق یک
.I configfile
پیکربندی می‌شود که برای هر فرآیندی که خروجی آن قابل ضبط است، حاوی یک خط می‌باشد؛ همان‌گونه که در بخش «پیکربندی (CONFIGURATION)» در ادامه شرح داده شده است.
.PP
شرح مختصری از گزینه‌های خط فرمان
.B pmdapipe
در ادامه آمده است:
.TP 5
.B \-c
یک فایل پیکربندی جایگزین برای PMDA مشخص می‌کند.
به طور پیش‌فرض، فایلی به نام
.I $PCP_PMDAS_DIR/pipe/pipe.conf
و تمام فایل‌های درون دایرکتوری
.I $PCP_SYSCONF_DIR/pipe.conf.d/
استفاده می‌شوند.
.TP
.B \-d
بسیار حیاتی است که شماره دامنه
.RI ( domain )
معیارهای کارایی که در اینجا مشخص می‌شود، یکتا و سازگار باشد.
به این معنا که
.I domain
باید برای هر PMDA روی یک میزبان، متفاوت باشد و همان شماره
.I domain
باید برای همان PMDA در تمام میزبان‌ها استفاده شود.
.TP
.B \-l
محل فایل لاگ. به طور پیش‌فرض، هنگام راه‌اندازی
.BR pmdapipe ،
یک فایل لاگ به نام
.I pipe.log
در دایرکتوری جاری
.BR pmcd (1)
(یعنی
.BR $PCP_LOG_DIR/pmcd )
نوشته می‌شود. اگر فایل لاگ نتواند ایجاد شود یا قابل نوشتن نباشد، خروجی به جای آن در خطای استاندارد نوشته می‌شود.
.TP
.B \-m
حافظه فیزیکی مورد استفاده توسط PMDA برای بافر کردن رکوردهای رویداد را به
.I maxsize
بایت محدود می‌کند.
با رسیدن رویدادهای لاگ به PMDA، آن‌ها باید تا زمانی که ابزارهای کلاینت مجزا دسته بعدی رویدادها را پس از دسته قبلی خود درخواست کنند، بافر شوند.
حداکثر مقدار پیش‌فرض ۲ مگابایت است.
.SH "پیکربندی (CONFIGURATION)"
مجموعه دستورات مجاز pipe توسط یک یا چند فایل متنی ساده پیکربندی می‌شود.
قالب آن شامل یک خط برای هر دستور است که در ادامه یک بخش اختیاری کنترل دسترسی قرار می‌گیرد.
.PP
خطوط خالی و کامنت‌ها در فایل پیکربندی مجاز هستند (و حتی توصیه می‌شوند).
یک کامنت با نویسه «#» آغاز می‌شود و در انتهای خط پایان می‌یابد.
.PP
هر خط پیکربندی دستور به شکل زیر است:
.TP
\&
\f2instance\f1 \f2username\f1 \f2command\f1 \f2options\f1
.PP
که در آن:
.TP 14
.PD 0
.I instance
رشته‌ای است که دستور pipe را مشخص می‌کند و همچنین به عنوان شناسه نمونه معیار صادر می‌شود.
.TP 14
.I username
نام حساب کاربری است که دستور باید تحت آن اجرا شود (مثلاً «root»)
.TP 14
.I command
مسیر فایل باینری است که برای تولید خروجی لوله‌کشی‌شده اجرا خواهد شد
.TP 14
.I options
فهرستی اختیاری و جداشده با فاصله از پارامترهایی است که به \f2command\f1 ارسال می‌شوند
.PD
.IP "" 14
این فهرست
.I options
می‌تواند شامل پارامترهای عددی باشد که با علامت دلار پیشوندگذاری شده‌اند، و این پارامترها در زمان اجرای \f2command\f1 با مقادیر ارائه‌شده توسط کاربر جایگزین خواهند شد (مشابه جایگزینی پارامتر در شل).
.PP
پارامترها به صورت یک رشته منفرد جداشده با فاصله یا کاما و با استفاده از رابط
.B pmStore (3)
به معیار
.I pipe.firehose
ارسال می‌شوند.
دستور
.B pmval
دسترسی ذخیره‌سازی را از طریق گزینه \f3\-x\f1 خود فراهم می‌کند.
پارامترهای ارائه‌شده توسط کاربر به نویسه‌های الفبایی‌عددی محدود شده‌اند.
.PP
بخش کنترل دسترسی فایل باید با خطی به این شکل آغاز شود:
.TP
.B [access]
.PP
فاصله‌های خالی ابتدایی و انتهایی ممکن است در اطراف یا درون کروشه‌ها قرار گیرند و بزرگی یا کوچکی حروف کلیدواژه
.B access
نادیده گرفته می‌شود.
به جز یک کامنت در انتهای خط، هیچ متن دیگری نمی‌تواند در این خط وجود داشته باشد.
.PP
به دنبال این خط، باقی‌مانده فایل پیکربندی باید شامل خطوطی باشد که استفاده از \f2commands\f1 را برای کاربران یا گروه‌های خاص مجاز یا غیرمجاز می‌کنند.
.PP
نام‌های کاربری و نام‌های گروه با استفاده از روتین‌های
.BR getpwent (3)
و
.BR getgrent (3)
از طریق فایل‌های محلی
.B /etc/passwd
و
.B /etc/groups
(یا یک سرویس دایرکتوری جایگزین) اعتبارسنجی می‌شوند.
.PP
دسترسی برای کاربران یا گروه‌ها با مشخص کردن گزاره‌هایی به این شکل مجاز یا غیرمجاز می‌شود:
.TP
\&
\f3allow user\f1 \f2username\f1 \f3:\f1 \f2instance\f1
.br
\f3disallow user\f1 \f2username\f1 \f3:\f1 \f2instance\f1
.br
\f3allow group\f1 \f2groupname\f1 \f3:\f1 \f2instance\f1
.br
\f3disallow group\f1 \f2groupname\f1 \f3:\f1 \f2instance\f1
.PP
نام‌های
.IR username
و
.I groupname
با استفاده از روتین‌های
.BR getpwent (3)
و
.BR getgrent (3)
از طریق فایل‌های محلی
.B /etc/passwd
و
.B /etc/groups
(یا یک سرویس دایرکتوری جایگزین) اعتبارسنجی خواهند شد.
.PP
از نویسه عام «*» می‌توان برای ارجاع به تمام نام‌های \f2instance\f1 استفاده کرد..SH "نصب (INSTALLATION)"
اگر می‌خواهید به نام‌ها، متن راهنما و مقادیر معیارهای کارایی pipe دسترسی داشته باشید، اقدامات زیر را به عنوان کاربر root انجام دهید:
.PP
.ft CR
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/pipe
# ./Install
.in
.fi
.ft 1
.PP
این یک فرایند نصب تعاملی است که مسیر هر فایل گزارش برای نظارت (یا دستور برای اجرا)، یک نام نمونهٔ معیار برای شناسایی آن، و اینکه آیا دسترسی باید محدود شود یا خیر را درخواست می‌کند (برای جزئیات بیشتر به گزینهٔ
.B \-x
در
.BR pmval (1)
مراجعه کنید).
.PP
اگر می‌خواهید نصب را لغو کنید، اقدامات زیر را به عنوان کاربر root انجام دهید:
.PP
.ft CR
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/pipe
# ./Remove
.in
.fi
.ft 1
.PP
.B pmdapipe
توسط
.B pmcd
راه‌اندازی می‌شود و هرگز نباید مستقیماً اجرا گردد.
اسکریپت‌های Install و Remove هنگام نصب یا حذف عامل، به
.B pmcd
اطلاع‌رسانی می‌کنند.
.SH "مثال‌ها (EXAMPLES)"
در ادامه یک مثال ساده از پیکربندی
.B pmdapipe
و استفاده از معیارهای pipe برای اجرای دستور
.B btrace
توسط کاربر \f3bob\f1 آورده شده است:
.de CS
.in +0.5i
.ft CR
.nf
..
.de CE
.fi
.ft 1
.in
..
.PP
.CS
bob> cat $PCP_PMDAS_DIR/pipe/pipe.conf
# instance      user      command
rw_syscalls     root      perf script rw-by-file $1
bdev_trace      root      btrace -w $1 /dev/$2

[access]
allow user bob : *;
allow user jane : bdev_trace;
allow group perf : rw_syscalls;

bob> pmval -i bdev_trace -x '5 sda' pipe.firehose
 8,2  5  1  0.000000000 25227  A  WS 734332384 + 24 <- (253,2) 734330336
 8,0  5  2  0.000000414 25227  A  WS 735358432 + 24 <- (8,2) 734332384
 8,0  5  3  0.000000756 25227  Q  WS 735358432 + 24 [qemu-kvm]
 [...5 seconds worth]
bob>
.CE
.SH "فایل‌ها (FILES)"
.PD 0
.TP 10
.B $PCP_PMCDCONF_PATH
گزینه‌های خط فرمان استفاده‌شده برای راه‌اندازی
.B pmdapipe
.TP 10
.B $PCP_PMDAS_DIR/pipe/pipe.conf
فایل پیکربندی پیش‌فرض برای معیارهای pipe
.TP 10
.B $PCP_PMDAS_DIR/pipe/help
فایل متنی راهنمای پیش‌فرض برای معیارهای pipe
.TP 10
.B $PCP_PMDAS_DIR/pipe/Install
اسکریپت نصب برای عامل
.B pmdapipe
.TP 10
.B $PCP_PMDAS_DIR/pipe/Remove
اسکریپت لغو نصب برای عامل
.B pmdapipe
.TP 10
.B $PCP_LOG_DIR/pmcd/pipe.log
فایل گزارش پیش‌فرض برای پیام‌های خطا و سایر اطلاعات حاصل از
.B pmdapipe
.TP 10
.B $PCP_SYSCONF_DIR/pipe.conf.d
دایرکتوری حاوی فایل‌های پیکربندی تکمیلی برای معیارهای pipe
.PD
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند
.B PCP_
برای مقداردهی و پارامتربندی نام فایل‌ها و دایرکتوری‌های استفاده‌شده توسط PCP به کار می‌روند.
در هر نصب، فایل
.I /etc/pcp.conf
حاوی مقادیر محلی برای این متغیرها است.
متغیر
.B $PCP_CONF
ممکن است برای تعیین یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در
.BR pcp.conf (5)
شرح داده شده است.
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینهٔ
.B \-D
یا
.B \-\-debug
خروجی عیب‌یابی تکمیلی را روی
.I stderr
فعال می‌کند تا به بررسی مشکلات کمک کند، اگرچه اطلاعات خروجی گاهی مبهم است و در درجه اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده است تا کاربران نهایی.
.I debug
یک فهرست جداشده با کاما از گزینه‌های اشکال‌زدایی است؛ از
.BR pmdbg (1)
همراه با گزینهٔ
.B \-l
برای به‌دست آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید.
.PP
گزینه‌های اشکال‌زدایی مختص به
.B pmdapipe
به شرح زیر هستند:
.TS
box;
lf(B) | lf(B)
lf(B) | lxf(R) .
گزینه	توضیحات
_
appl0	T{
پردازش و تولید رویداد، تعاملات با \fBpmcd\fP(1)،
مدیریت زمینهٔ کلاینت، اجرای دستور
T}
_
appl1	کنترل‌های دسترسی، عیب‌یابی کاربر و گروه
_
appl2	T{
مدیریت \fIconfigfile\fP، عیب‌یابی آرگومان‌های نادرست دستور،
مدیریت \fBselect\fP(2)
T}
.TE.SH "همچنین ببینید (SEE ALSO)"
.BR PCPIntro (1)،
.BR pmval (1)،
.BR pmcd (1)،
.BR getpwent (3)،
.BR getgrent (3)،
.BR pmStore (3)،
.BR pcp.conf (5)
و
.BR pcp.env (5).

.\" control lines for scripts/man-spell
.\" +ok+ WS {from example output} bdev_trace btrace firehose groupname
.\" +ok+ jane kvm maxsize perf qemu rw  rw_syscalls sda