PCP2XML(1) General Commands Manual PCP2XML(1)

pcp2xml - صادرکننده معیارهای کارایی PCP به فرمت XML

pcp2xml [-5CGHIjLmnrRvVxXz?] [-4 action] [-8|-9 limit] [-a archive] [-A align] [--archive-folio folio] [-b|-B space-scale] [-c config] [--container container] [-D debug] [--daemonize] [-e derived] [-f format] [-F outfile] [-h host] [-i instances] [-J rank] [-K spec] [-N predicate] [-O origin] [-P|-0 precision] [-q|-Q count-scale] [-s samples] [-S starttime] [-t interval] [-T endtime] [-y|-Y time-scale] [-Z timezone] metricspec [...]

دستور pcp2xml ابزاری قابل سفارشی‌سازی برای صادر کردن معیارهای کارایی از PCP به XML است. هر معیار کارایی موجود، زنده یا بایگانی‌شده، سیستمی یا برنامه‌ای، می‌تواند برای صدور با استفاده از آرگومان‌های خط فرمان یا یک فایل پیکربندی انتخاب شود.

دستور pcp2xml ارتباط نزدیکی با pmrep(1) دارد. برای شرح metricspec پذیرفته‌شده در خط فرمان pcp2xml، به pmrep(1) مراجعه کنید. برای شرح نحو فایل پیکربندی pcp2xml.conf صفحه راهنمای pmrep.conf(5) را ببینید. این صفحه راهنما، گزینه‌های اختصاصی pcp2xml و تفاوت‌های فایل پیکربندی آن با pmrep.conf(5) را توصیف می‌کند. همچنین pmrep(1) نمونه‌های متعددی از کاربرد را فهرست می‌کند که بیشتر آن‌ها برای pcp2xml نیز قابل استفاده هستند.

تنها گزینه‌های خط فرمان فهرست‌شده در این صفحه پشتیبانی می‌شوند؛ سایر گزینه‌های موجود برای pmrep(1) پشتیبانی نمی‌شوند.

گزینه‌های اعمال‌شده از طریق مقادیر محیطی (نگاه کنید به pmGetOptions(3)) بر مقادیر پیش‌فرض داخلی متناظر (در صورت وجود) تقدم دارند. گزینه‌های فایل پیکربندی بر متغیرهای محیطی متناظر (در صورت وجود) مقدم هستند. گزینه‌های خط فرمان نیز بر گزینه‌های فایل پیکربندی متناظر (در صورت وجود) اولویت دارند.

دستور pcp2xml از یک فایل پیکربندی با نحو توصیف‌شده در pmrep.conf(5) استفاده می‌کند. گزینه‌های زیر با pmrep.conf مشترک هستند: version، source، speclocal، derived، header، globals، samples، interval، type، type_prefer، ignore_incompat، names_change، instances، live_filter، rank، limit_filter، limit_filter_force، invert_filter، predicate، omit_flat، include_labels، precision، precision_force، count_scale، count_scale_force، space_scale، space_scale_force، time_scale، time_scale_force. باقی گزینه‌های pmrep.conf شناسایی می‌شوند اما جهت سازگاری نادیده گرفته می‌شوند.

extended (بولی)

نوشتن اطلاعات گسترش‌یافته درباره معیارها. گزینه خط فرمان متناظر -x است. پیش‌فرض no است.

everything (بولی)

نوشتن تمام اطلاعات شناخته‌شده درباره معیارها، از جمله شناسه‌های داخلی PCP. با این حال برچسب‌ها برای سازگاری با گذشته حذف شده‌اند. برای گنجاندن آن‌ها نیز گزینه include_labels را فعال کنید. گزینه خط فرمان متناظر -X است. پیش‌فرض no است.

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

-0 precision, --precision-force=precision
مشابه -P اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد.
-4 action, --names-change=action
مشخص می‌کند که هنگام دریافت رویداد تغییر نام معیارها در حین نمونه‌برداری، چه عملیاتی (action) انجام شود. این رویدادها زمانی رخ می‌دهند که یک PMDA مدتی پس از راه‌اندازی، معیارهای جدیدی را کشف کرده و به ابزارهای کلاینت در حال اجرا مانند pcp2xml اطلاع می‌دهد. مقادیر معتبر برای action عبارتند از update (تازه‌سازی معیارهای در حال نمونه‌برداری)، ignore (کاری انجام نده - رفتار پیش‌فرض) و abort (خروج از برنامه در صورت وقوع چنین رویدادی).
-5, --ignore-unknown
نادیده گرفتن بدون خطای نام هر معیاری که قابل حل‌وفصل نباشد. برای شروع به کار ابزار، حداقل یک معیار باید یافت شود.
-8 limit, --limit-filter=limit
محدود کردن نتایج به نمونه‌هایی با مقادیر بالاتر/پایین‌تر از limit. یک عدد صحیح مثبت، نمونه‌هایی با مقادیر مساوی یا بالاتر از حد تعیین‌شده را در گزارش لحاظ می‌کند. یک عدد صحیح منفی، نمونه‌هایی با مقادیر مساوی یا پایین‌تر از حد تعیین‌شده را در گزارش لحاظ می‌کند. مقدار صفر هیچ فیلتر محدودیتی اعمال نمی‌کند. این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به -J و -N.
-9 limit, --limit-filter-force=limit
مشابه -8 اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد.
مقادیر معیارهای کارایی از مجموعه‌ای از فایل‌های بایگانی Performance Co-Pilot (PCP) بازیابی می‌شوند که با آرگومان archive مشخص شده‌اند؛ این آرگومان فهرستی از نام‌های جداشده با کاما است که هر یک می‌تواند نام پایه یک بایگانی یا نام پوشه‌ای حاوی یک یا چند بایگانی باشد.
تراز کردن اجباری نمونه اولیه بر روی مرز یک واحد زمانی طبیعی align. برای شرح کامل نحو align، به PCPIntro(1) مراجعه کنید.
خواندن بایگانی‌های منبع معیار از فولیو بایگانی PCP folio ایجادشده توسط ابزارهایی مانند pmchart(1) یا، با تکرار کمتر، به صورت دستی با mkaf(1).
واحد/مقیاس برای معیارهای فضا (بایت)، مقادیر ممکن شامل bytes، Kbytes، KB، Mbytes، MB و غیره است. این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به pmParseUnitsStr(3).
مشابه -b اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد.
مشخص کردن فایل یا پوشه config مورد استفاده. در صورتی که config یک پوشه باشد، تمام فایل‌های درون آن که به .conf ختم می‌شوند گنجانده خواهند شد. پیش‌فرض نخستین موردی است که از میان موارد زیر یافت شود: ./pcp2xml.conf، $HOME/.pcp2xml.conf، $HOME/pcp/pcp2xml.conf و $PCP_SYSCONF_DIR/pcp2xml.conf. برای جزئیات، بخش بالا و pmrep.conf(5) را ببینید.
واکشی معیارهای کارایی از کانتینر مشخص‌شده container، خواه محلی یا دوردست (نگاه کنید به -h).
خروج پیش از گزارش هرگونه مقدار، اما پس از تجزیه پیکربندی و معیارها و چاپ هدرهای احتمالی.
اجرا به صورت دیمن در زمان راه‌اندازی.
مشخص کردن معیارهای کارایی مشتق‌شده (derived). اگر derived با یک اسلش (``/'') یا با یک نقطه (``.'') شروع شود، به عنوان یک فایل پیکربندی معیارهای مشتق‌شده PCP تفسیر خواهد شد؛ در غیر این صورت به عنوان عبارات معیارهای مشتق‌شده جداشده با کاما یا نقطه‌ویرگول تفسیر می‌شود. برای شرح کامل معیارهای مشتق‌شده و فایل‌های پیکربندی معیارهای مشتق‌شده PCP به pmLoadDerivedConfig(3) و pmRegisterDerived(3) مراجعه کنید. همچنین، استفاده از نحو پیکربندی pmrep.conf(5) اجازه می‌دهد معیارهای مشتق‌شده را به عنوان بخشی از مجموعه‌معیارها (metricsets) تعریف کنید.

در صورت بروز مشکل در معیارهای مشتق‌شده، صفحات راهنمای یادشده را به دقت مرور کنید و مطمئن شوید که تمام معیارهای مورد نیاز در دسترس هستند، به ویژه هنگام استفاده از بایگانی‌ها. از -Dderive برای مشاهده اطلاعات اشکال‌زدایی بیشتر درباره تجزیه معیارهای مشتق‌شده استفاده کنید.

عدم گنجاندن معیارهای سراسری در گزارش (نگاه کنید به pmrep.conf(5)).
استفاده از رشته format برای قالب‌بندی برچسب زمانی. این قالب با متد datetime.strftime پایتون استفاده خواهد شد که عمدتاً مشابه با موارد شرح‌داده‌شده در strftime(3) است. پیش‌فرض %Y-%m-%d %H:%M:%S است.
مشخص کردن فایل خروجی outfile.
واکشی معیارهای کارایی از pmcd(1) روی host، به جای پیش‌فرض localhost.
عدم چاپ هیچ‌گونه هدر.
بازیابی و گزارش تنها نمونه‌های (instances) مشخص‌شده از معیار. به طور پیش‌فرض تمام نمونه‌ها، چه فعلی و چه آینده، گزارش می‌شوند.

برای شرح کامل این گزینه به pmrep(1) مراجعه کنید.

نادیده گرفتن معیارهای ناسازگار. به طور پیش‌فرض معیارهای ناسازگار (یعنی نوع آن‌ها پشتیبانی نمی‌شود یا مقیاس آن‌ها طبق درخواست تغییر نمی‌کند) باعث توقف pcp2xml با یک پیام خطا می‌شوند. با این گزینه، تمام معیارهای ناسازگار بی سر و صدا از گزارش حذف می‌شوند. این ویژگی ممکن است به ویژه هنگام درخواست گره‌های غیربرگ درخت PMNS برای گزارش‌دهی مفید باشد.
انجام فیلترسازی زنده نمونه‌ها. این قابلیت امکان ضبط تمام نمونه‌های نام‌گذاری‌شده را فراهم می‌کند حتی اگر فرآیندها در مقطعی مجدداً راه‌اندازی شوند (برخلاف حالت بدون فیلتر زنده). انجام فیلترسازی زنده روی تعداد بسیار زیادی از نمونه‌ها سربار داخلی اضافه خواهد کرد، بنابراین احتیاط کاربر توصیه می‌شود. همچنین نگاه کنید به -n.
محدود کردن نتایج به بالاترین/پایین‌ترین نمونه‌های رتبه‌بندی‌شده (ranked) از معیارهای چندمقداری. یک عدد صحیح مثبت، نمونه‌هایی با بالاترین مقدار را در گزارش لحاظ می‌کند. یک عدد صحیح منفی، نمونه‌هایی با پایین‌ترین مقدار را در گزارش لحاظ می‌کند. مقدار صفر هیچ رتبه‌بندی انجام نمی‌دهد. رتبه‌بندی به معنای مرتب‌سازی نیست، نگاه کنید به -6. همچنین نگاه کنید به -8.
هنگام واکشی معیارها از یک بافت محلی (نگاه کنید به -L)، گزینه -K می‌تواند برای کنترل PMDAهای DSO که باید در دسترس قرار گیرند استفاده شود. آرگومان spec مطابق با نحو توصیف‌شده در pmSpecLocalPMDA(3) است. می‌توان بیش از یک گزینه -K را استفاده کرد.
استفاده از یک بافت محلی برای جمع‌آوری معیارها از PMDAهای DSO روی میزبان محلی بدون PMCD. همچنین نگاه کنید به -K.
گنجاندن برچسب‌های معیار PCP در خروجی.
انجام رتبه‌بندی پیش از فیلترسازی زنده. به طور پیش‌فرض فیلترسازی زنده نمونه‌ها (در صورت درخواست، نگاه کنید به -j) پیش از رتبه‌بندی نمونه‌ها (در صورت درخواست، نگاه کنید به -J) انجام می‌شود. با این گزینه منطق وارونه شده و رتبه‌بندی پیش از فیلترسازی زنده رخ می‌دهد.
مشخص کردن یک فهرست جداشده با کاما از معیارهای مرجع فیلتر گزاره‌ای (predicate). به طور پیش‌فرض رتبه‌بندی (نگاه کنید به -J) برای هر معیار به طور جداگانه صورت می‌گیرد. با گزاره‌ها، رتبه‌بندی تنها برای معیارهای گزاره‌ای مشخص‌شده انجام می‌شود. هنگام گزارش‌دهی، بقیه معیارهایی که دامنه نمونه یکسانی دارند (instance domain، نگاه کنید به PCPIntro(1)) با گزاره، تنها شامل نمونه‌هایی با بالاترین/پایین‌ترین رتبه از گزاره متناظر خواهند بود. رتبه‌بندی به معنای مرتب‌سازی نیست، نگاه کنید به -6.

بنابراین به عنوان مثال، با استفاده از proc.memory.rss (اندازه حافظه مقیم فرآیند) به عنوان معیار predicate همراه با proc.io.total_bytes و mem.util.used به عنوان معیارهایی که باید گزارش شوند، تنها فرآیندهایی که بیشترین/کمترین حافظه را (طبق -J) مصرف می‌کنند، هنگام گزارش مجموع بایت‌های نوشته‌شده توسط فرآیندها لحاظ خواهند شد. از آنجا که mem.util.used یک معیار تک‌مقداری است (و بنابراین دامنه نمونه یکسانی با معیارهای مربوط به فرآیند به اشتراک نمی‌گذارد)، مانند معمول گزارش خواهد شد.

هنگام گزارش معیارهای بایگانی‌شده، شروع گزارش در مبدأ origin درون پنجره زمانی (نگاه کنید به -S و -T). برای شرح کامل نحو origin، به PCPIntro(1) مراجعه کنید.
استفاده از precision برای مقادیر خروجی عددی غیرصحیح. پیش‌فرض استفاده از ۳ رقم اعشار است (در صورت کاربرد). این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد.
واحد/مقیاس برای معیارهای شمارشی، مقادیر ممکن شامل count x 10^-1، count، count x 10، count x 10^2 و به همین ترتیب از 10^-8 تا 10^7 است. (این مقادیر در حال حاضر به فاصله‌ها حساس هستند.) این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به pmParseUnitsStr(3).
مشابه -q اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد.
خروجی دادن مقادیر خام معیارها؛ شمارنده‌های انباشته به نرخ تبدیل نمی‌شوند. این گزینه مشخصات احتمالی به ازای هر معیار را لغو و جایگزین خواهد کرد.
مشابه -r اما این گزینه مشخصات به ازای هر معیار را لغو نخواهد کرد.
آرگومان samples تعداد نمونه‌هایی را که باید بازیابی و گزارش شوند مشخص می‌کند. اگر samples برابر ۰ باشد یا -s مشخص نشده باشد، pcp2xml به طور مداوم (در حالت بلادرنگ) یا تا انتهای مجموعه بایگانی‌های PCP (در حالت بایگانی) نمونه‌برداری و گزارش خواهد کرد. همچنین نگاه کنید به -T.
هنگام گزارش معیارهای بایگانی‌شده، گزارش محدود به رکوردهایی خواهد بود که در زمان starttime یا پس از آن ثبت شده‌اند. برای شرح کامل نحو starttime، به PCPIntro(1) مراجعه کنید.
تنظیم interval گزارش‌دهی روی مقداری غیر از پیش‌فرض ۱ ثانیه. آرگومان interval از نحو توصیف‌شده در PCPIntro(1) پیروی می‌کند، و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد (واحدهای ضمنی در این حالت ثانیه هستند). همچنین گزینه -T را ببینید.
هنگام گزارش معیارهای بایگانی‌شده، گزارش محدود به رکوردهایی خواهد بود که پیش از endtime یا در همان زمان ثبت شده‌اند. برای شرح کامل نحو endtime، به PCPIntro(1) مراجعه کنید.

هنگامی که برای تعیین مدت زمان اجرا پیش از خروج pcp2xml استفاده می‌شود، اگر هیچ مقداری برای samples تعیین نشده باشد (نگاه کنید به -s)، تعداد نمونه‌های گزارش‌شده به interval بستگی خواهد داشت (نگاه کنید به -t). اگر samples تعیین شده باشد، interval به گونه‌ای تنظیم می‌شود که اجازه گزارش‌دهی samples را در طول زمان اجرا بدهد. در صورتی که هر سه گزینه -T، -s و -t تعیین شده باشند، endtime زمان واقعی اجرای pcp2xml را تعیین می‌کند.

تنها معیارهای چندمقداری دارای نمونه (مانند disk.dev.read) را گزارش کرده و معیارهای تک‌مقداری «مسطح» بدون نمونه (مانند kernel.all.sysfork) را حذف می‌کند. نگاه کنید به -i و -I.
نمایش شماره نسخه و خروج.
نوشتن اطلاعات گسترش‌یافته.
نوشتن تمام اطلاعات شناخته‌شده درباره معیارها، از جمله شناسه‌های داخلی PCP. با این حال برچسب‌ها برای سازگاری با گذشته حذف شده‌اند؛ برای گنجاندن آن‌ها نیز از -m استفاده کنید.
واحد/مقیاس برای معیارهای زمانی، مقادیر ممکن شامل nanosec، ns، microsec، us، millisec، ms و به همین ترتیب تا hour، hr است. این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به pmParseUnitsStr(3).
مشابه -y اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد.
استفاده از منطقه زمانی محلی میزبانی که منبع معیارهای کارایی است، همان‌طور که توسط گزینه‌های -h یا -a مشخص شده است. پیش‌فرض استفاده از منطقه زمانی میزبان محلی است.
استفاده از timezone برای تاریخ و زمان. Timezone در قالب متغیر محیطی TZ مطابق با آنچه در environ(7) شرح داده شده است. توجه داشته باشید که هنگام گنجاندن رشته منطقه زمانی در خروجی، از آفست‌های UTC به سبک ISO 8601 استفاده می‌شود (بنابراین موردی مانند -Z EST+5 به UTC-5 تبدیل خواهد شد).
-?, --help
نمایش پیام راهنما و خروج.

فایل پیکربندی pcp2xml (نگاه کنید به -c)
$PCP_SYSCONF_DIR/pmrep/*.conf
فایل‌های پیکربندی پیش‌فرض pmrep ارائه‌شده توسط سیستم

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

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

به طور ویژه، PCP_DISCRETE_ONCE می‌تواند تنظیم شود تا اطمینان حاصل شود که مقادیر گسسته معیارها تنها یک‌بار گزارش می‌شوند، مگر اینکه در مقطعی تغییر کنند.

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

PCPIntro(1), mkaf(1), pcp(1), pcp2elasticsearch(1), pcp2graphite(1), pcp2influxdb(1), pcp2json(1), pcp2spark(1), pcp2xlsx(1), pcp2zabbix(1), pmcd(1), pminfo(1), pmrep(1), pmGetOptions(3), pmLoadDerivedConfig(3), pmParseUnitsStr(3), pmRegisterDerived(3), pmSpecLocalPMDA(3), LOGARCHIVE(5), pcp.conf(5), pmrep.conf(5), PMNS(5) و environ(7).

PCP Performance Co-Pilot