نام (NAME)

pmlogconf - ایجاد یا ویرایش فایل پیکربندی pmlogger

خلاصه دستور (SYNOPSIS)

pmlogconf [-cqrvV?] [-d groupsdir] [-D debug] [-g grouptag] [-h host] [-s groupfile] configfile

توضیحات (DESCRIPTION)

دستور pmlogconf می‌تواند برای ایجاد و تغییر یک فایل پیکربندی عمومی برای بایگان‌کننده PCP، یعنی pmlogger(1) به کار رود.

اگر configfile وجود نداشته باشد، pmlogconf یک فایل پیکربندی عمومی با مجموعه‌ای پیش‌فرض از سنجه‌های فعال و بازه‌های ثبت وقایع ایجاد خواهد کرد.

پس از ایجاد، configfile می‌تواند همراه با گزینه -c در pmlogger(1) برای انتخاب سنجه‌های کارایی و تعیین بازه‌های ثبت وقایع برای یک آرشیو PCP استفاده شود.

اگر configfile از قبل وجود داشته باشد، pmlogconf از کاربر درخواست ورودی می‌کند تا گروه‌هایی از سنجه‌های کارایی مرتبط را فعال یا غیرفعال کند و بازه ثبت وقایع را برای هر گروه فعال‌شده کنترل نماید.

انتخاب گروه نیازمند یک پاسخ ساده y (بله) یا n (خیر) به اعلان Log this group? است.

پاسخ‌های دیگر در این مرحله می‌توانند برای انتخاب توابع کنترلی بیشتر به شرح زیر استفاده شوند:

m: گزارش نام سنجه‌های موجود در گروه فعلی.
q: پایان دادن به انتخاب گروه (خروج) و اعمال نکردن تغییرات بیشتر در این گروه یا هر یک از گروه‌های بعدی.
/pattern: عدم اعمال تغییر در این گروه، اما جستجو برای گروهی حاوی pattern در توضیحات گروه یا نام سنجه‌های وابسته.

یک بازه ثبت وقایع با پاسخ دادن به اعلان Logging interval? توسط کلیدواژه‌های once یا default یا یک مشخصه بازه زمانی معتبر در pmlogger(1) به فرم ``every N timeunits'' یا صرفاً ``N timeunits '' (کلمه every اختیاری است) مشخص می‌شود؛ که در آن N یک عدد صحیح بدون علامت است و timeunits یکی از کلیدواژه‌های msec، millisecond، sec، second، min، minute، hour یا شکل جمع یکی از این کلیدواژه‌ها است.

هنگام اجرا از طریق فرآیندهای خودکارِ راه‌اندازی ثبت وقایع، گزینه -c برای نشان دادن این که pmlogconf در حالت ایجاد خودکار (auto-create) است و هیچ گفتگوی تعاملی صورت نمی‌گیرد، استفاده می‌شود. فایل خروجی configfile دارای یک پیام توضیحی اضافی و برچسب زمانی است که این موضوع را نشان می‌دهد، تا بتوان آن را شناسایی کرده و متعاقباً با استفاده مجدد از -c به‌روزرسانی نمود. این گزینه برای استفاده تعاملی از این ابزار مناسب نیست.

گزینه -q گفتگوی مربوط به بازه ثبت وقایع را متوقف می‌کند و بازه فعلی را از configfile حفظ می‌نماید.

خروجی پرجزئیات‌تر را می‌توان با گزینه -v فعال کرد..SH "فایل‌های گروه راه‌اندازی (SETUP GROUP FILES)" هنگامی که یک configfile اولیه ایجاد می‌شود، مشخصات پیش‌فرض از مجموعه‌ای از فایل‌های گروه در زیر groupsdir مشخص‌شده با گزینهٔ -d به‌دست می‌آیند (مقدار پیش‌فرض groupsdir برابر با $PCP_VAR_DIR/config/pmlogconf است که در اکثر موارد درست می‌باشد، بنابراین گزینهٔ -d در عمل به‌ندرت استفاده می‌شود).

ساختار دایرکتوری در زیر groupsdir دلخواه است، چرا که تمام فایل‌های عادی با پیمایش بازگشتی پیدا شده و مورد بررسی قرار می‌گیرند؛ از این رو محصولات جانبی و توسعه‌دهندگان PMDA می‌توانند با افزودن دایرکتوری‌ها و/یا فایل‌های گروه جدید در زیر groupsdir، پیش‌فرض‌های دردسترس برای pmlogconf را به‌سادگی گسترش دهند.

این فایل‌های گروه به روش‌های زیر پردازش می‌شوند:

هنگامی که یک configfile جدید ایجاد می‌شود، تمام فایل‌های گروه پردازش می‌شوند.
هر زمان که pmlogconf با یک configfile موجود اجرا شود، groupsdir پیمایش می‌شود تا بررسی شود آیا گروه جدیدی تعریف شده است که باید برای گنجانده شدن در configfile در نظر گرفته شود یا خیر.
هنگامی که pmlogconf گروهی را در configfile پردازش می‌کند که فعال است، فهرست معیارهای (metrics) مرتبط با آن گروه از فایل گروه گرفته می‌شود (و جایگزین هر فهرست قبلی از معیارهای مرتبط با این گروه در configfile می‌گردد).
هنگامی که هر یک از گزینه‌های خط فرمان -r (پویش مجدد یا reprobe) یا -c (ایجاد خودکار یا auto-create) مشخص شوند، تمام گروه‌ها (نه فقط گروه‌های تازه کشف‌شده) مجدداً پردازش می‌شوند تا بررسی شود که آیا باید برای گنجانده شدن در configfile در نظر گرفته شوند یا خیر.
اگر گروهی در configfile یافت شود اما گروه متناظر با آن در زیر groupsdir وجود نداشته باشد (مانند حالتی که یک گروه با ارتقای PCP منسوخ می‌شود)، نحوهٔ برخورد با آن گروه به حالتی بستگی دارد که pmlogconf در آن اجرا می‌شود. با -c گروه متناظر از configfile حذف می‌شود، در غیر این صورت گروه متناظر در configfile بدون تغییر باقی می‌ماند. در هر دو حالت یک هشدار صادر می‌شود.

هر فایل گروه ساختاری به شرح زیر دارد:

خط نخست باید شامل #pmlogconf-setup 2.0 باشد.
سایر خطوطی که با # آغاز می‌شوند به‌عنوان توضیح (comment) در نظر گرفته می‌شوند.
خط‌های خالی نادیده گرفته می‌شوند.
یک یا چند خط که با کلمهٔ کلیدی ident آغاز می‌شوند، برای ارائهٔ توضیحات خوانا برای انسان دربارهٔ گروه استفاده می‌شوند.
خط‌های غیرخالی که با فاصله (white space) آغاز می‌شوند، معیارهای مرتبط با این گروه را مشخص می‌کنند، هر خط یک معیار. هر مشخصهٔ معیار از قواعد پیکربندی pmlogger(1) پیروی می‌کند، یعنی یا نام یک گرهٔ غیربرگ در PMNS (به‌معنای تمام نام‌های فرزند در PMNS) است، یا نام یک گرهٔ برگ در PMNS که می‌تواند اختیاری با یک یا چند نام نمونه محصور در ``['' و ``]'' همراه باشد.
یک خط کنترلی که با یکی از کلمات کلیدی probe یا force آغاز می‌شود باید وجود داشته باشد.
یک خط کنترلی اختیاری برای بازهٔ ثبت وقایع با کلمهٔ کلیدی delta آغاز می‌شود که در ادامهٔ آن یکی از مشخصه‌های بازهٔ pmlogger(1) که در بالا توصیف شد می‌آید.
خط‌های کنترلی اختیاری معیارهای اشتقاقی با کلمهٔ کلیدی define آغاز می‌شوند و قالب زیر را دارند:

define name expr
که در آن name نام یک معیار اشتقاقی و expr عبارت معیار اشتقاقی است. برای توضیحات نحوی و معنایی name و expr به pmRegisterDerived(3) مراجعه کنید. پس از تعریف، name می‌تواند به‌عنوان metric در یک خط کنترلی بعدی probe استفاده شود که امکان بیان شروط پیچیده‌تر را برای گنجاندن مشروط معیارها در configfile فراهم می‌آورد.

توجه داشته باشید که name باید در تمام فایل‌های گروه یکتا باشد و با نام‌های موجود در PMNS تداخل نداشته باشد. بنابراین هنگام ایجاد فایل‌های گروه ممکن است نیاز به اتخاذ یک قرارداد نام‌گذاری مناسب باشد.

•: خطوط کنترلی probe دارای این قالب هستند:

probe metric [condition [state_rule] ]
که در آن metric نام یک معیار PCP است (باید یک گرهٔ برگ در PMNS باشد، هیچ مشخصهٔ نمونه‌ای مجاز نیست، و نباید یک معیار اشتقاقی باشد مگر آنکه در یک خط کنترلی قبلی define ذکر شده باشد) و condition اختیاری، کلمهٔ کلیدی exists است (در صورتی درست است که metric وجود داشته باشد، یعنی در PMNS تعریف شده باشد) یا کلمهٔ کلیدی values است (در صورتی درست است که metric در PMNS وجود داشته باشد و دارای یک یا چند مقدار فعلی باشد) یا عبارتی به فرم
op val که در آن op یکی از عملگرهای awk(1) است (==، !=، >، >=، <، <=، ~ (تطابق عبارت باقاعده) یا !~ (نفی تطابق عبارت باقاعده)) و val یک مقدار است (توالی دلخواهی از نویسه‌ها به‌جز فاصله)، و condition در صورتی درست است که نمونه‌ای از metric وجود داشته باشد که عبارت را درست کند..PP اگر condition مشخص نشده باشد، پیش‌فرض exists است.

هنگامی که یک condition صریح ارائه شود، ممکن است یک state_rule اختیاری نیز به شکل زیر وجود داشته باشد:
? true_state : false_state که در آن true_state (در صورتی که condition درست باشد اعمال می‌شود) و false_state (در صورتی که condition نادرست باشد اعمال می‌شود) هر دو از کلمات کلیدی زیر انتخاب می‌شوند: include (گنجاندن و فعال‌سازی گروه و معیارهای مرتبط در configfile)، available (گنجاندن و غیرفعال‌سازی گروه در configfile - اقدام کاربر با y، همان‌طور که در بالا در حالتی که configfile از پیش موجود باشد شرح داده شد، برای فعال‌سازی گروه و افزودن معیارهای مرتبط به configfile مورد نیاز است) یا exclude (گروه برای گنجانده شدن در configfile در نظر گرفته نمی‌شود).

قانون state_rule پیش‌فرض عبارت است از:
? available : exclude

•: خطوط کنترلی force با کلمه کلیدی force آغاز می‌شوند و به دنبال آن یکی از وضعیت‌های تعریف‌شده در بالا می‌آید، بنابراین یکی از اقدامات include، exclude یا available بدون قید و شرط بر روی گروه اعمال می‌گردد.

کاوش (probing) تنها زمانی انجام می‌شود که یک گروه جدید به configfile اضافه شود یا زمانی که گزینه خط فرمان -r مشخص شده باشد. ارزیابی شرایط کاوش از طریق برقراری ارتباط با pmcd(1) روی hostname (پیش‌فرض :local) صورت می‌گیرد.

گزینه‌ها (OPTIONS)

گزینه‌های خط فرمان موجود عبارتند از:

-c: فعال‌سازی حالت غیرتعاملی و ساخت خودکار (auto-create).
-d groupsdir, --groups=groupsdir: مسیر دایرکتوری groupsdir را مشخص می‌کند.
-g grouptag, --group=grouptag: پرس‌وجوی وضعیت لاگ‌گیری برای گروه لاگ‌گیری خاص با نام grouptag.
-h host, --host=host: منبع معیارهای عملکرد به جای localhost پیش‌فرض، pmcd(1) بر روی host است.
-q, --quiet: حالت بی‌صدا؛ فرونشاندن دیالوگ بازه زمانی لاگ‌گیری.
-r, --reprobe: بررسی مجدد تمامی گروه‌ها جهت گنجاندن در configfile.
-s groupfile, --setup=groupfile: گزارش وضعیت لاگ‌گیری پیش‌فرض برای گروه لاگ‌گیری درون groupfile. این خروجی معادل خروجی تولیدشده توسط اسکریپت شل از رده خارج pmlogconf-setup در نسخه‌های قبلی PCP است.
-v, --verbose: فعال‌سازی حالت پرگو (verbose).
-V, --version: نمایش شماره نسخه و خروج.
-?, --help: نمایش پیام راهنمای استفاده و خروج..SH "مثال‌ها (EXAMPLES)" فایل گروهیِ زیر بیشتر عناصر نحویِ پشتیبانی‌شده را نمایش می‌دهد.

#pmlogconf-setup 2.0
ident   Example group file
ident   ... more description
delta   1 minute
probe   sample.secret.foo.one values ? include : exclude
        sample.secret.foo.one
        sample.secret.foo.bar   # non-leaf in the PMNS
        sample.colour [ red green ]

در مثال زیر (بک‌اسلش‌ها برای خوانایی بیشتر اضافه شده‌اند، عبارت define کاملاً در یک خط قرار دارد)، اگر معیار mumble.foo شناخته‌شده باشد و حداقل یک نمونه (و مقدار) داشته باشد، یا اگر معیار mumble.bar شناخته‌شده باشد و حداقل یک نمونه (و مقدار) داشته باشد، معیارهای mumble در configfile گنجانده خواهند شد:

#pmlogconf-setup 2.0
ident   Derived metric example with alternation
define  mumble.check = \
            (defined(mumble.foo) ? count(mumble.foo) : 0) + \
            (defined(mumble.bar) ? count(mumble.bar) : 0)
probe   mumble.check > 0 ? include : exclude
        mumble

مثال زیر از یک معیار مشتق‌شده برای دسترسی به یک نمونهٔ خاص از معیار در یک سطر کنترلی probe استفاده می‌کند.

#pmlogconf-setup 2.0
ident   Derived metric example using a single metric instance
define  fumble_log = fumble.control[verbose_log]
probe   fumble_log > 0 ? include : exclude
        fumble.detailed

مهاجرت (MIGRATION)

نسخهٔ فعلی pmlogconf (2.0) در مقایسه با نسخه‌های پیشین، از قالب کمی متفاوتی برای configfile پشتیبانی می‌کند. اگر یک configfile نسخهٔ قدیمی به pmlogconf ارائه شود، به قالب جدید تبدیل خواهد شد.

محیط PCP (PCP ENVIRONMENT)

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

pmlogconf به دلایل کارایی و برای جلوگیری از گنجانده شدن معیارهای مشتق‌شده در configfile، هرگونه متغیر محیطی $PCP_DERIVED_CONFIG را با یک رشتهٔ خالی بازنویسی می‌کند.

pmlogconf هنگام کاوش و ایجاد فایل‌های پیکربندی جدید pmlogger متغیر محیطی $PMCD_WAIT_TIMEOUT را رعایت می‌کند. در صورت عدم تنظیم این متغیر در محیط، از مقدار پیش‌فرض ۱۰ ثانیه برای مهلت زمانی استفاده می‌شود..SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)" گزینهٔ -D یا --debug خروجی داده‌های تشخیصی اضافی را روی stderr فعال می‌کند تا به تفکیک و ارزیابی مشکلات کمک کند، اگرچه این اطلاعات گاهی مبهم است و در وهله اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی. debug فهرستی از گزینه‌های اشکال‌زدایی جداشده با کاما است؛ از pmdbg(1) به همراه گزینهٔ -l برای به‌دست آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و معنی آن‌ها استفاده کنید.

گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)

گزینهٔ -D یا --debug خروجی داده‌های تشخیصی اضافی را روی stderr فعال می‌کند تا به تفکیک و ارزیابی مشکلات کمک کند، اگرچه این اطلاعات گاهی مبهم است و در وهله اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی. debug فهرستی از گزینه‌های اشکال‌زدایی جداشده با کاما است؛ از pmdbg(1) به همراه گزینهٔ -l برای به‌دست آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و معنی آن‌ها استفاده کنید.

گزینه‌های اشکال‌زدایی مختص pmlogconf به شرح زیر هستند:

گزینه	توضیحات
appl0	عملیات‌های فایل گروه
appl1	عملیات‌های کاوش متریک
appl2	تخلیهٔ کامل و پرجزئیات ساختارهای دادهٔ گروهی داخلی

همچنین ببینید (SEE ALSO)

pmcd(1)، pmlogger(1)، PMAPI(3)، pmRegisterDerived(3)، pcp.conf(5) و pcp.env(5).