نام (NAME)

pmval, pmevent - استخراج و نمایش مقادیر معیارهای کارایی دلخواه

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

pmval [-dgLrvVXz?] [-a archive] [-A align] [--container=name] [-D debug] [--derived=file] [-f N] [-h host] [-i instances] [-K spec] [-n pmnsfile] [-O offset] [-p port] [-s samples] [-S starttime] [-t interval] [-T endtime] [-U archive] [-w width] [-x pattern] [-Z timezone] metricname

pmevent ...

توضیحات (DESCRIPTION)

دستور pmval مقادیر جاری یا بایگانی‌شده را برای معیار کارایی مشخص‌شده چاپ می‌کند. معیار مورد نظر در آرگومان metricname نام‌گذاری می‌شود و بنا به توضیح زیر، مشروط به تعیین نمونه‌ها (instance qualification) با پرچم -i است.

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

آرگومان metricname همچنین می‌تواند در ساختار دستوری مشخص‌سازی معیار، همان‌گونه که در PCPIntro(1) شرح داده شده است، مشخص گردد؛ جایی که منبع، معیار و نمونه می‌توانند همگی در metricname گنجانده شوند، مانند: thathost:kernel.all.load["1 minute"]. هنگام استفاده از این قالب، هیچ‌یک از گزینه‌های -h، -a یا -U نباید مشخص شوند.

هنگام استفاده از ساختار دستوری مشخص‌سازی معیار، «نام میزبانِ» @ به‌طور ویژه‌ای مدیریت می‌شود و سبب می‌گردد pmval از یک زمینهٔ محلی (local context) برای جمع‌آوری معیارها از PMDAها روی میزبان محلی بدون نیاز به PMCD استفاده کند. در این حالت تنها برخی از معیارها در دسترس هستند.

هنگام پردازش مجموعه‌ای از بایگانی‌ها، pmval ممکن است کنترل زمان‌بندی خود را واگذار کند و تحت کنترل یک فرایند pmtime(1) عمل کند که از یک کادر گفتگوی گرافیکی (GUI) برای کنترل زمان‌بندی بهره می‌برد. در این حالت، یا باید از گزینهٔ -g برای راه‌اندازی pmval به‌عنوان تنها کلاینتِ یک نمونهٔ جدید از pmtime(1) استفاده شود، یا از گزینهٔ -p برای اتصال pmval به یک نمونهٔ موجود از pmtime(1) از طریق کانال IPC مشخص‌شده با آرگومان port استفاده گردد.

گزینه‌های -S، -T، -O و -A می‌توانند برای تعریف یک پنجرهٔ زمانی جهت محدود کردن نمونه‌های بازیابی‌شده، تنظیم مبدأ اولیه در پنجرهٔ زمانی، یا مشخص کردن یک تراز «طبیعی» (natural alignment) برای زمان‌های نمونه‌برداری به کار روند؛ برای شرح کامل این گزینه‌ها به PCPIntro(1) مراجعه کنید.

خروجی pmval به خروجی استاندارد هدایت می‌شود. گاهی اوقات ممکن است نمادهای زیر به‌جای مقدار یک معیار در خروجی pmval ظاهر شوند: نماد علامت سؤال (?) نشان می‌دهد که مقداری دیگر برای آن نمونه از معیار در دسترس نیست. یک علامت تعجب (!) نشان می‌دهد که یک شمارندهٔ ۶۴ بیتی در طول نمونه‌برداری دور زده است (counter wrapped).

دستور pmevent یک نام مستعار برای pmval است..SH "گزینه‌ها (OPTIONS)" گزینه‌های خط فرمان در دسترس عبارتند از:

-a archive, --archive=archive: مقادیر متریک‌های کارایی از مجموعه‌ای از فایل‌های آرشیو Performance Co-Pilot (PCP) مشخص‌شده توسط آرگومان archive بازیابی می‌شوند؛ این آرگومان فهرستی از نام‌های جداشده با کاما است که هر یک می‌تواند نام پایه یک آرشیو یا نام یک دایرکتوری حاوی یک یا چند آرشیو باشد. همچنین ببینید: -U.
-A align, --align=align: نمونه اولیه را مجبور می‌کند تا بر روی مرز یک واحد زمانی طبیعی align تراز شود. برای شرح کامل نحو align به PCPIntro(1) مراجعه کنید.
--container=container: یک container مشخص را برای پرس‌وجو تعیین می‌کند.
-d, --delay: هنگام بازپخش از یک آرشیو، این گزینه درخواست می‌کند که تاخیر زمانی واقعی (real-time) غالب بین نمونه‌ها اعمال شود (ببینید -t) تا به جای رفتار پیش‌فرض بازپخش با سرعت کامل، مکثی ایجاد شود.
--derived=file: تعاریف متریک‌های مشتق‌شده را از file بارگذاری می‌کند.
-f precision, --precision=precision: اعداد به جای نماد علمی پیش‌فرض، در نماد «ممیز ثابت» با استفاده از precision رقم برای دقت گزارش می‌شوند. هر عدد حداکثر به اندازه عرض ستون تعیین‌شده توسط قواعد تجربی پیش‌فرض خواهد بود، مگر اینکه گزینه -w مشخص شده باشد، و شامل precision رقم پس از ممیز اعشار است. بنابراین، گزینه‌های -f 3 -w 8 اعدادی به شکل 9999.999 تولید می‌کنند. مقدار صفر برای precision ممیز اعشار و هرگونه ارقام کسری را حذف می‌کند.
-g, --guimode: دستور pmval را به عنوان تنها کلاینت یک پردازه کارساز جدید pmtime(1) جهت بازپخش داده‌های کارایی آرشیوشده با استفاده از واسط گرافیکی کاربر pmtime(1) اجرا می‌کند.
-h host, --host=host: متریک‌های کارایی را به جای localhost پیش‌فرض، از pmcd(1) روی host دریافت می‌کند.
-i instances, --instances=instances: فهرستی از یک یا چند نام از instances (نمونه‌ها) را برای متریک کارایی نامزدشده مشخص می‌کند - تنها همین instances بازیابی و گزارش خواهند شد (پیش‌فرض، گزارش تمام نمونه‌ها است). این فهرست باید یک آرگومان واحد باشد و عناصر فهرست با کاما و/یا نویسه فاصله از هم جدا شوند.

در مواردی که نام نمونه شامل نویسه فاصله یا کاما است، نام نمونه می‌تواند درون علامت‌های نقل‌قول تکی (') یا دوگانه (") قرار گیرد.

استفاده از چندین گزینه -i به عنوان روشی جایگزین جهت تعیین بیش از یک نمونهٔ مورد نظر مجاز است.

به عنوان مثال، موارد زیر همگی معادل هستند:

$ pmval -i "'1 minute','5 minute'" kernel.all.load
$ pmval -i '"1 minute","5 minute"' kernel.all.load
$ pmval -i "'1 minute' '5 minute'" kernel.all.load
$ pmval -i "'1 minute'" -i "'5 minute'" kernel.all.load
$ pmval 'localhost:kernel.all.load["1 minute","5 minute"]'

-K spec, --spec-local=spec: هنگام دریافت متریک‌ها از یک بافت محلی (ببینید -L)، گزینه -K می‌تواند برای کنترل DSO PMDAهایی که باید قابل دسترسی باشند استفاده شود. آرگومان spec از نحو شرح داده شده در pmSpecLocalPMDA(3) پیروی می‌کند. بیش از یک گزینه -K می‌تواند استفاده شود.
-L, --local-PMDA: استفاده از یک بافت محلی برای گردآوری متریک‌ها از DSO PMDAها روی میزبان محلی بدون PMCD. همچنین ببینید: -K.
-n pmnsfile, --namespace=pmnsfile: یک فضای نام متریک‌های کارایی جایگزین (PMNS(5)) را از فایل pmnsfile بارگذاری می‌کند.
-O origin, --origin=origin: هنگام گزارش متریک‌های آرشیوشده، گزارش‌گیری از origin درون بازه زمانی آغاز می‌شود (ببینید -S و -T). برای شرح کامل نحو origin به PCPIntro(1) مراجعه کنید.
-p port, --guiport=port: دستور pmval را از طریق کانال IPC مشخص‌شده با آرگومان port به یک پردازه موجود کنترل زمان pmtime(1) متصل می‌کند. این گزینه معمولاً تنها توسط سایر ابزارها، مانند pmchart(1)، هنگامی که pmval را با کنترل زمان همگام‌سازی‌شده اجرا می‌کنند، استفاده می‌شود.
-r, --raw: چاپ مقادیر خام برای متریک‌های شمارنده تجمعی. به طور معمول متریک‌های شمارنده تجمعی به نرخ تبدیل می‌شوند. به عنوان مثال، انتقال‌های دیسک به جای مقدار خام تعداد انتقال‌های دیسک از زمان راه‌اندازی سامانه، به صورت تعداد انتقال‌های دیسک در ثانیه در طول بازه نمونه‌برداری پیشین گزارش می‌شوند. اگر این گزینه را مشخص کنید، مقادیر خام متریک چاپ می‌شوند.
-s samples, --samples=samples: آرگومان samples تعداد نمونه‌هایی را که باید بازیابی و گزارش شوند تعیین می‌کند. اگر samples برابر 0 باشد یا -s مشخص نشده باشد، pmval به صورت مداوم (در حالت بی‌درنگ) یا تا انتهای مجموعه آرشیوهای PCP (در حالت آرشیو) به نمونه‌برداری و گزارش ادامه می‌دهد.
-S starttime, --start=starttime: هنگام گزارش متریک‌های آرشیوشده، گزارش به رکوردهایی محدود خواهد شد که در starttime یا پس از آن ثبت شده‌اند. برای شرح کامل نحو starttime به PCPIntro(1) مراجعه کنید..TP -t interval, --interval=interval تنظیم بازه گزارش‌دهی interval به مقداری غیر از ۱ ثانیه پیش‌فرض. آرگومان interval از ساختار نحوی شرح داده شده در PCPIntro(1) پیروی می‌کند و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد (واحدهای ضمنی در این حالت ثانیه هستند).
-T endtime, --finish=endtime: هنگام گزارش معیارهای بایگانی‌شده، گزارش به رکوردهایی که قبل از endtime یا در همان زمان ثبت شده‌اند، محدود خواهد شد. برای شرح کامل ساختار نحوی endtime به PCPIntro(1) مراجعه کنید.
-U archive, --nointerp=archive: مقادیر معیارهای کارایی از archive در Performance Co-Pilot (PCP) بازیابی می‌شوند. آرگومان، فهرستی از نام‌ها است که با کاما از هم جدا شده‌اند، و هر یک می‌تواند نام پایه یک بایگانی یا نام دایرکتوری حاوی یک یا چند بایگانی باشد. با این حال، برخلاف -a هر مقدار ثبت‌شده در بایگانی برای معیار و نمونه‌های انتخاب‌شده گزارش می‌شود (بنابراین حالت درون‌یابی وجود ندارد و بازه نمونه‌برداری (گزینه -t) نادیده گرفته می‌شود). همچنین نگاه کنید به -a.

حداکثر یکی از گزینه‌های -a و -U می‌تواند مشخص شود.

-v, --verbose: فعال کردن حالت پرگو (verbose).
-V, --version: نمایش شماره نسخه و خروج.
-w width, --width=width: تنظیم عرض هر ستون از خروجی به تعداد ستون‌های width. در صورت عدم تعیین، ستون‌ها به اندازه‌ای عریض خواهند بود که بزرگ‌ترین مقدار نوع داده‌ای در حال چاپ را در خود جای دهند.
-x pattern, --filter=pattern: الگوی pattern داده‌شده، پیش از درخواست هرگونه مقدار، به عامل دامنه معیارهای کارایی برای metricname درخواست‌شده ارسال می‌شود. این کار در خدمت دو هدف است. نخست، سازوکاری برای پالایش رویدادها در سمت سرور فراهم می‌کند که برای جریان‌های رویداد مجزا قابل سفارشی‌سازی است. علاوه بر این، برخی از عامل‌های دامنه معیارهای کارایی نیز از سازوکار ذخیره PMCD برای ارائه یک مدل امنیتی پایه استفاده می‌کنند (برای مثال برای فایل‌های لاگ حساس، تنها یک میزبان کلاینت با دسترسی pmStore(3) می‌تواند به جریان رویداد دسترسی داشته باشد).

از آنجا که pattern ممکن است توسط regcomp(3) پردازش شود، باید یک رشته غیرخالی باشد. از . (نقطه) برای یک pattern از نوع “match all” (تطبیق با همه) استفاده کنید.

-X, --timestamp: هنگام بازپخش از یک بایگانی، این گزینه درخواست می‌کند که برچسب زمانی همراه با اطلاعات تاریخ اضافی و دقت افزایش‌یافته گزارش شود (میکروثانیه با یک بار -X، نانوثانیه با یک -X اضافی)، برای مثال Sat May 22 20:32:20.971633 2021 به جای قالب پیش‌فرض، مانند 20:32:20.971.
-z, --hostzone: استفاده از منطقه زمانی محلی میزبانی که منبع معیارهای کارایی است، همان‌طور که توسط گزینه‌های -h یا -a یا -U مشخص شده است. حالت پیش‌فرض استفاده از منطقه زمانی میزبان محلی است.
-Z timezone, --timezone=timezone: استفاده از timezone برای تاریخ و زمان. timezone در قالب متغیر محیطی TZ است، همان‌گونه که در environ(7) شرح داده شده است.
-?, --help: نمایش پیام راهنما و خروج..SH "هشدارها (CAVEATS)" به‌طور پیش‌فرض، pmval تلاش می‌کند مقادیر عددی غیرصحیح را به‌گونه‌ای نمایش دهد که به دقت ذاتی آن‌ها (که به‌ندرت بیش از ۴ رقم بااهمیت است) خدشه‌ای وارد نشود، و سعی می‌کند قالب جدول‌بندی‌شده را در خروجی حفظ نماید. این اهداف گاهی با یکدیگر در تضاد هستند.

در صورت عدم وجود گزینهٔ -f (که در بالا شرح داده شد)، جدول زیر قالب‌های استفاده‌شده برای محدوده‌های مختلف مقادیر عددی را برای هر معیاری از نوع PM_TYPE_FLOAT یا PM_TYPE_DOUBLE، یا هر معیاری که دارای معناشناسی شمارنده باشد (که برای آن pmval مقدار تبدیل‌شده به نرخ را گزارش می‌کند) توصیف می‌کند:

قالب	محدوده مقادیر
!	مقداری در دسترس نیست
9.999E-99	< 0.1
0.0	0
9.9999	> 0 و <= 0.9999
9.999	> 0.9999 و < 9.999
99.99	> 9.999 و < 99.99
999.9	> 99.99 و < 999.9
9999.	> 999.9 و < 9999
9.999E+99	> 9999

محیط PCP (PCP ENVIRONMENT)

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

برای متغیرهای محیطی که بر ابزارهای PCP تأثیر می‌گذارند، به pmGetOptions(3) مراجعه کنید.

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

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

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

گزینه	توضیحات
appl0	موقعیت‌یابی اولیهٔ خط زمانی هنگام استفاده از -a

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

PCPIntro(1)، pmcd(1)، pmchart(1)، pmdumptext(1)، pminfo(1)، pmlogdump(1)، pmlogger(1)، pmrep(1)، pmtime(1)، PMAPI(3)، pmSpecLocalPMDA(3)، pmStore(3)، pcp.conf(5)، pcp.env(5) و PMNS(5).