نام (NAME)

pmlc - پیکربندی تعاملی pmloggerهای فعال Performance Co-Pilot

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

pmlc [-eiPz?] [-D debug] [-h host] [-n pmnsfile] [-p port] [-Z timezone] [pid]

توضیحات (DESCRIPTION)

pmlc می‌تواند برای تغییر آن دسته از معیارها و نمونه‌هایی که یک pmlogger(1) در یک بایگانی Performance Co-Pilot می‌نویسد (ببینید PCPIntro(1))، بسامد جمع‌آوری معیارها، و همچنین اجباری، توصیه‌ای، روشن یا خاموش بودن ثبت گزارش استفاده شود. این دستور همچنین وضعیت فعلی ثبت گزارش معیارها و نمونه‌ها را گزارش می‌دهد. pmlc می‌تواند برای کنترل نمونه‌های pmlogger در میزبان‌های دوردست و همچنین در میزبان محلی به کار رود.

در حالت عادی pmlc بر روی فضای نام توزیع‌شده معیارهای کارایی (PMNS) عمل می‌کند؛ اما اگر گزینهٔ -n مشخص شود، یک PMNS محلی جایگزین از فایل pmnsfile بارگذاری می‌شود.

اگر گزینهٔ -P مشخص شود، pmlc تلاش خواهد کرد تا با اتصال به pmlogger اصلی در میزبان محلی شروع به کار کند. اگر گزینهٔ -p مشخص شود، آنگاه pmlc تلاش خواهد کرد تا با اتصال به pmlogger در این port از نوع TCP/IP شروع به کار کند. همچنین، اگر pid مشخص شود، در هنگام راه‌اندازی برای اتصال به نمونهٔ pmlogger با آن شناسهٔ فرایند تلاش خواهد شد. گزینهٔ -h تنها زمانی می‌تواند استفاده شود که -P، -p port یا یک pid نیز مشخص شده باشد. در آن حالت، pmlc در ابتدا به جای میزبان محلی، به نمونهٔ pmlogger مشخص‌شده (از راه دور) در host متصل خواهد شد. اگر اتصال به نمونهٔ pmlogger مشخص‌شده برقرار نشود، pmlc بدون هیچ اتصالی شروع به کار خواهد کرد. این گزینه‌ها معمولاً به شما اجازه می‌دهند تا با تغییر آرگومان‌های خط فرمان، همان فایل حاوی دستورات pmlc را به چندین نمونهٔ pmlogger هدایت کنید. توجه داشته باشید که -P، -p port، pid و -h تنها هنگام برقراری اتصال اولیه به یک نمونهٔ pmlogger استفاده می‌شوند. اگر اتصالات بعدی به صورت تعاملی برقرار شوند، این گزینه‌ها به عنوان پیش‌فرض استفاده نخواهند شد (دستور connect را در ادامه ببینید).

به‌طور پیش‌فرض، pmlc زمان روز را بر اساس منطقه زمانی محلی سیستمی که pmlc روی آن اجرا می‌شود گزارش می‌کند. گزینهٔ -Z منطقه زمانی را به timezone در قالب متغیر محیطی TZ طبق آنچه در environ(7) شرح داده شده است تغییر می‌دهد. گزینهٔ -z منطقه زمانی را به منطقه زمانی نمونهٔ pmlogger که اطلاعات از آن دریافت می‌شود تغییر می‌دهد. تنها یکی از گزینه‌های -z یا -Z می‌تواند مشخص شود.

اگر ورودی استاندارد از یک tty باشد، pmlc به همراه اعلان‌ها به صورت تعاملی خواهد بود. پرچم -i می‌تواند برای اجبار رفتار تعاملی استفاده شود و معمولاً در ترکیب با -e به کار می‌رود تا تمام ورودی‌های دستور را در خروجی استاندارد بازتاب دهد (echo کند)..SH "دستورها (COMMANDS)" دستورهای زیر را می‌توان استفاده کرد:

show [ loggers ] [ @host ]: شناسه‌های فرایند (PID) تمام نمونه‌های pmlogger در حال اجرا روی میزبان محلی (یا host، در صورت مشخص شدن) را نمایش می‌دهد. شناسه فرایند pmlogger اصلی (primary) درون پرانتز قرار می‌گیرد، زیرا علاوه بر PID می‌توان با عنوان «primary» نیز به آن ارجاع داد.
connect pid [ @host ]: connect primary [ @host ]
ابزار pmlc را به فرایند pmlogger مشخص‌شده متصل می‌کند. هرگونه اتصال موجود به یک نمونه pmlogger ابتدا بسته می‌شود. هر نمونه pmlogger در هر لحظه حداکثر یک اتصال را می‌پذیرد، بنابراین اگر اتصال با موفقیت برقرار شود، pmlc شما تنها برنامه‌ای خواهد بود که نمونه pmlogger متصل‌شده را کنترل می‌کند.
new volume: این دستور تنها زمانی کار می‌کند که اتصال به یک نمونه pmlogger برقرار باشد. این دستور به pmlogger اعلام می‌کند که جلد (volume) فعلی بایگانی را ببندد و یک جلد جدید باز کند. جلدهای بسته‌شده را می‌توان فشرده‌سازی کرد و/یا به یک سیستم دوردست، فضای ذخیره‌سازی از راه دور یا ذخیره‌سازی آفلاین منتقل نمود؛ مثلاً به عنوان بخشی از یک رویه منظم مدیریت بایگانی برای کنترل اندازه فایل‌های فیزیکی بایگانی روی سیستمی که pmlogger روی آن در حال اجرا است.
status: این دستور تنها زمانی کار می‌کند که اتصال به یک نمونه pmlogger برقرار باشد. اطلاعاتی را درباره وضعیت نمونه pmlogger و بایگانی مرتبط با آن چاپ می‌کند.
timezone local | logger | "timezone": این دستور منطقه زمانی مورد استفاده هنگام چاپ زمان‌ها را تعیین می‌کند. local به معنای استفاده از منطقه زمانی سیستمی است که pmlc روی آن اجرا می‌شود. logger به معنای استفاده از منطقه زمانی سیستمی است که نمونه pmlogger روی آن در حال اجرا است. همچنین می‌توان یک timezone صریح را درون گیومه مشخص کرد (برای جزئیات به TZ در environ(7) مراجعه کنید). منطقه زمانی پیش‌فرض local است مگر اینکه یکی از گزینه‌های -z یا -Z در خط فرمان مشخص شده باشد.
flush: این دستور تنها زمانی کار می‌کند که اتصال به یک نمونه pmlogger برقرار باشد، و از نمونه pmlogger درخواست می‌کند تا تمام بافرهای مرتبط با بایگانی فعلی را روی دیسک تخلیه کند. برای کاربران قدیمی، sync مترادفی برای flush است. در نسخه‌های فعلی pmlogger(1) تمام عملیات نوشتن بدون بافر بوده و با رکوردهای منطقی در فایل‌های خارجی هم‌تراز هستند، بنابراین این دستور عملاً کاری انجام نمی‌دهد، اما برای سازگاری با نسخه‌های پیشین حفظ شده است.
disconnect: قطع اتصال pmlc از نمونه فعلی pmlogger (در صورت وجود).
sleep delay: ایجاد وقفه در pmlc به مدت delay میلی‌ثانیه. این دستور ممکن است در کاربردهای اسکریپتی از pmlc مفید باشد تا به نمونه فعلی pmlogger فرصت پیشبرد درخواست‌های اخیر پیش از استعلام وضعیت داده شود.
help: خلاصه‌ای از دستورهای موجود را نمایش می‌دهد.
h و ? مترادف‌هایی برای help هستند.
quit: خروج از pmlc.

دستورهای باقی‌مانده، وضعیت ثبت گزارش (logging state) متریک‌ها و نمونه‌ها را پرس‌وجو کرده و تغییر می‌دهند. این دستورها تنها در صورتی کار خواهند کرد که pmlc اتصالی به یک نمونه pmlogger داشته باشد. متریک‌ها ممکن است به صورت نام‌های کامل (مانند hinv.ncpu) یا زیردرخت‌هایی از PMNS (مانند hinv) مشخص شوند که گسترش یافته تا شامل تمام متریک‌های آن زیردرخت شوند (مانند hinv.ncpu، hinv.cpuclock و غیره). فهرست‌های متریک‌ها را می‌توان با قرار دادن آن‌ها درون آکولاد به همراه فاصله یا کاما میان متریک‌ها مشخص کرد (مانند {hinv.ncpu hinv.ndisk}). زیردرخت‌های متریک‌ها نیز می‌توانند در چنین فهرست‌هایی گنجانده شوند.

هر مشخصه متریک فردی می‌تواند با فهرستی از نمونه‌ها در کروشه که با فاصله یا کاما جدا شده‌اند، دقیق‌تر مشخص شود (مانند kernel.all.load["1 minute", "5 minute"]). نام‌های خارجی نمونه‌ها یا شناسه‌های عددی داخلی نمونه‌ها یا هر دو ممکن است در یک فهرست به کار روند (مانند sample.colour.[red,1,"blue"]). اگر تعیین یک نمونه روی زیردرختی از PMNS اعمال شود، تمام متریک‌های آن زیردرخت باید دارای دامنه نمونه (instance domain) یکسانی باشند. تعیین نمونه نمی‌تواند روی کل فهرست‌های متریک اعمال شود اما می‌تواند درون این فهرست‌ها بیاید.

اگر هیچ نمونه‌ای برای یک متریک مشخص نشود، همه نمونه‌ها استفاده می‌شوند. «همه نمونه‌ها» یعنی تمام نمونه‌های موجود در زمانی که نمونه pmlogger مربوطه متریک‌ها را برای ثبت واکشی می‌کند. اگر یک دامنه نمونه با گذشت زمان تغییر کند، این وضعیت همواره با مجموعه نمونه‌های نمایش‌یافته توسط pmlc یکسان نخواهد بود، چرا که تنها نمونه‌های در دسترس فعلی را نمایش می‌دهد. برای جلوگیری از خطاهای ناخواسته، تنها نمونه‌هایی که در حال حاضر برای pmlc در دسترس هستند می‌توانند در مشخصات نمونه قید شوند.

query metriclist

وضعیت ثبت فعلی هر متریک (و نمونه‌ها، در صورت کاربرد) در metriclist نمایش داده می‌شود. این شامل وضعیت ثبت (مانند on، maybe، off) و بازه زمانی ثبت گزارش برای هر متریک (و نمونه) درخواست‌شده است. اختصارات زیر مربوط به متریک‌ها (و نمونه‌ها) ممکن است در خروجی ظاهر شوند: adv، توصیه‌ای (advisory)؛ mand، اجباری (mandatory)؛ nl، ثبت‌نشده (در بایگانی موجود نیست)؛ na، در بایگانی موجود است اما در حال حاضر از Performance Metrics Domain Agent (PMDA) مربوط به آن در دسترس نیست. در صورت لزوم، نام یک نمونه در انتهای سطر قرار گرفته و شناسه عددی داخلی نمونه پیش از آن می‌آید.

[ log ] mandatory on interval metriclist

این شکل از دستور log ثبت گزارش را برای متریک‌ها (و هر نمونه‌ای) در metriclist فعال می‌کند. interval مشخص می‌کند که متریک‌ها/نمونه‌های مشخص‌شده هر چند وقت یک‌بار باید ثبت شوند. once نشان می‌دهد که متریک‌ها/نمونه‌ها باید حداکثر یک بار در بایگانی ظاهر شوند. اغلب از کلمه کلیدی اختیاری every به همراه یک عدد مثبت و یکی از واحدهای millisecond (یا msec)، second (یا sec)، minute (یا min)، hour یا صورت جمع آن‌ها استفاده می‌شود.

توجه داشته باشید کلمه کلیدی default که ممکن است برای interval پیش‌فرض در یک فایل پیکربندی pmlogger(1) استفاده شود، در pmlc قابل استفاده نیست.

محدودیت‌های داخلی مستلزم آن است که interval کمتر از (تقریباً) ۷۴ ساعت باشد. مقدار صفر برای interval مترادفی برای once است..TP 4 [ log ] mandatory off metriclist این دستور به نمونه‌ی pmlogger اعلام می‌کند که هیچ‌یک از معیارها/نمونه‌های موجود در metriclist را بایگانی نکند.

[ log ] mandatory maybe metriclist

این دستور به نمونه‌ی pmlogger اعلام می‌کند که به هرگونه درخواست‌های بعدی ثبت وقایع توصیه‌ای (advisory logging) برای معیارها/نمونه‌های موجود در metriclist ترتیب اثر دهد. اگر وضعیت کنونی ثبت وقایع معیارها/نمونه‌ها اجباری (mandatory، چه on یا off) باشد، وضعیت جدید روی maybe تنظیم می‌شود (که عملاً معادل advisory off است). اگر وضعیت کنونی معیارها/نمونه‌ها از قبل توصیه‌ای (advisory، چه on یا off) باشد، وضعیت(های) معیارها/نمونه‌ها همان‌گونه که هستند باقی خواهند ماند.

[ log ] advisory on interval metriclist

[ log ] advisory off metriclist
ثبت وقایع توصیه‌ای تنها زمانی قابل‌اعمال است که آخرین وضعیت ثبت تعیین‌شده برای یک معیار/نمونه “mandatory maybe” بوده باشد (که کنترل ثبت توصیه‌ای بعدی را مجاز می‌کند) یا اینکه وضعیت ثبت از قبل توصیه‌ای باشد. این دو عبارت به‌ترتیب ثبت وقایع توصیه‌ای را برای معیارها/نمونه‌های مشخص‌شده روشن (on) یا خاموش (off) می‌کنند.

تفسیر interval همانند حالت mandatory در بالا است.

برای دستوراتی که در چند خط امتداد می‌یابند، نیازی به نویسه ادامه‌دهنده نیست.

کلمه at می‌تواند به‌صورت جایگزین با @ به‌کار رود.

درخواست بایگانی تمام نمونه‌های یک معیار، بر هرگونه درخواست قبلی برای ثبت تمام یا نمونه‌های خاصی از یک معیار اولویت داشته و جایگزین آن می‌شود (در صورتی که درخواست، یک گذار مجاز را در وضعیت ثبت مشخص کند). درخواست برای بایگانی نمونه‌های خاصی از یک معیار زمانی که تمام نمونه‌های آن معیار از قبل در حال ثبت باشند، توسط pmlogger رد می‌شود.

گزینه‌ها (OPTIONS)

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

-e, --echo: بازتاب تمام ورودی‌های دستور در خروجی استاندارد.
-h host, --host=host: اتصال به pmlogger روی host، به‌جای localhost پیش‌فرض.
-i, --interactive: اجبار به رفتار تعاملی.
-n pmnsfile, --namespace=pmnsfile: بارگذاری یک فضای نام معیارهای کارایی جایگزین (PMNS(5)) از فایل pmnsfile.
-p port, --port=port: اتصال به pmlogger اصلی روی درگاه TCP/IP به شماره port.
-P, --primary: اتصال به pmlogger اصلی.
-z, --logzone: استفاده از زمان محلی pmlogger به‌عنوان منطقه زمانی گزارش‌دهی.
-Z timezone, --timezone=timezone: استفاده از timezone برای تاریخ و زمان. Timezone در قالب متغیر محیطی TZ است همان‌طور که در environ(7) شرح داده شده است.
-?, --help: نمایش پیام راهنمای استفاده و خروج.

کنترل دسترسی (ACCESS CONTROL)

pmlc ممکن است دسترسی و کنترل محدودی بر فرایندهای pmlogger(1) داشته باشد.

اگر یک pmlogger(1) نتواند اطلاعات کنترلی خود را به pmcd(1) محلی صادر کند، آنگاه امکان اتصال به آن pmlogger(1) یا کنترل آن توسط pmlc وجود نخواهد داشت. در عمل، این بدان معناست که مالکیت فرایند pmlogger(1) باید متعلق به کاربر “pcp” و/یا گروه “pcp” باشد. اگر pmlogger(1) روی میزبان “foo” در حال اجرا است، از دستور “pminfo -f -h foo pmcd.pmlogger” برای بررسی این‌که آیا pmlogger(1) مورد نظر برای pmcd(1) شناخته شده است یا خیر استفاده کنید؛ از سوی دیگر، نمونه‌های pmlogger(1) که توسط دستور show loggers @foo در pmlc گزارش نمی‌شوند، برای pmcd(1) روی میزبان “foo” شناخته‌شده نیستند.

اگر pmlogger(1) با یک فایل پیکربندی راه‌اندازی شود که شامل یک بخش [access] باشد، آنگاه pmlc قادر به اتصال به آن pmlogger(1) نخواهد بود مگر اینکه کنترل‌های دسترسی، مقداری دسترسی را از میزبانی که pmlc روی آن اجرا می‌شود مجاز دانسته باشند. در کمترین حالت، این امر مستلزم آن است که دسترسی enquire در بخش کنترل دسترسی pmlogger(1) مجاز شده باشد.

اگر pmlc بتواند به pmlogger(1) مورد نظر متصل شود، جدول زیر مجوزهای مورد نیاز برای اجرای دستورهای مختلف pmlc را خلاصه می‌کند:

دستور pmlc	دسترسی مورد نیاز pmlogger
show loggers	هرکدام
connect	هریک از enquire، advisory یا mandatory
status	هریک از enquire، advisory یا mandatory
query ...	هریک از enquire، advisory یا mandatory
disconnect	هرکدام
log advisory ...	advisory
log mandatory ...	mandatory
new volume	mandatory
"هشدارها (CAVEATS)"
اگر تمام نمونه‌های یک متریک در حال ثبت گزارش باشند و درخواستی برای ثبت نمونه‌های خاصی از آن متریک با همان وضعیت و بسامد ارسال شود، ممکن است چنین به نظر برسد که درخواست موفقیت‌آمیز بوده است، حتی اگر
pmlogger
درخواست را رد کرده باشد.
این حالت معمولاً مشکلی ایجاد نمی‌کند، زیرا اطلاعات مورد نیاز همچنان توسط
pmlogger
در بایگانی قرار خواهد گرفت.
اما در شرایطی که متریک تنها باید یک‌بار ثبت شود، نتیجه آن چیزی نخواهد بود که ممکن است انتظار رود.
هنگامی که
pmlogger
درخواستی برای یک‌بار بایگانی کردن یک متریک دریافت می‌کند، صرف‌نظر از اینکه متریک از قبل در بایگانی موجود است یا خیر، مقادیر فعلی متریک را در سریع‌ترین زمان ممکن در بایگانی قرار می‌دهد.
این رفتار ممکن است برای درج اجباری مقادیر در بایگانی استفاده شود.
هنگامی که درخواستی برای بایگانی نمونه‌های خاصی از یک متریک ارسال شود و به این دلیل که همه نمونه‌های آن متریک از قبل در حال ثبت هستند رد گردد،
pmlogger
مقادیر مربوط به نمونه‌های درخواست‌شده را در بایگانی قرار نمی‌دهد.
این ابزار وضعیت فعلی ثبت گزارش هر نمونه درخواست‌شده را به
pmlc
بازمی‌گرداند.
وضعیت‌های درخواستی و بازگردانده‌شده یکسان هستند، بنابراین
pmlc
آن‌طور که باید خطایی صادر نمی‌کند.
برای اطمینان از اینکه تنها نمونه‌های خاصی از یک متریک ثبت می‌شوند، همواره باید پیش از فعال کردن ثبت گزارش برای نمونه‌های خاص مورد نیاز، ثبت را برای تمام نمونه‌های آن متریک غیرفعال کرد.
"خطاها (DIAGNOSTICS)"
بیشتر پیام‌های خطا یا هشدار خودتوضیح هستند.
پیامی به شکل
+05.v
Warning: unable to change logging state for...
که پس از آن فهرستی از متریک‌ها (و احتمالاً نمونه‌ها) می‌آید، نشان می‌دهد که
pmlogger
درخواست مربوط به متریک‌ها (و نمونه‌های) نشان داده‌شده را رد کرده است.
هر متریک (و نمونه‌ای) که مشخص شده بود اما در پیام ظاهر نشده، وضعیت ثبت آن با موفقیت به‌روزرسانی شده است
(بی‌خبری نشانه موفقیت است).
معمولاً این هشدار ناشی از درخواست ثبت اختیاری (advisory) در زمانی است که یک کنترل اجباری (mandatory) از پیش اعمال شده است، یا درخواست ثبت برای نمونه‌های خاص در حالی که همه نمونه‌ها از قبل در حال ثبت هستند.
"محیط (ENVIRONMENT)"
اگر متغیر محیطی
PMLOGGER_REQUEST_TIMEOUT
تنظیم نشده باشد یا روی 0 (صفر) تنظیم شده باشد،
pmlc
تا زمان برقراری ارتباط با
pmlogger (1)
روی port درخواست‌شده مسدود (block) خواهد شد.
اگر
PMLOGGER_REQUEST_TIMEOUT
روی مقداری بزرگ‌تر از صفر تنظیم شده باشد، در صورت برقرار نشدن اتصال پس از آن تعداد ثانیه،
pmlc
با یک خطا شکست می‌خورد.
این سازوکار می‌تواند توسط اسکریپت‌های مدیریتی مانند
pmlogger_daily (1)
استفاده شود تا وضعیت
pmlogger
را در زمان راه‌اندازی تا آماده‌شدن و گوش‌به‌زنگ شدن روی port کنترلی خود بررسی دوره‌ای (poll) کنند.
"محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند PCP_ برای مقداردهی و پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های استفاده‌شده توسط PCP به کار می‌روند.
در هر نصب، فایل /etc/pcp.conf حاوی مقادیر محلی برای این متغیرها است.
متغیر $PCP_CONF ممکن است برای تعیین یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در pcp.conf(5) شرح داده شده است.
"گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینه
-D
یا
--debug
خروجی عیب‌یابی مضاعف را در
stderr
فعال می‌کند تا به تفکیک و ریشه‌یابی مشکلات کمک کند، هرچند این اطلاعات گاهی مبهم است و در درجه اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی.
debug
فهرستی از گزینه‌های اشکال‌زدایی جدا شده با کاما است؛ از
pmdbg (1)
به همراه گزینه
-l
استفاده کنید تا فهرستی از گزینه‌های اشکال‌زدایی موجود و مفاهیم آن‌ها را دریافت نمایید.
گزینه‌های اشکال‌زدایی مخصوص به
pmlc
به شرح زیر است:
box;
lf(B) \| lf(B)
lf(B) \| lxf(R) .
گزینه	توضیحات
appl0	تخلیه متریک‌ها و نمونه‌های دریافت‌شده
appl1	تخلیه وضعیت پس از تجزیه هر دستور

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

PCPIntro(1)، pmcd(1)، pmlogdump(1)، pmlogger(1)، pcp.conf(5)، pcp.env(5)، PMNS(5) و environ(7).