PCP2XML(1) General Commands Manual PCP2XML(1) نام (NAME) pcp2xml - صادرکننده معیارهای کارایی PCP به فرمت XML خلاصه دستور (SYNOPSIS) 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 [...] توضیحات (DESCRIPTION) دستور 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)) بر مقادیر پیش‌فرض داخلی متناظر (در صورت وجود) تقدم دارند. گزینه‌های فایل پیکربندی بر متغیرهای محیطی متناظر (در صورت وجود) مقدم هستند. گزینه‌های خط فرمان نیز بر گزینه‌های فایل پیکربندی متناظر (در صورت وجود) اولویت دارند. فایل پیکربندی (CONFIGURATION FILE) دستور 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 شناسایی می‌شوند اما جهت سازگاری نادیده گرفته می‌شوند. گزینه‌های اختصاصی pcp2xml extended (بولی) نوشتن اطلاعات گسترش‌یافته درباره معیارها. گزینه خط فرمان متناظر -x است. پیش‌فرض no است. everything (بولی) نوشتن تمام اطلاعات شناخته‌شده درباره معیارها، از جمله شناسه‌های داخلی PCP. با این حال برچسب‌ها برای سازگاری با گذشته حذف شده‌اند. برای گنجاندن آن‌ها نیز گزینه include_labels را فعال کنید. گزینه خط فرمان متناظر -X است. پیش‌فرض no است. گزینه‌ها (OPTIONS) گزینه‌های خط فرمان موجود عبارتند از: -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 اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد. -a archive, --archive=archive مقادیر معیارهای کارایی از مجموعه‌ای از فایل‌های بایگانی Performance Co-Pilot (PCP) بازیابی می‌شوند که با آرگومان archive مشخص شده‌اند؛ این آرگومان فهرستی از نام‌های جداشده با کاما است که هر یک می‌تواند نام پایه یک بایگانی یا نام پوشه‌ای حاوی یک یا چند بایگانی باشد. -A align, --align=align تراز کردن اجباری نمونه اولیه بر روی مرز یک واحد زمانی طبیعی align. برای شرح کامل نحو align، به PCPIntro(1) مراجعه کنید. --archive-folio=folio خواندن بایگانی‌های منبع معیار از فولیو بایگانی PCP folio ایجادشده توسط ابزارهایی مانند pmchart(1) یا، با تکرار کمتر، به صورت دستی با mkaf(1). -b scale, --space-scale=scale واحد/مقیاس برای معیارهای فضا (بایت)، مقادیر ممکن شامل bytes، Kbytes، KB، Mbytes، MB و غیره است. این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به pmParseUnitsStr(3). -B scale, --space-scale-force=scale مشابه -b اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد. -c config, --config=config مشخص کردن فایل یا پوشه config مورد استفاده. در صورتی که config یک پوشه باشد، تمام فایل‌های درون آن که به .conf ختم می‌شوند گنجانده خواهند شد. پیش‌فرض نخستین موردی است که از میان موارد زیر یافت شود: ./pcp2xml.conf، $HOME/.pcp2xml.conf، $HOME/pcp/pcp2xml.conf و $PCP_SYSCONF_DIR/pcp2xml.conf. برای جزئیات، بخش بالا و pmrep.conf(5) را ببینید. --container=container واکشی معیارهای کارایی از کانتینر مشخص‌شده container، خواه محلی یا دوردست (نگاه کنید به -h). -C, --check خروج پیش از گزارش هرگونه مقدار، اما پس از تجزیه پیکربندی و معیارها و چاپ هدرهای احتمالی. --daemonize اجرا به صورت دیمن در زمان راه‌اندازی. -e derived, --derived=derived مشخص کردن معیارهای کارایی مشتق‌شده (derived). اگر derived با یک اسلش (``/'') یا با یک نقطه (``.'') شروع شود، به عنوان یک فایل پیکربندی معیارهای مشتق‌شده PCP تفسیر خواهد شد؛ در غیر این صورت به عنوان عبارات معیارهای مشتق‌شده جداشده با کاما یا نقطه‌ویرگول تفسیر می‌شود. برای شرح کامل معیارهای مشتق‌شده و فایل‌های پیکربندی معیارهای مشتق‌شده PCP به pmLoadDerivedConfig(3) و pmRegisterDerived(3) مراجعه کنید. همچنین، استفاده از نحو پیکربندی pmrep.conf(5) اجازه می‌دهد معیارهای مشتق‌شده را به عنوان بخشی از مجموعه‌معیارها (metricsets) تعریف کنید. در صورت بروز مشکل در معیارهای مشتق‌شده، صفحات راهنمای یادشده را به دقت مرور کنید و مطمئن شوید که تمام معیارهای مورد نیاز در دسترس هستند، به ویژه هنگام استفاده از بایگانی‌ها. از -Dderive برای مشاهده اطلاعات اشکال‌زدایی بیشتر درباره تجزیه معیارهای مشتق‌شده استفاده کنید. -G, --no-globals عدم گنجاندن معیارهای سراسری در گزارش (نگاه کنید به pmrep.conf(5)). -f format, --timestamp-format=format استفاده از رشته format برای قالب‌بندی برچسب زمانی. این قالب با متد datetime.strftime پایتون استفاده خواهد شد که عمدتاً مشابه با موارد شرح‌داده‌شده در strftime(3) است. پیش‌فرض %Y-%m-%d %H:%M:%S است. -F outfile, --output-file=outfile مشخص کردن فایل خروجی outfile. -h host, --host=host واکشی معیارهای کارایی از pmcd(1) روی host، به جای پیش‌فرض localhost. -H, --no-header عدم چاپ هیچ‌گونه هدر. -i instances, --instances=instances بازیابی و گزارش تنها نمونه‌های (instances) مشخص‌شده از معیار. به طور پیش‌فرض تمام نمونه‌ها، چه فعلی و چه آینده، گزارش می‌شوند. برای شرح کامل این گزینه به pmrep(1) مراجعه کنید. -I, --ignore-incompat نادیده گرفتن معیارهای ناسازگار. به طور پیش‌فرض معیارهای ناسازگار (یعنی نوع آن‌ها پشتیبانی نمی‌شود یا مقیاس آن‌ها طبق درخواست تغییر نمی‌کند) باعث توقف pcp2xml با یک پیام خطا می‌شوند. با این گزینه، تمام معیارهای ناسازگار بی سر و صدا از گزارش حذف می‌شوند. این ویژگی ممکن است به ویژه هنگام درخواست گره‌های غیربرگ درخت PMNS برای گزارش‌دهی مفید باشد. -j, --live-filter انجام فیلترسازی زنده نمونه‌ها. این قابلیت امکان ضبط تمام نمونه‌های نام‌گذاری‌شده را فراهم می‌کند حتی اگر فرآیندها در مقطعی مجدداً راه‌اندازی شوند (برخلاف حالت بدون فیلتر زنده). انجام فیلترسازی زنده روی تعداد بسیار زیادی از نمونه‌ها سربار داخلی اضافه خواهد کرد، بنابراین احتیاط کاربر توصیه می‌شود. همچنین نگاه کنید به -n. -J rank, --rank=rank محدود کردن نتایج به بالاترین/پایین‌ترین نمونه‌های رتبه‌بندی‌شده (ranked) از معیارهای چندمقداری. یک عدد صحیح مثبت، نمونه‌هایی با بالاترین مقدار را در گزارش لحاظ می‌کند. یک عدد صحیح منفی، نمونه‌هایی با پایین‌ترین مقدار را در گزارش لحاظ می‌کند. مقدار صفر هیچ رتبه‌بندی انجام نمی‌دهد. رتبه‌بندی به معنای مرتب‌سازی نیست، نگاه کنید به -6. همچنین نگاه کنید به -8. -K spec, --spec-local=spec هنگام واکشی معیارها از یک بافت محلی (نگاه کنید به -L)، گزینه -K می‌تواند برای کنترل PMDAهای DSO که باید در دسترس قرار گیرند استفاده شود. آرگومان spec مطابق با نحو توصیف‌شده در pmSpecLocalPMDA(3) است. می‌توان بیش از یک گزینه -K را استفاده کرد. -L, --local-PMDA استفاده از یک بافت محلی برای جمع‌آوری معیارها از PMDAهای DSO روی میزبان محلی بدون PMCD. همچنین نگاه کنید به -K. -m, --include-labels گنجاندن برچسب‌های معیار PCP در خروجی. -n, --invert-filter انجام رتبه‌بندی پیش از فیلترسازی زنده. به طور پیش‌فرض فیلترسازی زنده نمونه‌ها (در صورت درخواست، نگاه کنید به -j) پیش از رتبه‌بندی نمونه‌ها (در صورت درخواست، نگاه کنید به -J) انجام می‌شود. با این گزینه منطق وارونه شده و رتبه‌بندی پیش از فیلترسازی زنده رخ می‌دهد. -N predicate, --predicate=predicate مشخص کردن یک فهرست جداشده با کاما از معیارهای مرجع فیلتر گزاره‌ای (predicate). به طور پیش‌فرض رتبه‌بندی (نگاه کنید به -J) برای هر معیار به طور جداگانه صورت می‌گیرد. با گزاره‌ها، رتبه‌بندی تنها برای معیارهای گزاره‌ای مشخص‌شده انجام می‌شود. هنگام گزارش‌دهی، بقیه معیارهایی که دامنه نمونه یکسانی دارند (instance domain، نگاه کنید به PCPIntro(1)) با گزاره، تنها شامل نمونه‌هایی با بالاترین/پایین‌ترین رتبه از گزاره متناظر خواهند بود. رتبه‌بندی به معنای مرتب‌سازی نیست، نگاه کنید به -6. بنابراین به عنوان مثال، با استفاده از proc.memory.rss (اندازه حافظه مقیم فرآیند) به عنوان معیار predicate همراه با proc.io.total_bytes و mem.util.used به عنوان معیارهایی که باید گزارش شوند، تنها فرآیندهایی که بیشترین/کمترین حافظه را (طبق -J) مصرف می‌کنند، هنگام گزارش مجموع بایت‌های نوشته‌شده توسط فرآیندها لحاظ خواهند شد. از آنجا که mem.util.used یک معیار تک‌مقداری است (و بنابراین دامنه نمونه یکسانی با معیارهای مربوط به فرآیند به اشتراک نمی‌گذارد)، مانند معمول گزارش خواهد شد. -O origin, --origin=origin هنگام گزارش معیارهای بایگانی‌شده، شروع گزارش در مبدأ origin درون پنجره زمانی (نگاه کنید به -S و -T). برای شرح کامل نحو origin، به PCPIntro(1) مراجعه کنید. -P precision, --precision=precision استفاده از precision برای مقادیر خروجی عددی غیرصحیح. پیش‌فرض استفاده از ۳ رقم اعشار است (در صورت کاربرد). این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. -q scale, --count-scale=scale واحد/مقیاس برای معیارهای شمارشی، مقادیر ممکن شامل count x 10^-1، count، count x 10، count x 10^2 و به همین ترتیب از 10^-8 تا 10^7 است. (این مقادیر در حال حاضر به فاصله‌ها حساس هستند.) این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به pmParseUnitsStr(3). -Q scale, --count-scale-force=scale مشابه -q اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد. -r, --raw خروجی دادن مقادیر خام معیارها؛ شمارنده‌های انباشته به نرخ تبدیل نمی‌شوند. این گزینه مشخصات احتمالی به ازای هر معیار را لغو و جایگزین خواهد کرد. -R, --raw-prefer مشابه -r اما این گزینه مشخصات به ازای هر معیار را لغو نخواهد کرد. -s samples, --samples=samples آرگومان samples تعداد نمونه‌هایی را که باید بازیابی و گزارش شوند مشخص می‌کند. اگر samples برابر ۰ باشد یا -s مشخص نشده باشد، pcp2xml به طور مداوم (در حالت بلادرنگ) یا تا انتهای مجموعه بایگانی‌های PCP (در حالت بایگانی) نمونه‌برداری و گزارش خواهد کرد. همچنین نگاه کنید به -T. -S starttime, --start=starttime هنگام گزارش معیارهای بایگانی‌شده، گزارش محدود به رکوردهایی خواهد بود که در زمان starttime یا پس از آن ثبت شده‌اند. برای شرح کامل نحو starttime، به PCPIntro(1) مراجعه کنید. -t interval, --interval=interval تنظیم interval گزارش‌دهی روی مقداری غیر از پیش‌فرض ۱ ثانیه. آرگومان interval از نحو توصیف‌شده در PCPIntro(1) پیروی می‌کند، و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد (واحدهای ضمنی در این حالت ثانیه هستند). همچنین گزینه -T را ببینید. -T endtime, --finish=endtime هنگام گزارش معیارهای بایگانی‌شده، گزارش محدود به رکوردهایی خواهد بود که پیش از endtime یا در همان زمان ثبت شده‌اند. برای شرح کامل نحو endtime، به PCPIntro(1) مراجعه کنید. هنگامی که برای تعیین مدت زمان اجرا پیش از خروج pcp2xml استفاده می‌شود، اگر هیچ مقداری برای samples تعیین نشده باشد (نگاه کنید به -s)، تعداد نمونه‌های گزارش‌شده به interval بستگی خواهد داشت (نگاه کنید به -t). اگر samples تعیین شده باشد، interval به گونه‌ای تنظیم می‌شود که اجازه گزارش‌دهی samples را در طول زمان اجرا بدهد. در صورتی که هر سه گزینه -T، -s و -t تعیین شده باشند، endtime زمان واقعی اجرای pcp2xml را تعیین می‌کند. -v, --omit-flat تنها معیارهای چندمقداری دارای نمونه (مانند disk.dev.read) را گزارش کرده و معیارهای تک‌مقداری «مسطح» بدون نمونه (مانند kernel.all.sysfork) را حذف می‌کند. نگاه کنید به -i و -I. -V, --version نمایش شماره نسخه و خروج. -x, --with-extended نوشتن اطلاعات گسترش‌یافته. -X, --with-everything نوشتن تمام اطلاعات شناخته‌شده درباره معیارها، از جمله شناسه‌های داخلی PCP. با این حال برچسب‌ها برای سازگاری با گذشته حذف شده‌اند؛ برای گنجاندن آن‌ها نیز از -m استفاده کنید. -y scale, --time-scale=scale واحد/مقیاس برای معیارهای زمانی، مقادیر ممکن شامل nanosec، ns، microsec، us، millisec، ms و به همین ترتیب تا hour، hr است. این گزینه مشخصات احتمالی به ازای هر معیار را لغو نخواهد کرد. همچنین نگاه کنید به pmParseUnitsStr(3). -Y scale, --time-scale-force=scale مشابه -y اما این گزینه مشخصات به ازای هر معیار را لغو و جایگزین خواهد کرد. -z, --hostzone استفاده از منطقه زمانی محلی میزبانی که منبع معیارهای کارایی است، همان‌طور که توسط گزینه‌های -h یا -a مشخص شده است. پیش‌فرض استفاده از منطقه زمانی میزبان محلی است. -Z timezone, --timezone=timezone استفاده از timezone برای تاریخ و زمان. Timezone در قالب متغیر محیطی TZ مطابق با آنچه در environ(7) شرح داده شده است. توجه داشته باشید که هنگام گنجاندن رشته منطقه زمانی در خروجی، از آفست‌های UTC به سبک ISO 8601 استفاده می‌شود (بنابراین موردی مانند -Z EST+5 به UTC-5 تبدیل خواهد شد). -?, --help نمایش پیام راهنما و خروج. فایل‌ها (FILES) pcp2xml.conf فایل پیکربندی pcp2xml (نگاه کنید به -c) $PCP_SYSCONF_DIR/pmrep/*.conf فایل‌های پیکربندی پیش‌فرض pmrep ارائه‌شده توسط سیستم محیط PCP (PCP ENVIRONMENT) متغیرهای محیطی با پیشوند PCP_ برای پارامتریک‌سازی نام فایل‌ها و پوشه‌های مورداستفاده توسط PCP استفاده می‌شوند. در هر نصب، فایل /etc/pcp.conf حاوی مقادیر محلی برای این متغیرها است. متغیر $PCP_CONF می‌تواند برای مشخص کردن یک فایل پیکربندی جایگزین، همان‌طور که در pcp.conf(5) توصیف شده، استفاده شود. برای متغیرهای محیطی اثرگذار بر ابزارهای PCP، به pmGetOptions(3) مراجعه کنید. به طور ویژه، PCP_DISCRETE_ONCE می‌تواند تنظیم شود تا اطمینان حاصل شود که مقادیر گسسته معیارها تنها یک‌بار گزارش می‌شوند، مگر اینکه در مقطعی تغییر کنند. گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS) گزینه -D یا --debug خروجی اطلاعات تشخیصی اضافی را روی stderr فعال می‌کند تا به تفکیک و عیب‌یابی مشکلات کمک کند، اگرچه اطلاعات گاهی پیچیده و مبهم بوده و در درجه اول برای راهنمایی توسعه‌دهندگان به جای کاربران نهایی در نظر گرفته شده است. debug یک فهرست جداشده با کاما از گزینه‌های اشکال‌زدایی است؛ از pmdbg(1) با گزینه -l برای دریافت فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید. همچنین ببینید (SEE ALSO) 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). Performance Co-Pilot PCP PCP2XML(1)