نام (NAME)

pmiectl - مدیریت و کنترل موتورهای استنتاج Performance Co-Pilot

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

pmiectl [-afmNV?] [-C check_args] [-c class] [-i ident] [-p policy] command [host ...]

توضیحات (DESCRIPTION)

pmiectl می‌تواند برای مدیریت نمونه‌های غیر اصلی موتور استنتاج Performance Co-Pilot (PCP) یعنی pmie(1) به کار رود. این کاربرد بیشتر در یک «مزرعه» (farm) از موتورهای استنتاج PCP مطرح می‌شود، جایی که نمونه‌های متعددی از pmie(1) قوانین را در برابر داده‌های کارایی جمع‌آوری‌شده از pmcd(1) روی چندین میزبان راه دور ارزیابی می‌کنند.

نمونهٔ اصلی pmie(1) پیوند نزدیکی با فرایند محلی pmcd(1) دارد و در نتیجه از همان زیرساخت کنترلی، یعنی systemd(1) یا «اسکریپت‌های rc» در init(1) مربوط به PCP استفاده می‌کند. به همین دلیل، نمونهٔ اصلی pmie(1) را نمی‌توان با pmiectl مدیریت کرد.

برای رعایت اختصار در توضیحات زیر، واژهٔ «نمونه» به معنای نمونه‌ای از pmie(1) است.

تمام نمونه‌های مدیریت‌شده توسط pmiectl، pmie_check(1) و pmie_daily(1) از قوانین زیر پیروی می‌کنند:

1.: هر نمونه، داده‌های کارایی را از یک pmcd(1) واحد (یعنی یک میزبان) واکشی می‌کند، اما هر pmcd(1) ممکن است داده‌های کارایی را به صفر، یک یا چند فرایند pmie(1) در حال اجرا روی یک یا چند میزبان ارائه دهد.
2.: روی میزبان محلی، هر نمونهٔ pmie(1) باید یک‌بار در یک فایل کنترلی pmie_check(1) مشخص شود و pmie(1) یک فایل گزارش یکتا ایجاد می‌کند که در چهارمین پارامتر ورودیِ فایل کنترلی مربوطه نام‌گذاری شده است (بخش CONFIGURATION در pmie_check(1) را ببینید).
3.: هر نمونه دقیقاً متعلق به یک class (کلاس) است که می‌تواند به صورت اختیاری با استفاده از مقداردهی $class=... در فایل کنترلی مربوطه نام‌گذاری شود. کلاس ویژهٔ default برای تمام نمونه‌هایی رزرو شده است که مقداردهی $class=... مرتبطی ندارند. برای مقاصد گزارش‌گیری (به دستور summary در زیر مراجعه کنید)، نمونهٔ اصلی pmie(1) به طور خودکار به کلاس ویژهٔ primary اختصاص داده می‌شود.

هر بار اجرای pmiectl یک یا چند نمونه را با به‌روزرسانی فایل‌های کنترلی مرتبط و سپس اجرای pmie_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 وجود داشته باشد..PP با توجه به وظایفی که pmiectl بر عهده دارد، معمولاً باید به عنوان کاربر ریشه («root») اجرا شود؛ به استثنای دستور status یا زمانی که گزینهٔ -N مشخص شده باشد.

دستورها (COMMANDS)

command یکی از موارد زیر است:

check: وضعیت تمام نمونه‌های پیکربندی‌شدهٔ کنونی pmie را بررسی کرده و هرکدام را که با شکست مواجه شده باشد، بازراه‌اندازی می‌کند. اگر پرچم -m روی بسترهای systemd(1) مشخص شده باشد، فرآیندهای منطبق (و جدید) را نیز به سرویس pmie_farm منتقل می‌کند.
create: ایجاد نمونه‌های جدید در کلاس classname (به‌طور پیش‌فرض default) برای میزبان‌های host. نام کلاس برای شناسایی فایل خط‌مشی کلاس استفاده می‌شود (بخش CLASS POLICY FILE در زیر را ببینید) که قالبی برای هر فایل کنترل جدید فراهم می‌کند؛ به طوری که %h با host و %i با شناسهٔ (یکتای) نمونه برگرفته از بخش ident فایل خط‌مشی کلاس یا ident از گزینهٔ -i جایگزین می‌شود.

گزینهٔ -p می‌تواند برای مشخص کردن فایل خط‌مشی کلاسی غیر از فایل موجود در مکان استاندارد استفاده شود، یعنی $PCP_SYSCONF_DIR/pmie/class.d/classname.

حداقل یک host باید برای دستور create مشخص گردد.

cond-create: مشابه create است، اما نمونه تنها در صورتی ایجاد خواهد شد که یکی از شروط موجود در بخش create در فایل(های) خط‌مشی کلاس مربوطه، درست (true) ارزیابی شود.

اگر گزینهٔ -c مشخص شده باشد، تنها کلاس classname در نظر گرفته می‌شود، در غیر این صورت تمام کلاس‌ها بررسی خواهند شد. در حالت دوم، اگر هیچ‌یک از شروط موجود در هر یک از کلاس‌ها درست ارزیابی نشود، کلاس ویژهٔ pmfind استفاده می‌شود (این کلاس، کلاس «پیش‌فرض» برای دستور cond-create هنگام به نتیجه نرسیدن سایر موارد است).

اگر بیش از یک کلاس درست ارزیابی شود، یک فایل پیکربندی ترکیبی pmie(1) ایجاد می‌شود و نمونه به کلاس ویژهٔ pmfind نیز اختصاص می‌یابد. فایل پیکربندی ترکیبی ممکن است شامل ترکیبی از بندهای پیکربندی صریح و بندهای پیکربندی شرطی کلی‌تر، آن‌طور که توسط ابزار pmieconf(1) پشتیبانی می‌شود، باشد.

start: مجموعه نمونه‌های هدف را راه‌اندازی می‌کند.

اگر مجموعهٔ هدف عمداً شامل بیش از یک نمونه باشد، در این صورت باید از گزینهٔ -a استفاده شود (این کار برای کاهش خطر راه‌اندازی تصادفی تعداد بالقوه زیادی از فرآیندهای pmie(1) طراحی شده است).

اگر نمونه‌ای در مجموعهٔ هدف از قبل راه‌اندازی شده باشد، هیچ تغییری ایجاد نمی‌شود (برای واداشتن نمونه‌های جدید به اجرا، دستور restart را ببینید).

stop: مجموعه نمونه‌های هدف را متوقف می‌کند.

اگر مجموعهٔ هدف عمداً شامل بیش از یک نمونه باشد، در این صورت باید از گزینهٔ -a استفاده شود (این کار برای کاهش خطر متوقف کردن تصادفی تعداد بالقوه زیادی از فرآیندهای pmie(1) طراحی شده است).

اگر نمونه‌ای در مجموعهٔ هدف از قبل متوقف شده باشد، هیچ تغییری ایجاد نمی‌شود اما یک هشدار صادر خواهد شد.

restart: مجموعه نمونه‌های هدف را متوقف کرده و سپس راه‌اندازی می‌کند.

اگر مجموعهٔ هدف عمداً شامل بیش از یک نمونه باشد، در این صورت باید از گزینهٔ -a استفاده شود (این کار برای کاهش خطر متوقف کردن و راه‌اندازی تصادفی تعداد بالقوه زیادی از فرآیندهای pmie(1) طراحی شده است).

اگر نمونه‌ای در مجموعهٔ هدف از قبل متوقف شده باشد، پیش از راه‌اندازی نمونه یک هشدار صادر می‌شود.

status: وضعیت مجموعه نمونه‌های هدف را گزارش می‌کند. اگر هیچ گزینهٔ -c و هیچ آرگومان host مشخص نشده باشد، یعنی مجموعهٔ هدف خالی باشد، وضعیت تمام نمونه‌ها گزارش خواهد شد.
destroy: نابود کردن مجموعه نمونه‌های هدف. در پایان این عملیات، فرآیندهای pmie(1) مرتبط متوقف شده و اطلاعات فایل کنترل مربوطه حذف خواهد شد.

اگر مجموعهٔ هدف عمداً شامل بیش از یک نمونه باشد، در این صورت باید از گزینهٔ -a استفاده شود (این کار برای کاهش خطر پایان دادن تصادفی به تعداد بالقوه زیادی از فرآیندهای pmie(1) و حذف پیکربندی‌های pmie_check(1) آن‌ها طراحی شده است).

فایل خط‌مشی پیوندیافته به کلاس نمونه‌ای که قرار است نابود شود، ممکن است شامل یک بخش destroy باشد که می‌تواند بر اینکه آیا و چگونه عملیات نابودسازی انجام شود اثر بگذارد. این کار ممکن است برای یافتن فایل خط‌مشی کلاس مربوطه به گزینهٔ -p نیاز داشته باشد. بررسی خط‌مشی کلاس را می‌توان با استفاده از گزینهٔ خط فرمان -f (اجبار یا force) نادیده گرفت.

فایل خط‌مشی کلاس (CLASS POLICY FILE)

یک فایل خط‌مشی کلاس شامل تعدادی بخش است، هر بخش با خطی آغاز می‌شود که به‌سادگی با نام بخش محصور در «[» و «]» شروع می‌شود.

خطوطی که با علامت هش (#) شروع می‌شوند به عنوان توضیح (کامنت) در نظر گرفته شده و نادیده گرفته می‌شوند. خطوط خالی یا سفید نیز نادیده گرفته می‌شوند.

مکان معمول فایل خط‌مشی برای کلاس foo برابر است با $PCP_SYSCONF_DIR/pmie/class.d/foo.

[class]: بخش اختیاری نام کلاس، کلاس را نام‌گذاری می‌کند. اگر این بخش وجود نداشته باشد، نام فایل خط‌مشی (بدون هیچ‌گونه پیشوند دایرکتوری) به عنوان نام کلاس استفاده می‌شود.
[ident]: بخش ident الگویی را مشخص می‌کند که باید برای شناسهٔ نمونهٔ اختصاص‌یافته به هر عضو از کلاس استفاده شود. این شناسه باید در میان تمام نمونه‌ها و تمام کلاس‌ها یکتا باشد، و همچنین باید یک نام فایل معتبر در فایل‌سیستم محلی باشد، بنابراین معمولاً شامل نام کلاس و ماکروی %h خواهد بود، برای مثال foo-%h. هنگام ایجاد هر نمونه، این ماکرو با host جایگزین می‌شود.
[control]: بخش control شامل یک یا چند خط از متن الگو است که برای ایجاد فایل کنترل برای هر نمونه استفاده خواهد شد. این بخش باید دست‌کم شامل خط کنترل pmie_check(1) باشد تا نحوهٔ اجرای فرایند pmie(1) مرتبط را مشخص کند؛ این خط شامل فیلدهایی است که با فاصلهٔ خالی (whitespace) به شرح زیر از یکدیگر جدا شده‌اند:

1.: نام میزبان، معمولاً ماکروی %h
2.: n برای نشان دادن اینکه این یک نمونهٔ غیر اصلی (non-primary) است
3.: پرچم «socks»، معمولاً n
4.: مسیر فایل مورد استفاده توسط pmie(1) برای فایل لاگ؛ این مسیر باید یکتا باشد و معمولاً با استفاده از ماکروی pmie_check(1) یعنی PCP_LOG_DIR به عنوان ابتدای مسیر مشخص می‌شود، به دنبال آن pmie، و سپس دایرکتوری یکتای نمونه %i، برای مثال PCP_LOG_DIR/pmie/%i/pmie.log
5.: پارامترهای اضافی برای pmie(1) که احتمالاً دست‌کم شامل یک گزینهٔ -c برای ارائهٔ یک فایل پیکربندی است که مشخص می‌کند چه قوانینی باید برای نمونه‌های این کلاس ارزیابی شوند؛ این مقدار ممکن است برای تمام نمونه‌ها در این کلاس یکسان باشد، یا ممکن است شامل ماکروی %i باشد تا برای هر نمونه از فایل پیکربندی متفاوتی استفاده شود. توجه داشته باشید که اگر این فایل پیکربندی وجود نداشته باشد، در اولین باری که pmie_check(1) اجرا شود، با استفاده از pmieconf(1) ایجاد خواهد شد.

پیش از خط کنترل، باید خطی وجود داشته باشد که نسخهٔ خط کنترل پس از آن را مشخص کند، یعنی:
$version=1.1
اگر این خط وجود نداشته باشد، pmiectl فرض می‌کند که نسخه 1.1 است و هنگام ایجاد نمونه این خط را درج می‌کند.

همچنین pmiectl نام کلاس را هنگام ایجاد اضافه خواهد کرد. برای مثال:
$class=foo

درون یک الگوی خط کنترل، شکل ساده‌ای از جایگزینی پارامتری پشتیبانی می‌شود. ماکروی ENV(spec) با استفاده از متغیرهای محیطی به شرح زیر با متن جایگزین می‌شود:

اگر spec به فرم var باشد، مقدار $var از محیط استفاده می‌شود. اگر $var تعریف نشده باشد یا مقدار آن یک رشتهٔ خالی باشد، این یک خطا محسوب می‌شود.
اگر spec به فرم var:default باشد، در این صورت اگر $var از محیط تعریف شده باشد و رشتهٔ خالی نباشد، مقدار $var استفاده می‌شود؛ در غیر این صورت مقدار default به کار می‌رود. این جایگزینی ساده است، بنابراین هرگونه فاصلهٔ سفید میان : و ) در default لحاظ می‌شود، و default نمی‌تواند شامل یک ) باشد.

به عنوان مثال:
# unset PMPROXY_PORT; PMPROXY_HOST=foobar.com pmiectl 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) ارزیابی می‌شود.TP 4n values arg نام یک سنجهٔ کارایی در PMNS راه دور است و values در صورتی به «درست» ارزیابی می‌شود که نمونه‌ای از آن سنجه روی میزبان راه دور مقداری داشته باشد
condition: arg یک عبارت سنجهٔ مشتق‌شده در قالب پشتیبانی‌شده توسط pmRegisterDerived(3) است، و condition در صورتی به «درست» ارزیابی می‌شود که مقدار آن عبارت روی میزبان راه دور بزرگ‌تر از صفر باشد
hostname: arg یک عبارت باقاعده به شیوهٔ egrep(1) است و hostname در صورتی به «درست» ارزیابی می‌شود که نام میزبان راه دور با arg مطابقت داشته باشد

[destroy]: بخش destroy سیاستی را تعیین می‌کند که هنگام نابود شدن یک نمونه اعمال می‌شود.

هدف این است که وقتی سرویس اکتشاف، مانند pmfind(1)، متوجه می‌شود میزبانی که به یک نمونه مرتبط است دیگر حضور ندارد، امکان اتخاذ تصمیمات متفاوتی فراهم شود. اما در نسخهٔ فعلی این قابلیت پیاده‌سازی نشده است و نحو و معناشناسی بخش destroy هنوز تعریف نشده است.

یک نمونه فایل سیاست کلاس به صورت زیر است:

# policy file for the foo class
[class]
foo
[ident]
foo-%h
[control]
$version=1.1
%h n n PCP_LOG_DIR/pmie/%i/pmie.log -c foo-metrics.config
[create]
# matches all hosts
hostname(.*)
[destroy]
# still to be defined

گزینه‌ها (OPTIONS)

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

-a, --all: اعمال عملیات روی تمامی نمونه‌های منطبق. به‌طور پیش‌فرض تنها انتظار یک تعریف نمونه می‌رود و بر اساس آن اقدام می‌شود.
-c class, --class=class: تنظیم نام کلاسی که نمونه‌های pmie(1) به آن تعلق دارند به class.
-C check_args, --checkargs=check_args: check_args آرگومان‌های خط فرمان اضافی برای pmie_check(1) در هنگام فراخوانی آن هستند. این گزینه بیش از همه برای گزینه‌هایی مانند -V مفید است. می‌توان از چندین گزینهٔ -C استفاده کرد و گزینه‌های مختلف check_args تجمیع شده و همگی به pmie_check(1) ارسال خواهند شد.
-f, --force: اجبار به انجام عملیات در صورت امکان.
-i ident, --ident=ident: جایگزین کردن شناسهٔ نمونه با ident. این گزینه فقط برای دستورهای create و cond-create اعمال می‌شود.
-N, --showme: اجرای pmiectl در حالت «به من نشان بده» (show me) یا «اجرای آزمایشی» (dry run) که در آن مقصود دستور نمایش داده می‌شود، اما هیچ تغییری اعمال نمی‌گردد.
-m, --migrate: هنگام استفاده با دستورهای create یا check در پلتفرم‌های systemd(1)، همچنین فرایندهای pmie غیراصلی جدید یا موجود را به سرویس pmie_farm مهاجرت می‌دهد. این کار معمولاً به‌طور خودکار توسط سرویس pmie_farm_check انجام می‌شود، که مبتنی بر زمان‌سنج است (بنابراین ممکن است قبل از شروع مهاجرت خودکار، چند دقیقه تأخیر وجود داشته باشد).
-p policy, --policy=policy: استفاده از policy به‌عنوان فایل سیاست کلاس. پیش‌فرض برابر با $PCP_SYSCONF_DIR/pmie/class.d/<class> است.
-V, --verbose: فعال‌سازی حالت پرگو. استفاده از این گزینه برای دو بار، میزان پرگویی را افزایش می‌دهد. خروجی پرگو در stderr نوشته می‌شود.
-?, --help: نمایش پیام راهنمای استفاده و خروج..SH "محیط PCP (PCP ENVIRONMENT)" متغیرهای محیطی با پیشوند PCP_ برای تعیین پارامتریک نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند. در هر نصب، فایل /etc/pcp.conf شامل مقادیر محلی برای این متغیرها است. متغیر $PCP_CONF می‌تواند برای مشخص کردن یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در pcp.conf(5) شرح داده شده است.

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

egrep(1), init(1), PCPIntro(1), pmcd(1), pmieconf(1), pmie(1), pmie_check(1), pmie_daily(1), systemd(1), PMAPI(3), pmDerivedRegister(3) و pcp.conf(5).