PMLOGGER.CONTROL(5) File Formats Manual PMLOGGER.CONTROL(5)

pmlogger.control - پرونده‌های کنترلی برای بایگانی Performance Co-Pilot

بایگانی داده‌های تاریخی کارایی برای Performance Co-Pilot (ببینید PCPIntro(1)) از pmlogger(1) استفاده می‌کند و یک یا چند نمونه از pmlogger می‌توانند توسط pmlogger_check(1) و pmlogger_daily(1) مدیریت شوند.

دستور pmlogger_check(1) می‌تواند در هر زمانی از روز اجرا شود و هدف آن بررسی در حال اجرا بودن مجموعه مورد نظر از فرآیندهای pmlogger است. اگر در حال اجرا نباشند، هرگونه فرآیند ثبات (logger) مفقود را مجدداً راه‌اندازی می‌کند. به‌طور پیش‌فرض، pmlogger_check(1) همچنین pmlogger_daily(1) را با گزینه -K فراخوانی می‌کند تا وظایف فشرده‌سازی بایگانی مورد نیاز را اجرا کند.

دستور pmlogger_daily(1) برای اجرا یک بار در روز در نظر گرفته شده است، ترجیحاً در اوایل صبح و هرچه زودتر پس از نیمه‌شب در زمان امکان‌پذیر. وظیفه آن تجمیع، چرخش (rotate) و انجام کارهای نگهداری عمومی برای یک یا چند مجموعه از بایگانی‌های PCP است.

هر دو دستور pmlogger_check(1) و pmlogger_daily(1) روی خانواده‌ای از پرونده‌های کنترلی مشترک عمل می‌کنند، به‌ویژه پرونده $PCP_PMLOGGERCONTROL_PATH و پرونده‌های درون دایرکتوری $PCP_PMLOGGERCONTROL_PATH.d. این پرونده‌ها نباید توسط هیچ کاربری به جز کاربر ارشد (root) قابل نوشتن باشند.

پرونده(های) کنترل باید مطابق با قوانین زیر که برای نسخه جاری (1.1) از قالب پرونده کنترل تعریف شده‌اند، سفارشی‌سازی شوند.

1.
خطوطی که با «#» شروع می‌شوند، توضیح (کامنت) هستند. یک مورد خاص خطوطی هستند که با «#!#» آغاز می‌شوند؛ این‌ها خطوط کنترلی برای یک pmlogger هستند که با استفاده از pmlogctl(1) متوقف شده است.
2.
خطوطی که با «$» آغاز می‌شوند، به‌عنوان تخصیص به متغیرهای محیطی به سبک sh(1) در نظر گرفته می‌شوند، و تمام متن بعد از «$» توسط اسکریپت خواننده پرونده کنترل با eval ارزیابی می‌شود، و متغیر مربوطه به محیط صادر (export) می‌گردد. این قابلیت به‌ویژه برای تنظیم و صدور متغیرها به محیط اسکریپت‌های مدیریتی مفید است، برای مثال: 

$ PMCD_CONNECT_TIMEOUT=20

اگر مقدار سمت راست «=» شامل هرگونه فاصله یا نویسه خالی (whitespace) باشد، باید در علامت نقل‌قول دوتایی (") یا تکی (') محصور شود.

از آنجا که خطوط در هر پرونده کنترل به ترتیب پردازش می‌شوند، مهم است که هرگونه متغیر محیطی پیش از یک خط کنترلی که نمونه‌ای از pmlogger را مشخص می‌کند که ممکن است از آن متغیرهای محیطی استفاده کند تنظیم شود، مثلاً برای کنترل فشرده‌سازی یا پاکسازی بایگانی‌ها توسط pmlogger_daily(1).

3.
باید یک خط نسخه در پرونده کنترل به این شکل وجود داشته باشد: 

$version=1.1

اما از آنجا که تنها نسخه پشتیبانی‌شده در حال حاضر 1.1 است، این اعلان ارزش اضافی فراتر از مستندسازی ندارد.

4.
فیلدهای درون یک خط از پرونده(های) کنترل معمولاً با یک یا چند فاصله یا تب از هم جدا می‌شوند (اگرچه برای برخی استثناهای مهم به توضیحات فیلد directory در زیر مراجعه کنید).
5.
باید در پرونده(های) کنترل یک خط برای هر نمونه از pmlogger با حداقل ۴ فیلد به شکل زیر وجود داشته باشد: 

host primary socks directory args ...

6.
فیلد host نام میزبانی است که منبع معیارهای کارایی برای این نمونه از pmlogger است. کلمه رزروشده LOCALHOSTNAME با local: جایگزین خواهد شد (بنابراین اتصال به pmcd(1) روی میزبان محلی برقرار می‌شود).
7.
فیلد primary نشان می‌دهد که آیا این یک نمونه اصلی (primary) از pmlogger است (y) یا خیر (n). از آنجا که ثبات اصلی باید روی میزبان محلی اجرا شود و برای یک میزبان خاص حداکثر یک ثبات اصلی می‌تواند وجود داشته باشد، این فیلد می‌تواند حداکثر برای یک نمونه از pmlogger برابر y باشد، که در این صورت نام میزبان باید نام میزبان محلی (یا LOCALHOSTNAME) باشد.
8.
فیلد socks مشخص می‌کند که آیا این نمونه از pmlogger باید تحت کنترل pmsocks(1) راه‌اندازی شود تا به یک pmcd(1) از میان دیواره آتش (firewall) متصل گردد (y یا n).
9.
فیلد directory نام یک دایرکتوری است. تمام پرونده‌های بایگانی مرتبط با این نمونه از pmlogger در این دایرکتوری ایجاد خواهند شد، و این دایرکتوری، دایرکتوری جاری برای اجرای هر برنامه‌ای خواهد بود که برای نگهداری آن بایگانی‌ها مورد نیاز است. یک قرارداد مفید این است که بایگانی‌های ثبات اصلی برای میزبان محلی با نام میزبان myhost در دایرکتوری $PCP_ARCHIVE_DIR/myhost نگهداری شوند (این جایی است که اسکریپت راه‌اندازی پیش‌فرض pmlogger در $PCP_RC_DIR/pmlogger بایگانی‌ها را ایجاد خواهد کرد)، در حالی که بایگانی‌های میزبان راه‌دور mumble در $PCP_ARCHIVE_DIR/mumble نگهداری می‌شوند.
10.
فیلد directory می‌تواند حاوی نحو توکار پوسته (shell syntax) باشد که توسط sh(1) ارزیابی می‌شود تا نام واقعی دایرکتوری مورد استفاده تولید شود. ساختارهای مجاز عبارتند از:
  • هر متنی (شامل فاصله‌ها) که درون $( و ) محصور شده باشد، به‌عنوان دستور پوسته تفسیر خواهد شد.
  • هر متنی (شامل فاصله‌ها) که درون ` و ` (بک‌تیک یا نقل‌قول وارونه) محصور شده باشد، به‌عنوان دستور پوسته تفسیر خواهد شد.
  • درون یک خط تنها یک سبک از دستور پوسته توکار مجاز است، یعنی یا $(...) یا `...`, اما نه هر دو.
  • یک نقل‌قول دوتایی ابتدایی (") که به دنبال آن متن دلخواه (شامل فاصله، اما بدون نقل‌قول دوتایی درون متن) و یک نقل‌قول دوتایی پایانی بیاید.
  • یک نقل‌قول تکی ابتدایی (') که به دنبال آن متن دلخواه (شامل فاصله، اما بدون نقل‌قول تکی درون متن) و یک نقل‌قول تکی پایانی بیاید.
  • هر کلمه‌ای که حاوی یک $ باشد (فرض می‌شود که نام یک متغیر محیطی را معرفی می‌کند).
11.
در فیلد directory، کلمه رزروشده LOCALHOSTNAME با نام میزبان محلی جایگزین خواهد شد. به همین ترتیب کلمات رزروشده PCP_ARCHIVE_DIR و PCP_LOG_DIR که در هر کجای فیلد directory ظاهر شوند با مقادیر متغیرهای محیطی مربوطه جایگزین خواهند شد.
12.
اگر فیلد directory (پس از هرگونه جایگزینی پوسته) با «+» شروع شود، این نشان می‌دهد که pmlogger(1) با گزینه -R در args اجرا خواهد شد تا بایگانی را به یک سرور راه‌دور pmproxy(1) «ارسال» (push) کند. در این حالت، هیچ پرونده بایگانی به‌صورت محلی ذخیره نمی‌شود، اما directory (پس از حذف «+» ابتدایی) به‌عنوان دایرکتوری‌ای استفاده می‌شود که پرونده گزارش (log) حاصل از pmlogger(1) محلی در آن ذخیره خواهد شد و احتمالاً مکانی برای پرونده پیکربندی pmlogger(1) خواهد بود (به مثال زیر مراجعه کنید).
13.
فیلد اختیاری args و هرگونه فیلد باقی‌مانده به‌عنوان آرگومان‌هایی تفسیر می‌شوند که باید به pmlogger(1) ارسال شوند. معمولاً این حداقل شامل گزینه -c برای تعیین معیارهای مورد نظر جهت ثبت و بسامدهای ثبت، و/یا -R در مورد یک بایگانی «ارسال» (push) خواهد بود.

خطوط کنترلی نمونه زیر یک ثبات اصلی را روی میزبان محلی (bozo)، ثبات‌های غیراصلی را برای جمع‌آوری و ثبت معیارهای کارایی از میزبان‌های wobbly، boing و میزبان محلی (یعنی bozo) و یک ثبات را برای ارسال بایگانی‌ها به pmproxy(1) راه‌دور روی میزبان grunt مشخص می‌کنند.

$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 \
				-c ./remote.config

اجرای دوره‌ای pmlogger_check(1) و pmlogger_daily(1) توسط systemd(1) یا cron(8) کنترل می‌شود.

مدخل‌های متداول crontab(5) در $PCP_SYSCONF_DIR/pmlogger/crontab ارائه شده‌اند (مگر اینکه از قبل به‌طور پیش‌فرض در /etc/cron.d نصب شده باشند) و در زیر نشان داده شده است.

# 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

هنگام استفاده از systemd(1) در لینوکس، هیچ مدخل crontab لازم نیست زیرا سازوکار تایمر ارائه‌شده توسط systemd به جای آن برای دستیابی به همان دوره اجرایی مشابه با مثال crontab بالا استفاده می‌شود.

$PCP_PMLOGGERCONTROL_PATH
پرونده کنترل ثبات PCP. برای یک نصب جدید، این پرونده هیچ خط کنترلی برای pmlogger(1) ندارد (پرونده‌های کنترلی واقعی همگی در دایرکتوری $PCP_PMLOGGERCONTROL_PATH.d هستند)، اما این پرونده همچنان برای پشتیبانی از هرگونه پیکربندی قدیمی از نسخه‌های پیشین PCP پردازش می‌شود.
هشدار: این پرونده نباید توسط هیچ کاربری به جز کاربر ارشد (root) قابل نوشتن باشد.
$PCP_PMLOGGERCONTROL_PATH.d
دایرکتوری اختیاری حاوی پرونده‌های کنترل ثبات PCP اضافی، با یک یا چند مشخصه برای هر pmlogger در هر پرونده.
هشدار: پرونده‌های درون اینجا نباید توسط هیچ کاربری به جز کاربر ارشد (root) قابل نوشتن باشند.
$PCP_SYSCONF_DIR/pmlogger/crontab
یک crontab نمونه برای اجرای خودکار اسکریپت توسط $PCP_USER (یا کاربر ارشد root). فقط در صورتی وجود دارد که پلتفرم از سازوکار ‎/etc/cron.d پشتیبانی نکند.

متغیرهای محیطی با پیشوند PCP_ برای پارامتریک‌سازی نام پرونده‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند. در هر نصب، پرونده /etc/pcp.conf حاوی مقادیر محلی برای این متغیرها است. متغیر $PCP_CONF ممکن است برای تعیین یک پرونده پیکربندی جایگزین استفاده شود، همان‌طور که در pcp.conf(5) شرح داده شده است.

PCPIntro(1), pmcd(1), pmlogctl(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), pmlogger_daily_report(1), pmproxy(1), pmsocks(1), systemd(1) و cron(8).

PCP Performance Co-Pilot