| PMLOGCTL(1) | General Commands Manual | PMLOGCTL(1) |
نام (NAME)
pmlogctl - مدیریت و کنترل بایگان‌های Performance Co-Pilot
خلاصه دستور (SYNOPSIS)
pmlogctl [-afmNV?] [-C check_args] [-c class] [-i ident] [-p policy] command [host ...]
توضیحات (DESCRIPTION)
دستور pmlogctl می‌تواند برای مدیریت نمونه‌های غیر‌اصلی بایگانِ Performance Co-Pilot (PCP) یعنی pmlogger(1) استفاده شود. این ابزار بیشترین کاربرد را در یک «مزرعه» (farm) بایگانی PCP دارد که در آن نمونه‌های متعددی از pmlogger(1) در حال ساخت بایگانی‌هایی از داده‌های کارایی گردآوری‌شده از pmcd(1) روی چندین میزبان راه دور هستند.
نمونهٔ اصلی pmlogger(1) ارتباط نزدیکی با فرایند محلی pmcd(1) دارد و در نتیجه از همان زیرساخت کنترلی مشترک، یعنی systemd(1) یا «اسکریپت‌های rc» در init(1) مربوط به PCP بهره می‌برد. به همین دلیل، نمونهٔ اصلی pmlogger(1) را نمی‌توان با pmlogctl مدیریت کرد.
به جهت اختصار در توضیحات زیر، واژهٔ «نمونه» به معنای یک نمونه از pmlogger(1) است.
تمامی نمونه‌های مدیریت‌شده توسط pmlogctl، pmlogger_check(1) و pmlogger_daily(1) از قوانین زیر پیروی می‌کنند:
- 1.
- هر نمونه داده‌های کارایی را از یک pmcd(1) واحد (یعنی یک میزبان) دریافت می‌کند، اما هر pmcd(1) می‌تواند داده‌های کارایی را در اختیار صفر، یک یا چند فرایند pmlogger(1) که روی یک یا چند میزبان اجرا می‌شوند قرار دهد.
- 2.
- روی میزبان محلی، هر نمونه از pmlogger(1) باید دقیقاً یک بار در یک فایل کنترلی pmlogger_check(1) مشخص شده باشد و pmlogger(1) بایگانی‌ها را در دایرکتوری یکتایی ایجاد می‌کند که در پارامتر چهارم مدخل فایل کنترلی مربوطه نام برده شده است (بخش پیکربندی (CONFIGURATION) در pmlogger_check(1) را ببینید).
- 3.
- هر نمونه دقیقاً متعلق به یک کلاس است که به‌صورت اختیاری با استفاده از انتساب $class=... در فایل کنترلی مربوطه نام‌گذاری می‌شود. کلاس ویژهٔ default برای تمامی نمونه‌هایی که فاقد انتساب $class=... هستند رزرو شده است. برای اهداف گزارش‌گیری (به دستور summary در زیر مراجعه کنید)، نمونهٔ اصلی pmlogger(1) به‌طور خودکار به کلاس ویژهٔ primary اختصاص می‌یابد.
هر بار اجرای pmlogctl یک یا چند نمونه را مدیریت کرده، فایل‌های کنترلی مربوطه را به‌روزرسانی می‌کند و سپس pmlogger_check(1) را برای اعمال تغییرات مورد نظر به اجرا درمی‌آورد.
آرگومان‌های host معمولاً نام‌های معتبر میزبان هستند. برای همهٔ دستورها به جز create و cond-create (که در زیر توضیح داده شده‌اند)، آرگومان‌های host می‌توانند عبارات منظمِ egrep(1) نیز باشند که با کل یک نام میزبان معتبر تطابق می‌یابند، بنابراین الگوی استفاده‌شده در واقع به صورت ^host$ است. به عنوان مثال foo.* (با تمام نام‌های میزبانی که با «foo» شروع می‌شوند مطابقت دارد) یا .*foo (با تمام نام‌های میزبانی که به «foo» ختم می‌شوند مطابقت دارد) یا .*[fF][oO][oO].* (با تمام نام‌های میزبانی که شامل «foo» با حروف بزرگ، کوچک یا ترکیبی هستند مطابقت دارد).
ترکیب یک class از گزینهٔ اختیاری -c (یا default) و آرگومان‌های host برای هر command، مجموعهٔ هدف از نمونه‌هایی را مشخص می‌کند که عملیات command باید روی آن‌ها اعمال شود.
گزینهٔ -i می‌تواند همراه با دستورهای create یا cond-create برای جایگزین کردن شناسهٔ نمونه‌ای که در بخش ident فایل خط‌مشی کلاس مشخص شده است استفاده شود (بخش CLASS POLICY FILE را در ادامه ببینید). از آنجا که این شناسه باید در میان تمام نمونه‌ها و همهٔ کلاس‌ها یکتا باشد، استفاده از این گزینه تنها زمانی منطقی است که فقط یک آرگومان host وجود داشته باشد.
با توجه به وظایفی که pmlogctl انجام می‌دهد، معمولاً باید با دسترسی کاربر ریشه (root) اجرا شود؛ استثنای این قاعده دستور status یا زمانی است که گزینهٔ -N مشخص شده باشد..SH "دستورها (COMMANDS)" command یکی از موارد زیر است:
- check
- وضعیت تمام نمونه‌های پیکربندی‌شده فعلی pmlogger را بررسی کرده و مواردی را که با شکست مواجه شده‌اند دوباره راه‌اندازی می‌کند. اگر پرچم -m روی بسترهای systemd(1) داده شود، فرآیندهای منطبق (و جدید) را به سرویس pmlogger_farm نیز منتقل می‌کند.
- create
- نمونه‌های جدیدی در کلاس classname (default به‌طور پیش‌فرض) برای میزبان‌های host ایجاد می‌کند. نام کلاس برای شناسایی یک فایل خط‌مشی کلاس استفاده می‌شود (بخش CLASS POLICY FILE در زیر را ببینید) که یک الگو برای هر فایل کنترل جدید فراهم می‌کند که در آن %h با host و %i با شناسه (یکتای) نمونه از بخش ident در فایل خط‌مشی کلاس یا ident از گزینه -i جایگزین می‌شود.
گزینه -p می‌تواند برای شناسایی فایل خط‌مشی کلاسی غیر از فایل موجود در مکان استاندارد، یعنی $PCP_SYSCONF_DIR/pmlogger/class.d/classname استفاده شود.
حداقل یک host باید برای دستور create مشخص شود.
- cond-create
- مشابه create است، اما نمونه تنها در صورتی ایجاد می‌شود که یکی از شرایط موجود در بخش create از فایل(های) خط‌مشی کلاس مرتبط به true ارزیابی شود.
اگر گزینه -c مشخص شده باشد، تنها کلاس classname در نظر گرفته می‌شود، در غیر این صورت همه کلاس‌ها در نظر گرفته خواهند شد. در حالت دوم، اگر هیچ‌یک از شرایط در هیچ‌کدام از کلاس‌ها به true ارزیابی نشود، کلاس ویژه pmfind استفاده می‌شود (این کلاس «پیش‌فرض» برای دستور cond-create در زمانی است که سایر موارد با شکست مواجه شوند).
اگر بیش از یک کلاس به true ارزیابی شود، یک فایل پیکربندی ترکیبی pmlogger(1) ایجاد شده و نمونه نیز به کلاس ویژه pmfind اختصاص داده می‌شود. فایل پیکربندی ترکیبی ممکن است شامل ترکیبی از بندهای پیکربندی صریح و بندهای پیکربندی شرطی عمومی‌تر باشد که توسط ابزار pmlogconf(1) شناسایی می‌شوند.
- start
- مجموعه نمونه‌های هدف را راه‌اندازی می‌کند.
اگر مجموعه هدف عمداً شامل بیش از یک نمونه باشد، باید از گزینه -a استفاده شود (این گزینه برای کاهش خطر راه‌اندازی تصادفی تعداد بالقوه زیادی از فرآیندهای pmlogger(1) طراحی شده است).
اگر نمونه‌ای در مجموعه هدف از قبل راه‌اندازی شده باشد، تغییری ایجاد نمی‌شود (برای اجبار به راه‌اندازی نمونه‌های جدید، دستور restart را ببینید).
- stop
- مجموعه نمونه‌های هدف را متوقف می‌کند.
اگر مجموعه هدف عمداً شامل بیش از یک نمونه باشد، باید از گزینه -a استفاده شود (این گزینه برای کاهش خطر متوقف کردن تصادفی تعداد بالقوه زیادی از فرآیندهای pmlogger(1) طراحی شده است).
اگر نمونه‌ای در مجموعه هدف از قبل متوقف شده باشد، هیچ تغییری ایجاد نمی‌شود اما یک هشدار صادر خواهد شد.
- restart
- مجموعه نمونه‌های هدف را متوقف کرده و سپس راه‌اندازی می‌کند.
اگر مجموعه هدف عمداً شامل بیش از یک نمونه باشد، باید از گزینه -a استفاده شود (این گزینه برای کاهش خطر متوقف کردن و راه‌اندازی تصادفی تعداد بالقوه زیادی از فرآیندهای pmlogger(1) طراحی شده است).
اگر نمونه‌ای در مجموعه هدف از قبل متوقف شده باشد، پیش از راه‌اندازی نمونه یک هشدار صادر می‌شود.
- status
- وضعیت مجموعه نمونه‌های هدف را گزارش می‌دهد. اگر هیچ گزینه -c مشخص نشده باشد و هیچ آرگومان host وجود نداشته باشد، یعنی مجموعه هدف خالی باشد، وضعیت تمام نمونه‌ها گزارش داده خواهد شد.
- destroy
- مجموعه نمونه‌های هدف را نابود می‌کند. در پایان این عملیات، فرآیندهای pmlogger(1) مرتبط متوقف شده و اطلاعات فایل کنترل مربوطه حذف خواهند شد.
اگر مجموعه هدف عمداً شامل بیش از یک نمونه باشد، باید از گزینه -a استفاده شود (این گزینه برای کاهش خطر پایان دادن تصادفی به تعداد بالقوه زیادی از فرآیندهای pmlogger(1) و حذف پیکربندی‌های pmlogger_check(1) آن‌ها طراحی شده است).
فایل خط‌مشی پیوندیافته به کلاس نمونه‌ای که قرار است نابود شود، ممکن است شامل یک بخش destroy باشد که می‌تواند بر انجام شدن یا نحوه انجام عملیات نابودی اثر بگذارد. این امر ممکن است به یک گزینه -p برای یافتن فایل خط‌مشی کلاس مربوطه نیاز داشته باشد.
بررسی خط‌مشی کلاس را می‌توان با استفاده از گزینه خط فرمان -f (اجبار) نادیده گرفت. یک فایل خط‌مشی کلاس شامل چندین بخش است؛ هر بخش با خطی آغاز می‌شود که نام بخش درون «[» و «]» در آن قرار گرفته است.
خطوطی که با علامت هش (#) آغاز می‌شوند به عنوان توضیح (comment) در نظر گرفته شده و نادیده گرفته می‌شوند. خطوط خالی یا سفید نیز نادیده گرفته می‌شوند.
مکان معمول فایل خط‌مشی برای کلاس foo مسیر $PCP_SYSCONF_DIR/pmlogger/class.d/foo است.
- [class]
- بخش اختیاری نام کلاس، کلاس را نام‌گذاری می‌کند. در صورت عدم وجود، نام فایل خط‌مشی (بدون هرگونه پیشوند دایرکتوری) به عنوان نام کلاس استفاده می‌شود.
- [ident]
- بخش ident الگویی را مشخص می‌کند که برای شناسه نمونه اختصاص‌یافته به هر عضو کلاس استفاده می‌شود. این شناسه باید در میان تمامی نمونه‌ها و تمام کلاس‌ها یکتا باشد و باید یک نام فایل معتبر در فایل‌سیستم محلی باشد، بنابراین معمولاً شامل نام کلاس و ماکروی %h خواهد بود، مانند foo-%h. هنگام ایجاد هر نمونه، این ماکرو با host جایگزین می‌شود.
- [control]
- بخش control شامل یک یا چند خط از متن الگو است که برای ایجاد فایل کنترل برای هر نمونه استفاده خواهد شد. این بخش حداقل باید شامل خط کنترل pmlogger_check(1) باشد تا نحوه راه‌اندازی فرایند pmlogger(1) مرتبط را مشخص کند؛ این خط شامل فیلدهایی است که با فاصله خالی (white space) به شرح زیر از هم جدا شده‌اند:
- 1.
- نام میزبان (hostname)، معمولاً ماکروی %h
- 2.
- n برای نشان دادن اینکه این یک نمونه غیر-اصلی (non-primary) است
- 3.
- پرچم «socks»، معمولاً n
- 4.
- دایرکتوری که در آن آرشیوهای pmlogger(1) ایجاد خواهند شد؛ این مسیر باید یکتا باشد و معمولاً با استفاده از ماکروی pmlogger_check(1) یعنی PCP_ARCHIVE_DIR به عنوان آغاز مسیر و به دنبال آن شناسه نمونه، معمولاً ماکروی %i، مشخص می‌شود؛ مانند PCP_ARCHIVE_DIR/%i
- 5.
- پارامترهای اضافی برای pmlogger(1) که احتمالاً حداقل شامل گزینه -c برای ارائه یک فایل پیکربندی است که مشخص می‌کند کدام معیارها باید برای نمونه‌های این کلاس ثبت شوند؛ این فایل ممکن است برای تمام نمونه‌های این کلاس یکسان باشد، یا ممکن است شامل ماکروی %i باشد تا برای هر نمونه از یک فایل پیکربندی متفاوت استفاده شود. توجه داشته باشید که اگر این فایل پیکربندی وجود نداشته باشد، اولین باری که pmlogger_check(1) اجرا شود، با استفاده از pmlogconf(1) ایجاد خواهد شد.
پیش از خط
کنترل باید
خطی وجود
داشته باشد
که نسخه خط
کنترلِ پس
از خود را
تعیین کند،
یعنی:
$version=1.1
اگر این خط
وجود
نداشته
باشد، pmlogctl
نسخه را 1.1
فرض کرده و
هنگام
ایجاد
نمونه این
خط را درج
می‌کند.
همچنین pmlogctl
نام کلاس را
هنگام
ایجاد
اضافه
خواهد کرد؛
مانند:
$class=foo
درون یک الگوی خط کنترل، شکل ساده‌ای از جایگزینی پارامتری پشتیبانی می‌شود. ماکروی ENV(spec) با متنی با استفاده از متغیرهای محیطی به شرح زیر جایگزین می‌شود:
- اگر spec به شکل var باشد، آن‌گاه از مقدار $var موجود در محیط استفاده می‌شود. اگر $var تعریف نشده باشد یا مقدار آن یک رشته خالی باشد، این یک خطا خواهد بود.
- اگر spec به شکل var:default باشد، در صورتی که $var موجود در محیط تعریف شده و رشته خالی نباشد، مقدار $var استفاده می‌شود؛ در غیر این صورت مقدار default به کار می‌رود. این جایگزینی ساده است، بنابراین هرگونه فاصله خالی میان : و ) در default لحاظ می‌شود، و default نمی‌تواند شامل ) باشد.
به عنوان
مثال:
# unset PMPROXY_PORT; PMPROXY_HOST=foobar.com pmlogctl create ...
همراه با یک
خط الگوی
کنترل کلاس
خط‌مشی که
شامل
http://ENV(PMPROXY_HOST):ENV(PMPROXY_PORT:44322)
باشد، یک خط
کنترل
تولید
خواهد کرد
که شامل
مورد زیر
است:
http://foobar.com:44322
- [create]
- بخش create شرایطی را تعریف می‌کند که پیش از ایجاد یک نمونه با دستور cond-create باید برقرار باشند. هدف این است که هنگام کشف یک میزبان جدید که pmcd(1) را اجرا می‌کند (مثلاً توسط pmfind(1))، امکان اتخاذ تصمیمات متفاوتی وجود داشته باشد.
هر خط غیرخالی در بخش create یک شرط به فرم function(arg) است که در آن function یکی از موارد زیر است:
- exists
- arg نام یک معیار عملکرد است و اگر آن معیار در فضای نام معیارهای عملکرد (PMNS) در میزبان دوردست وجود داشته باشد، exists به «درست» (true) ارزیابی می‌شود
- values
- arg نام یک معیار عملکرد در PMNS دوردست است و در صورتی که نمونه‌ای از آن معیار مقداری در میزبان دوردست داشته باشد، values به «درست» (true) ارزیابی می‌شود
- condition
- arg یک عبارت معیار مشتق‌شده در قالب پشتیبانی‌شده توسط pmRegisterDerived(3) است، و اگر مقدار آن عبارت در میزبان دوردست بزرگ‌تر از صفر باشد، condition به «درست» (true) ارزیابی می‌شود
- hostname
- arg یک عبارت باقاعده به سبک egrep(1) است و اگر نام میزبان دوردست با arg تطابق داشته باشد، hostname به «درست» (true) ارزیابی می‌شود [destroy] بخش destroy خط‌مشی‌ای را تعیین می‌کند که هنگام از بین رفتن یک نمونه اعمال می‌شود.
هدف این است که وقتی سرویس اکتشاف، برای نمونه pmfind(1), متوجه می‌شود میزبانی که با یک نمونه مرتبط است دیگر وجود ندارد، امکان اتخاذ تصمیم‌های متفاوتی فراهم شود. اما در نسخه کنونی این قابلیت پیاده‌سازی نشده است و نحو و معناشناسی بخش destroy هنوز تعریف نشده است.
یک نمونه فایل خط‌مشی کلاس به صورت زیر است:
# policy file for the foo class [class] foo [ident] foo-%h [control] $version=1.1 %h n n PCP_ARCHIVE_DIR/%i -c foo-metrics.config [create] # matches all hosts hostname(.*) [destroy] # still to be defined
گزینه‌ها (OPTIONS)
گزینه‌های موجود در خط فرمان عبارتند از:
- -a, --all
- اعمال عملیات بر روی تمام نمونه‌های منطبق. به‌طور پیش‌فرض تنها یک تعریف نمونه مورد انتظار است و روی آن اقدام می‌شود.
- -c class, --class=class
- تنظیم نام کلاسی که نمونه‌های pmlogger(1) به آن تعلق دارند به عنوان class.
- -C check_args, --checkargs=check_args
- check_args شامل آرگومان‌های خط فرمان اضافی برای pmlogger_check(1) در زمان فراخوانی آن است. این مورد بیش از همه برای گزینه‌هایی مانند -V کاربرد دارد. می‌توان از چندین گزینه -C استفاده کرد و گزینه‌های مختلف check_args انباشته شده و همگی به pmlogger_check(1) ارسال می‌شوند.
- -f, --force
- اجبار به انجام عملیات در صورت امکان.
- -i ident, --ident=ident
- بازنویسی شناسه نمونه با ident. این گزینه تنها برای دستورهای create و cond-create اعمال می‌شود.
- -N, --showme
- اجرای pmlogctl در حالت «show me» یا «dry run» (آزمایشی) که در آن مقصود دستور نشان داده می‌شود، اما هیچ تغییری اعمال نمی‌گردد.
- -m, --migrate
- هنگام استفاده همراه با دستورهای create یا check در پلتفرم‌های systemd(1)، فرایندهای جدید یا موجود غیر اصلی pmlogger را نیز به سرویس pmlogger_farm منتقل می‌کند. این کار معمولاً به صورت خودکار توسط سرویس pmlogger_farm_check انجام می‌شود که مبتنی بر تایمر است (بنابراین ممکن است پیش از آغاز انتقال خودکار، چند دقیقه تاخیر وجود داشته باشد).
- -p policy, --policy=policy
- استفاده از policy به عنوان فایل خط‌مشی کلاس. مقدار پیش‌فرض آن $PCP_SYSCONF_DIR/pmlogger/class.d/<class> است.
- -V, --verbose
- فعال‌سازی حالت پرگو (verbose). استفاده دوباره از این گزینه میزان جزئیات خروجی را افزایش می‌دهد. خروجی پرگو در stderr نوشته می‌شود.
- -?, --help
- نمایش پیام نحوه استفاده و خروج.
محیط PCP (PCP ENVIRONMENT)
متغیرهای محیطی با پیشوند PCP_ برای پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورد استفاده PCP به کار می‌روند. در هر نصب، فایل /etc/pcp.conf حاوی مقادیر محلی برای این متغیرها است. متغیر $PCP_CONF می‌تواند برای مشخص کردن یک فایل پیکربندی جایگزین، همان‌طور که در pcp.conf(5) شرح داده شده است، استفاده شود.
همچنین ببینید (SEE ALSO)
egrep(1), init(1), PCPIntro(1), pmcd(1), pmlc(1), pmlogconf(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), systemd(1), PMAPI(3), pmDerivedRegister(3) و pcp.conf(5).
| PCP | Performance Co-Pilot |