PCP2SPARK(1) General Commands Manual PCP2SPARK(1)

pcp2spark - صادرکننده متریک‌های pcp به spark

pcp2spark [-5CGHIjLmnrRvV?] [-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] [-g server] [-h host] [-i instances] [-J rank] [-K spec] [-N predicate] [-O origin] [-p port] [-P|-0 precision] [-q|-Q count-scale] [-s samples] [-S starttime] [-t interval] [-T endtime] [-y|-Y time-scale] metricspec [...]

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

دستور pcp2spark به‌عنوان یک پل ارتباطی عمل می‌کند که جریانی از سوکت شبکه را روی نشانی/درگاه داده‌شده فراهم می‌سازد تا یک تسک worker در Apache Spark بتواند به آن متصل شده و متریک‌های پیکربندی‌شده PCP را از pcp2spark دریافت نماید و با استفاده از افزونه‌های جریانی API مربوط به Apache Spark صادر کند.

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

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

گزینه‌های مشخص‌شده از طریق مقادیر محیطی (رجوع کنید به pmGetOptions(3)) بر مقادیر پیش‌فرض توکار متناظر (در صورت وجود) مقدم هستند. گزینه‌های فایل پیکربندی بر متغیرهای محیطی متناظر (در صورت وجود) اولویت دارند. گزینه‌های خط فرمان نیز بر گزینه‌های متناظر در فایل پیکربندی (در صورت وجود) اولویت خواهند داشت..SH "کاربرد عمومی (GENERAL USAGE)" یک راه‌اندازی معمول برای استفاده از pcp2spark شامل پیکربندی pcp2spark توسط کاربر برای سنجه‌های PCP جهت برون‌ریزی و به دنبال آن اجرای برنامهٔ pcp2spark است. سپس برنامهٔ pcp2spark منتظر مانده و روی آدرس/درگاه مشخص‌شده برای برقراری اتصال از طرف یک نخ کارگر (worker thread) آپاچی اسپارک (Apache Spark) که آغاز به کار خواهد کرد، به گوش می‌ایستد. سپس نخ کارگر به pcp2spark متصل خواهد شد.

هنگامی که یک نخ کارگر Apache Spark متصل شد، pcp2spark شروع به جاری‌سازی داده‌های سنجهٔ PCP به Apache Spark می‌کند تا زمانی که کار نخ کارگر پایان یابد یا اتصال قطع شود. اگر اتصال قطع شود یا سوکت از سمت نخ کارگر Apache Spark بسته شود، pcp2spark خارج خواهد شد.

برای مشاهده یک نمونه کار (job) کارگر Apache Spark که به یک نمونه از pcp2spark روی آدرس/درگاه داده‌شده متصل می‌شود و داده‌های سنجهٔ PCP را دریافت می‌کند، به نمونهٔ ارائه‌شده در دایرکتوری نمونه‌های PCP برای pcp2spark (که اغلب توسط بستهٔ توسعهٔ PCP ارائه می‌شود) یا نسخهٔ برخط در https://github.com/performancecopilot/pcp/blob/main/src/pcp2spark مراجعه کنید.

pcp2spark از یک فایل پیکربندی با ساختار شرح‌داده‌شده در 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 شناسایی می‌شوند اما به منظور سازگاری نادیده گرفته خواهند شد.

spark_server (رشته)

آدرسی را مشخص می‌کند که pcp2spark روی آن برای اتصالات ورودی از طرف یک نخ کارگر Apache Spark به گوش می‌ایستد. گزینهٔ خط فرمان معادل -g است. پیش‌فرض 127.0.0.1 است.

spark_port (عدد صحیح)

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

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

آدرس server محلی pcp2spark.
شامل نکردن متریک‌های سراسری (global) در گزارش (نگاه کنید به pmrep.conf(5)).
واکشی متریک‌های کارایی از pmcd(1) روی host، به جای localhost پیش‌فرض.
عدم چاپ هیچ‌گونه سرآیندی.
تنها بازیابی و گزارش نمونه‌های (instances) مشخص‌شدهٔ متریک. به‌طور پیش‌فرض، تمام نمونه‌ها، اعم از فعلی و آتی، گزارش می‌شوند.

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

نادیده گرفتن متریک‌های ناسازگار. به‌طور پیش‌فرض، متریک‌های ناسازگار (یعنی نوع آن‌ها پشتیبانی نمی‌شود یا طبق درخواست مقیاس‌پذیر نیستند) موجب می‌شوند که pcp2spark همراه با یک پیام خطا متوقف شود. با این گزینه، تمام متریک‌های ناسازگار بی‌سروصدا از گزارش حذف می‌شوند. این قابلیت به‌ویژه هنگام درخواست گره‌های غیربرگ درخت PMNS برای گزارش‌گیری مفید است..TP -j, --live-filter فیلترسازی زنده‌ی نمونه‌ها را انجام می‌دهد. این قابلیت اجازه می‌دهد تمام نمونه‌های نام‌گذاری‌شده ضبط شوند، حتی اگر فرآیندها در مقطعی مجدداً راه‌اندازی شوند (برخلاف حالتی که بدون فیلترسازی زنده اجرا شود). انجام فیلترسازی زنده روی تعداد بسیار زیادی از نمونه‌ها بار اضافی (overhead) داخلی به همراه خواهد داشت، بنابراین کمی احتیاط از سوی کاربر توصیه می‌شود. همچنین ببینید: -n.
نتایج را به بالاترین/پایین‌ترین نمونه‌های ranked از معیارهای دارای مقدار مجموعه‌ای (set-valued) محدود می‌کند. یک عدد صحیح مثبت، نمونه‌های با بالاترین مقدار را در گزارش لحاظ خواهد کرد. یک عدد صحیح منفی، نمونه‌های با پایین‌ترین مقدار را در گزارش لحاظ خواهد کرد. مقدار صفر هیچ رتبه‌بندی‌ای انجام نمی‌دهد. رتبه‌بندی به معنای مرتب‌سازی نیست، ببینید: -6. همچنین ببینید: -8.
هنگام واکشی معیارها از یک بافت محلی (ببینید: -L)، گزینهٔ -K می‌تواند برای کنترل DSO PMDAهایی که باید قابل دسترسی باشند استفاده شود. آرگومان spec از نحو شرح داده‌شده در pmSpecLocalPMDA(3) پیروی می‌کند. می‌توان از بیش از یک گزینهٔ -K استفاده کرد.
استفاده از یک بافت محلی برای جمع‌آوری معیارها از DSO PMDAها روی میزبان محلی بدون PMCD. همچنین ببینید: -K.
گنجاندن برچسب‌های معیار PCP در خروجی.
انجام رتبه‌بندی پیش از فیلترسازی زنده. به‌طور پیش‌فرض، فیلترسازی زنده‌ی نمونه‌ها (در صورت درخواست، ببینید: -j) پیش از رتبه‌بندی نمونه‌ها (در صورت درخواست، ببینید: -J) انجام می‌شود. با این گزینه، منطق کار معکوس شده و رتبه‌بندی قبل از فیلترسازی زنده رخ می‌دهد.
مشخص کردن یک فهرست جدا شده با کاما از معیارهای مرجع فیلتر predicate. به‌طور پیش‌فرض رتبه‌بندی (ببینید: -J) برای هر معیار به‌صورت جداگانه انجام می‌شود. با گزاره‌ها (predicates)، رتبه‌بندی تنها برای معیارهای گزارهٔ مشخص‌شده انجام می‌گیرد. هنگام گزارش‌گیری، باقی معیارهایی که دامنهٔ نمونهٔ (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) مراجعه کنید.
درگاه (port) محلی pcp2spark.
استفاده از دقت اعشار precision برای مقادیر عددی غیرصحیح در خروجی. حالت پیش‌فرض استفاده از ۳ رقم اعشار است (در صورت امکان). این گزینه مشخصات احتمالی اختصاصی به ازای هر معیار را لغو نخواهد کرد.
واحد/مقیاس (Unit/scale) برای معیارهای شمارشی، مقادیر معتبر شامل count x 10^-1، count، count x 10، count x 10^2 و به همین ترتیب از 10^-8 تا 10^7 است. (این مقادیر در حال حاضر به فاصله حساس هستند.) این گزینه مشخصات احتمالی اختصاصی به ازای هر معیار را لغو نخواهد کرد. همچنین ببینید: pmParseUnitsStr(3).
مشابه -q اما این گزینه مشخصات اختصاصی به ازای هر معیار را لغو خواهد کرد.
خروجی دادن مقادیر خام معیارها و عدم تبدیل شمارنده‌های تجمعی به نرخ (rate). این گزینه مشخصات احتمالی اختصاصی به ازای هر معیار را لغو خواهد کرد.
مشابه -r اما این گزینه مشخصات اختصاصی به ازای هر معیار را لغو نخواهد کرد.
آرگومان samples تعداد نمونه‌هایی را که باید دریافت و گزارش شوند مشخص می‌کند. اگر samples برابر ۰ باشد یا -s مشخص نشده باشد، pcp2spark به‌صورت مداوم (در حالت بلادرنگ) یا تا انتهای مجموعه بایگانی‌های PCP (در حالت بایگانی) نمونه‌برداری و گزارش خواهد کرد. همچنین ببینید: -T.
هنگام گزارش معیارهای بایگانی‌شده، گزارش تنها به رکوردهایی محدود خواهد شد که در زمان starttime یا پس از آن ثبت شده باشند. برای شرح کامل نحو starttime، به PCPIntro(1) مراجعه کنید.
تنظیم بازهٔ زمانی (interval) گزارش‌گیری به مقداری غیر از مقدار پیش‌فرض ۱ ثانیه. آرگومان interval از نحو شرح داده‌شده در PCPIntro(1) پیروی می‌کند و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد (واحد پیش‌فرض در این حالت ثانیه است). همچنین گزینهٔ -T را ببینید.
هنگام گزارش معیارهای بایگانی‌شده، گزارش تنها به رکوردهایی محدود خواهد شد که قبل از endtime یا در همان زمان ثبت شده باشند. برای شرح کامل نحو endtime، به PCPIntro(1) مراجعه کنید. هنگامی که برای تعریف مدت‌زمان اجرا پیش از خروج pcp2spark استفاده می‌شود، اگر هیچ samples مشخص نشده باشد (گزینهٔ -s را ببینید)، تعداد نمونه‌های گزارش‌شده به interval (گزینهٔ -t را ببینید) وابسته خواهد بود. اگر samples داده شده باشد، آنگاه interval به گونه‌ای تنظیم می‌شود که امکان گزارش دادن samples در طول مدت‌زمان اجرا فراهم شود. در صورتی که هر سه گزینهٔ -T، -s و -t داده شده باشند، endtime زمان واقعی اجرای pcp2spark را تعیین می‌کند.
تنها معیارهای دارای مقادیر مجموعه‌ای همراه‌با نمونه‌ها (مانند disk.dev.read) را گزارش می‌دهد و از معیارهای تک‌مقدار «مسطح» فاقد نمونه (مانند kernel.all.sysfork) صرف‌نظر می‌کند. گزینه‌های -i و -I را ببینید.
نمایش شماره نسخه و خروج.
واحد/مقیاس برای معیارهای زمانی؛ مقادیر ممکن شامل nanosec، ns، microsec، us، millisec، ms و به همین ترتیب تا hour و hr است. این گزینه مشخصات احتمالی اختصاصی هر معیار را لغو نخواهد کرد. همچنین pmParseUnitsStr(3) را ببینید.
مشابه -y اما این گزینه مشخصات اختصاصی هر معیار را لغو خواهد کرد.
-?, --help
نمایش پیام راهنما و خروج.

فایل پیکربندی pcp2spark (گزینهٔ -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 برای دریافت فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید..SH "همچنین ببینید (SEE ALSO)" PCPIntro(1)، mkaf(1)، pcp(1)، pcp2elasticsearch(1)، pcp2graphite(1)، pcp2influxdb(1)، pcp2json(1)، pcp2xlsx(1)، pcp2xml(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).

PCP Performance Co-Pilot