'\"macro stdmacro
.\"
.\" Copyright (c) 2013-2019 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 PMLOGGER.CONTROL 5 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmlogger.control\f1 \- پرونده‌های کنترلی برای بایگانی Performance Co-Pilot
.SH "توضیحات (DESCRIPTION)"
بایگانی داده‌های تاریخی کارایی برای
Performance Co-Pilot (ببینید
.BR PCPIntro (1))
از
.BR pmlogger (1)
استفاده می‌کند و یک یا چند نمونه از
.B pmlogger
می‌توانند توسط
.BR pmlogger_check (1)
و
.BR pmlogger_daily (1)
مدیریت شوند.
.PP
دستور
.BR pmlogger_check (1)
می‌تواند در هر زمانی از روز اجرا شود و هدف آن بررسی در حال اجرا بودن مجموعه مورد نظر از فرآیندهای
.B pmlogger
است.
اگر در حال اجرا نباشند، هرگونه فرآیند ثبات (logger) مفقود را مجدداً راه‌اندازی می‌کند.
به‌طور پیش‌فرض،
.BR pmlogger_check (1)
همچنین
.BR pmlogger_daily (1)
را با گزینه
.B \-K
فراخوانی می‌کند تا وظایف فشرده‌سازی بایگانی مورد نیاز را اجرا کند.
.PP
دستور
.BR pmlogger_daily (1)
برای اجرا یک بار در روز در نظر گرفته شده است، ترجیحاً در اوایل صبح و هرچه زودتر پس از نیمه‌شب در زمان امکان‌پذیر.
وظیفه آن تجمیع، چرخش (rotate) و انجام کارهای نگهداری عمومی برای یک یا چند مجموعه از بایگانی‌های PCP است.
.PP
هر دو دستور
.BR pmlogger_check (1)
و
.BR pmlogger_daily (1)
روی خانواده‌ای از پرونده‌های کنترلی مشترک عمل می‌کنند، به‌ویژه پرونده
.I $PCP_PMLOGGERCONTROL_PATH
و پرونده‌های درون دایرکتوری
.IR $PCP_PMLOGGERCONTROL_PATH.d .
این پرونده‌ها نباید توسط هیچ کاربری به جز کاربر ارشد (root) قابل نوشتن باشند.
.PP
پرونده(های) کنترل باید مطابق با قوانین زیر که برای نسخه جاری (1.1) از قالب پرونده کنترل تعریف شده‌اند، سفارشی‌سازی شوند.
.IP 1. 4n
خطوطی که با «#» شروع می‌شوند، توضیح (کامنت) هستند.
یک مورد خاص خطوطی هستند که با «#!#» آغاز می‌شوند؛ این‌ها خطوط کنترلی برای یک
.B pmlogger
هستند که با استفاده از
.BR pmlogctl (1)
متوقف شده است.
.PD 0
.IP 2. 4n
خطوطی که با «$» آغاز می‌شوند، به‌عنوان تخصیص به متغیرهای محیطی به سبک
.BR sh (1)
در نظر گرفته می‌شوند، و تمام متن بعد از «$» توسط اسکریپت خواننده پرونده کنترل با
.B eval
ارزیابی می‌شود،
و متغیر مربوطه به محیط صادر (export) می‌گردد.
این قابلیت به‌ویژه برای تنظیم و صدور متغیرها به محیط اسکریپت‌های مدیریتی مفید است، برای مثال:
.br
.in +4n
.ft CR
.nf
$ PMCD_CONNECT_TIMEOUT=20
.fi
.ft R
.in -4n
اگر مقدار سمت راست «=» شامل هرگونه فاصله یا نویسه خالی (whitespace) باشد،
باید در علامت نقل‌قول دوتایی (\[dq]) یا تکی (\[aq]) محصور شود.
.RS 4n
.PP
از آنجا که خطوط در هر پرونده کنترل به ترتیب پردازش می‌شوند، مهم است که هرگونه متغیر محیطی
.B پیش از
یک خط کنترلی که نمونه‌ای از
.B pmlogger
را مشخص می‌کند که ممکن است از آن متغیرهای محیطی استفاده کند تنظیم شود، مثلاً برای کنترل فشرده‌سازی یا پاکسازی بایگانی‌ها توسط
.BR pmlogger_daily (1).
.RE
.IP 3. 4n
باید یک خط نسخه در پرونده کنترل به این شکل وجود داشته باشد:
.br
.in +4n
.ft CR
.nf
$version=1.1
.fi
.ft R
.in -4n
.RS
.nr PD 0
.PP
اما از آنجا که تنها نسخه پشتیبانی‌شده در حال حاضر 1.1 است، این اعلان ارزش اضافی فراتر از مستندسازی ندارد.
.PD
.RE
.IP 4. 4n
فیلدهای درون یک خط از پرونده(های) کنترل معمولاً با یک یا چند فاصله یا تب از هم جدا می‌شوند (اگرچه برای برخی استثناهای مهم به توضیحات فیلد
.I directory
در زیر مراجعه کنید).
.IP 5. 4n
باید در پرونده(های) کنترل یک خط برای هر نمونه از
.B pmlogger
با حداقل ۴ فیلد به شکل زیر وجود داشته باشد:
.br
.in +4n
.ft CR
.nf
\f2host\f1 \f2primary\f1 \f2socks\f1 \f2directory\f1 \f2args\f1 ...
.fi
.ft R
.in -4n
.IP 6. 4n
فیلد
.I host
نام میزبانی است که منبع معیارهای کارایی برای این نمونه از
.B pmlogger
است.
کلمه رزروشده
.B LOCALHOSTNAME
با
.B local:
جایگزین خواهد شد (بنابراین اتصال به
.BR pmcd (1)
روی میزبان محلی برقرار می‌شود).
.IP 7. 4n
فیلد
.I primary
نشان می‌دهد که آیا این یک نمونه اصلی (primary) از
.B pmlogger
است (\c
.BR y )
یا خیر (\c
.BR n ).
از آنجا که ثبات اصلی باید روی میزبان محلی اجرا شود و برای یک میزبان خاص حداکثر یک ثبات اصلی می‌تواند وجود داشته باشد، این فیلد می‌تواند حداکثر برای یک نمونه از
.B pmlogger
برابر
.B y
باشد، که در این صورت نام میزبان باید نام میزبان محلی (یا
.BR LOCALHOSTNAME )
باشد.
.IP 8. 4n
فیلد
.I socks
مشخص می‌کند که آیا این نمونه از
.B pmlogger
باید تحت کنترل
.BR pmsocks (1)
راه‌اندازی شود تا به یک
.BR pmcd (1)
از میان دیواره آتش (firewall) متصل گردد (\c
.B y
یا
.BR n ).
.IP 9. 4n
فیلد
.I directory
نام یک دایرکتوری است. تمام پرونده‌های بایگانی مرتبط با این نمونه از
.B pmlogger
در این دایرکتوری ایجاد خواهند شد،
و این دایرکتوری، دایرکتوری جاری برای اجرای هر برنامه‌ای خواهد بود که برای نگهداری آن بایگانی‌ها مورد نیاز است.
یک قرارداد مفید این است که بایگانی‌های ثبات اصلی برای میزبان محلی با نام میزبان
.I myhost
در دایرکتوری
.I $PCP_ARCHIVE_DIR/myhost
نگهداری شوند
(این جایی است که اسکریپت راه‌اندازی پیش‌فرض
.B pmlogger
در
.I $PCP_RC_DIR/pmlogger
بایگانی‌ها را ایجاد خواهد کرد)، در حالی که بایگانی‌های میزبان راه‌دور
.I mumble
در
.IR $PCP_ARCHIVE_DIR/mumble
نگهداری می‌شوند.
.IP 10. 4n
فیلد
.I directory
می‌تواند حاوی نحو توکار پوسته (shell syntax) باشد که توسط
.BR sh (1)
ارزیابی می‌شود تا نام واقعی دایرکتوری مورد استفاده تولید شود. ساختارهای مجاز عبارتند از:
.RS
.nr PD 0
.IP \(bu 2n
هر متنی (شامل فاصله‌ها) که درون
.B $(
و
.BR )
محصور شده باشد، به‌عنوان دستور پوسته تفسیر خواهد شد.
.IP \(bu 2n
هر متنی (شامل فاصله‌ها) که درون
.B \[ga]
و
.B \[ga]
(بک‌تیک یا نقل‌قول وارونه) محصور شده باشد، به‌عنوان دستور پوسته تفسیر خواهد شد.
.IP \(bu 2n
درون یک خط تنها یک سبک از دستور پوسته توکار مجاز است، یعنی یا
.BR $( ... )
یا
.BR \[ga] ... \[ga] ,
اما نه هر دو.
.IP \(bu 2n
یک نقل‌قول دوتایی ابتدایی (\[dq]) که به دنبال آن متن دلخواه (شامل فاصله، اما بدون نقل‌قول دوتایی درون متن) و یک نقل‌قول دوتایی پایانی بیاید.
.IP \(bu 2n
یک نقل‌قول تکی ابتدایی (\[aq]) که به دنبال آن متن دلخواه (شامل فاصله، اما بدون نقل‌قول تکی درون متن) و یک نقل‌قول تکی پایانی بیاید.
.IP \(bu 2n
هر کلمه‌ای که حاوی یک
.B $
باشد (فرض می‌شود که نام یک متغیر محیطی را معرفی می‌کند).
.nr PD
.RE
.IP 11. 4n
در فیلد
.IR directory ،
کلمه رزروشده
.B LOCALHOSTNAME
با نام میزبان محلی جایگزین خواهد شد.
به همین ترتیب کلمات رزروشده
.B PCP_ARCHIVE_DIR
و
.B PCP_LOG_DIR
که در هر کجای فیلد
.I directory
ظاهر شوند با مقادیر متغیرهای محیطی مربوطه جایگزین خواهند شد.
.IP 12. 4n
اگر فیلد
.I directory
(پس از هرگونه جایگزینی پوسته) با «+» شروع شود، این نشان می‌دهد که
.BR pmlogger (1)
با گزینه
.B \-R
در
.I args
اجرا خواهد شد تا بایگانی را به یک سرور راه‌دور
.BR pmproxy (1)
«ارسال» (push) کند.
در این حالت، هیچ پرونده بایگانی به‌صورت محلی ذخیره نمی‌شود، اما
.I directory
(پس از حذف «+» ابتدایی) به‌عنوان دایرکتوری‌ای استفاده می‌شود که پرونده گزارش (log) حاصل از
.BR pmlogger (1)
محلی در آن ذخیره خواهد شد و احتمالاً مکانی برای پرونده پیکربندی
.BR pmlogger (1)
خواهد بود (به مثال زیر مراجعه کنید).
.IP 13. 4n
فیلد اختیاری
.I args
و هرگونه فیلد باقی‌مانده به‌عنوان آرگومان‌هایی تفسیر می‌شوند که باید به
.BR pmlogger (1)
ارسال شوند.
معمولاً این حداقل شامل گزینه
.B \-c
برای تعیین معیارهای مورد نظر جهت ثبت و بسامدهای ثبت، و/یا
.B \-R
در مورد یک بایگانی «ارسال» (push) خواهد بود.
.PD
.PP
خطوط کنترلی نمونه زیر یک ثبات اصلی را روی میزبان محلی (\c
.IR bozo )،
ثبات‌های غیراصلی را برای جمع‌آوری و ثبت معیارهای کارایی از میزبان‌های
.IR wobbly ،
.I boing
و میزبان محلی (یعنی \c
.IR bozo )
و یک ثبات را برای ارسال بایگانی‌ها به
.BR pmproxy (1)
راه‌دور روی میزبان
.I grunt
مشخص می‌کنند.
.PP
.nf
.ft CR
$version=1.1
bozo          y  n  $PCP_ARCHIVE_DIR/bozo   \-c config.default
wobbly        n  n  "/store/wobbly/$(date +%Y)"  \-c ./wobbly.config
boing         n  n  $PCP_ARCHIVE_DIR/boing   \-c ./pmlogger.config
LOCALHOSTNAME n  n  /cluster/LOCALHOSTNAME   \-c ./precious.config
LOCALHOSTNAME n  n  +PCP_ARCHIVE_DIR/remote \-R http://grunt:44322 \e
				\-c ./remote.config
.ft 1
.fi
.SH "اجرای زمان‌بندی‌شده (SCHEDULED EXECUTION)"
اجرای دوره‌ای
.BR pmlogger_check (1)
و
.BR pmlogger_daily (1)
توسط
.BR systemd (1)
یا
.BR cron (8)
کنترل می‌شود.
.PP
مدخل‌های متداول
.BR crontab (5)
در
.I $PCP_SYSCONF_DIR/pmlogger/crontab
ارائه شده‌اند (مگر اینکه از قبل به‌طور پیش‌فرض در
.I /etc/cron.d
نصب شده باشند)
و در زیر نشان داده شده است.
.PP
.nf
.ft CR
# daily processing of archives
14      0       *       *       *       $PCP_BINADM_DIR/pmlogger_daily
# every 30 minutes, check pmlogger instances are running
25,55   *       *       *       *       $PCP_BINADM_DIR/pmlogger_check
.ft 1
.fi
.PP
هنگام استفاده از
.BR systemd (1)
در لینوکس،
هیچ مدخل
.B crontab
لازم نیست زیرا سازوکار تایمر ارائه‌شده توسط
.B systemd
به جای آن برای دستیابی به همان دوره اجرایی مشابه با مثال crontab بالا استفاده می‌شود.
.SH "فایل‌ها (FILES)"
.TP 5
.I $PCP_PMLOGGERCONTROL_PATH
پرونده کنترل ثبات PCP.
برای یک نصب جدید،
این پرونده هیچ خط کنترلی برای
.BR pmlogger (1)
ندارد (پرونده‌های کنترلی واقعی همگی در دایرکتوری
.I $PCP_PMLOGGERCONTROL_PATH.d
هستند)، اما این پرونده همچنان برای پشتیبانی از هرگونه پیکربندی قدیمی از نسخه‌های پیشین PCP پردازش می‌شود.
.br
.BR هشدار :
این پرونده نباید توسط هیچ کاربری به جز کاربر ارشد (root) قابل نوشتن باشد.
.TP
.I $PCP_PMLOGGERCONTROL_PATH.d
دایرکتوری اختیاری حاوی پرونده‌های کنترل ثبات PCP اضافی،
با یک یا چند مشخصه برای هر
.B pmlogger
در هر پرونده.
.br
.BR هشدار :
پرونده‌های درون اینجا نباید توسط هیچ کاربری به جز کاربر ارشد (root) قابل نوشتن باشند.
.TP
.I $PCP_SYSCONF_DIR/pmlogger/crontab
یک crontab نمونه برای اجرای خودکار اسکریپت توسط $PCP_USER (یا کاربر ارشد root).
فقط در صورتی وجود دارد که پلتفرم از سازوکار ‎/etc/cron.d پشتیبانی نکند.
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای پارامتریک‌سازی نام پرونده‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، پرونده \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP ممکن است برای تعیین یک پرونده پیکربندی جایگزین استفاده شود، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده است.
.SH "همچنین ببینید (SEE ALSO)"
.BR PCPIntro (1),
.BR pmcd (1),
.BR pmlogctl (1),
.BR pmlogger (1),
.BR pmlogger_check (1),
.BR pmlogger_daily (1),
.BR pmlogger_daily_report (1),
.BR pmproxy (1),
.BR pmsocks (1),
.BR systemd (1)
و
.BR cron (8).

.\" control lines for scripts/man-spell
.\" +ok+ myhost boing args