PCP2OPENTELEMETRY(1) General Commands Manual PCP2OPENTELEMETRY(1) نام (NAME) pcp2opentelemetry - صادرکننده pcp به opentelemetry خلاصه دستور (SYNOPSIS) pcp2opentelemetry [-5CEGHIjLmnrRvVxXz?] [-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 timeout] [-O origin] [-p password] [-P|-0 precision] [-q|-Q count-scale] [-s samples] [-S starttime] [-t interval] [-T endtime] [-u url] [-U username] [-y|-Y time-scale] [-Z timezone] metricspec [...] توضیحات (DESCRIPTION) ابزار pcp2opentelemetry یک ابزار سفارشی‌پذیر برای صادر کردن معیارهای کارایی از PCP به قالب OpenTelemetry - https://opentelemetry.io - است. هر معیار کارایی موجود، چه زنده و چه بایگانی‌شده، سیستمی و/یا برنامه‌ای را می‌توان با استفاده از آرگومان‌های خط فرمان یا یک فایل پیکربندی برای صادر کردن انتخاب کرد. ابزار pcp2opentelemetry خویشاوندی نزدیکی با pmrep(1) دارد. برای مشاهده شرح metricspec پذیرفته‌شده در خط فرمان pcp2opentelemetry، به pmrep(1) مراجعه کنید. برای شرح ساختار فایل پیکربندی pcp2opentelemetry.conf به pmrep.conf(5) مراجعه کنید. این صفحه گزینه‌های اختصاصی pcp2opentelemetry و تفاوت‌های فایل پیکربندی آن با pmrep.conf(5) را شرح می‌دهد. pmrep(1) همچنین مثال‌های متعددی از کاربرد را فهرست می‌کند که بیشتر آن‌ها برای pcp2opentelemetry نیز قابل استفاده هستند. تنها گزینه‌های خط فرمان فهرست‌شده در این صفحه پشتیبانی می‌شوند؛ سایر گزینه‌های موجود برای pmrep(1) پشتیبانی نمی‌شوند. گزینه‌های مشخص‌شده از طریق مقادیر متغیرهای محیطی (ببینید: pmGetOptions(3)) بر مقادیر پیش‌فرض توکار متناظر (در صورت وجود) مقدم هستند. گزینه‌های فایل پیکربندی بر متغیرهای محیطی متناظر (در صورت وجود) تقدم دارند. گزینه‌های خط فرمان نیز بر گزینه‌های متناظر فایل پیکربندی (در صورت وجود) مقدم خواهند بود. فایل پیکربندی (CONFIGURATION FILE) pcp2opentelemetry از یک فایل پیکربندی با ساختار شرح داده‌شده در 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 شناسایی می‌شوند اما جهت سازگاری نادیده گرفته می‌شوند..SS گزینه‌های اختصاصی pcp2opentelemetry url (string) ارسال خروجی OpenTelemetry به صورت یک HTTP POST به url ارائه‌شده. گزینهٔ خط فرمان متناظر -u است. پیش‌فرض None است. http_pass (string) استفاده از گذرواژهٔ ارائه‌شده برای احراز هویت پایه‌ای (Basic Authentication) هنگام ارسال یک HTTP POST. گزینهٔ خط فرمان متناظر -p است. پیش‌فرض None است. http_user (string) استفاده از نام کاربری ارائه‌شده برای احراز هویت پایه‌ای (Basic Authentication) هنگام ارسال یک HTTP POST. گزینهٔ خط فرمان متناظر -U است. پیش‌فرض None است. http_timeout (number) حداکثر زمان (به ثانیه) هنگام ارسال یک HTTP POST. گزینهٔ خط فرمان متناظر -o است. پیش‌فرض 2.5 ثانیه است. گزینه‌ها (OPTIONS) گزینه‌های خط فرمان موجود عبارتند از: -0 precision, --precision-force=precision مانند -P است، اما این گزینه مشخصات اختصاصی هر متریک را بازنویسی خواهد کرد. -4 action, --names-change=action مشخص می‌کند که هنگام دریافت یک رویداد تغییر نام متریک در طول نمونه‌برداری، چه action (اقدامی) انجام گیرد. این رویدادها زمانی رخ می‌دهند که یک PMDA مدتی پس از راه‌اندازی، متریک‌های جدیدی را شناسایی کرده و به ابزارهای کلاینت در حال اجرا مانند pcp2opentelemetry اطلاع‌رسانی کند. مقادیر معتبر برای 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 خواندن بایگانی‌های منبع متریک از folio (برگه‌دان) بایگانی PCP ایجادشده توسط ابزارهایی مانند 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 خاتمه می‌یابند لحاظ خواهند شد. پیش‌فرض اولین مورد یافت‌شده از میان موارد زیر است: ./pcp2opentelemetry.conf، $HOME/.pcp2opentelemetry.conf، $HOME/pcp/pcp2opentelemetry.conf و $PCP_SYSCONF_DIR/pcp2opentelemetry.conf. برای جزئیات بیشتر، به بخش بالا و pmrep.conf(5) مراجعه کنید. --container=container واکشی متریک‌های کارایی از container مشخص‌شده، به‌صورت محلی یا از راه دور (نگاه کنید به -h). -C, --check خروج پیش از گزارش هرگونه مقدار، اما پس از تجزیهٔ پیکربندی و متریک‌ها و چاپ سرایندهای احتمالی. --daemonize اجرا به صورت دیمِن (Daemonize) در هنگام راه‌اندازی. -e derived, --derived=derived تعیین متریک‌های کارایی derived (مشتق‌شده). اگر derived با یک اسلش (``/'') یا با یک نقطه (``.'') آغاز شود، به عنوان یک فایل پیکربندی متریک‌های مشتق‌شدهٔ PCP تفسیر می‌شود؛ در غیر این صورت به صورت عبارت‌های متریک مشتق‌شده که با کاما یا نقطه-ویرگول از هم جدا شده‌اند تفسیر خواهد شد. برای شرح کامل متریک‌های مشتق‌شده و فایل‌های پیکربندی متریک‌های مشتق‌شدهٔ PCP، به pmLoadDerivedConfig(3) و pmRegisterDerived(3) مراجعه کنید. علاوه بر این، استفاده از نحو پیکربندی pmrep.conf(5) امکان تعریف متریک‌های مشتق‌شده را به عنوان بخشی از مجموعه‌متریک‌ها (metricsets) فراهم می‌کند. -E, --exact-types نوشتن اعداد در قالب نوع‌داده‌های عددی و نه به عنوان رشته، که ممکن است تا حدی موجب کاهش دقت شود. -f format, --timestamp-format=format استفاده از رشتهٔ format برای قالب‌بندی برچسب زمانی. این قالب به همراه متد datetime.strftime پایتون استفاده خواهد شد که تا حد زیادی مشابه موارد توصیف‌شده در strftime(3) است. پیش‌فرض %Y-%m-%d %H:%M:%S است. -F outfile, --output-file=outfile مشخص کردن فایل خروجی outfile. -G, --no-globals عدم گنجاندن متریک‌های سراسری در گزارش (نگاه کنید به pmrep.conf(5)). -h host, --host=host واکشی متریک‌های کارایی از pmcd(1) روی host، به جای localhost پیش‌فرض. -H, --no-header عدم چاپ هیچ‌گونه سرایند. -i instances, --instances=instances تنها نمونه‌های (instances) مشخص‌شدهٔ متریک را بازیابی و گزارش می‌کند. به‌طور پیش‌فرض تمام نمونه‌ها، چه فعلی و چه آینده، گزارش می‌شوند. برای شرح کامل این گزینه به pmrep(1) مراجعه کنید. -I, --ignore-incompat نادیده گرفتن معیارهای ناسازگار. به‌طور پیش‌فرض معیارهای ناسازگار (یعنی نوع آن‌ها پشتیبانی نمی‌شود یا نمی‌توان آن‌ها را مطابق درخواست مقیاس‌بندی کرد) باعث می‌شوند که pcp2opentelemetry با یک پیام خطا خاتمه یابد. با این گزینه، تمام معیارهای ناسازگار بدون هشدار از گزارش‌گیری حذف می‌شوند. این موضوع به‌ویژه هنگام درخواست گره‌های غیربرگ درخت PMNS برای گزارش‌گیری می‌تواند مفید باشد. -j, --live-filter انجام فیلترسازی زندهٔ نمونه‌ها. این کار امکان دریافت تمام نمونه‌های نام‌گذاری‌شده را حتی در صورت راه‌اندازی مجدد فرایندها در طول زمان فراهم می‌کند (برخلاف حالت بدون فیلترسازی زنده). انجام فیلترسازی زنده روی تعداد بسیار زیادی از نمونه‌ها، بار اضافی داخلی ایجاد می‌کند؛ بنابراین کمی احتیاط از سوی کاربر توصیه می‌شود. همچنین ببینید -n. -J rank, --rank=rank محدود کردن نتایج به بالاترین/پایین‌ترین نمونه‌های رتبه‌بندی‌شده بر اساس rank در معیارهای چندمقداری (set-valued). یک عدد صحیح مثبت، نمونه‌های دارای بالاترین مقدار را در گزارش لحاظ می‌کند. یک عدد صحیح منفی، نمونه‌های دارای کمترین مقدار را در گزارش لحاظ می‌کند. مقدار صفر هیچ رتبه‌بندی‌ای انجام نمی‌دهد. رتبه‌بندی به معنای مرتب‌سازی نیست، ببینید -6. همچنین ببینید -8. -K spec, --spec-local=spec هنگام واکشی معیارها از یک بافت محلی (ببینید -L)، گزینهٔ -K می‌تواند برای کنترل DSO PMDAهایی که باید در دسترس قرار گیرند استفاده شود. آرگومان spec از نحو شرح‌داده‌شده در pmSpecLocalPMDA(3) پیروی می‌کند. می‌توان بیش از یک گزینهٔ -K را استفاده کرد. -L, --local-PMDA استفاده از یک بافت محلی برای جمع‌آوری معیارها از DSO PMDAها روی میزبان محلی بدون PMCD. همچنین ببینید -K. -n, --invert-filter انجام رتبه‌بندی پیش از فیلترسازی زنده. به‌طور پیش‌فرض، فیلترسازی زندهٔ نمونه‌ها (در صورت درخواست، ببینید -j) قبل از رتبه‌بندی نمونه‌ها (در صورت درخواست، ببینید -J) انجام می‌شود. با این گزینه، منطق برعکس شده و رتبه‌بندی پیش از فیلترسازی زنده اتفاق می‌افتد. -m, --include-labels گنجاندن برچسب‌های معیارهای PCP در خروجی. -N predicate, --predicate=predicate مشخص کردن فهرستی از معیارهای مرجع فیلتر گزاره‌ای (predicate) که با کاما جدا شده‌اند. به‌طور پیش‌فرض، رتبه‌بندی (ببینید -J) برای هر معیار به‌صورت مجزا انجام می‌شود. با گزاره‌ها، رتبه‌بندی تنها برای معیارهای گزاره‌ایِ مشخص‌شده انجام می‌گیرد. هنگام گزارش‌گیری، باقی معیارهایی که با گزاره دامنهٔ نمونهٔ مشترک دارند (ببینید PCPIntro(1))، تنها شامل نمونه‌هایی با بالاترین/پایین‌ترین رتبه از گزارهٔ مربوطه خواهند بود. رتبه‌بندی به معنای مرتب‌سازی نیست، ببینید -6. برای نمونه، استفاده از proc.memory.rss (اندازهٔ حافظهٔ مقیم فرایند) به‌عنوان معیار predicate همراه با proc.io.total_bytes و mem.util.used به‌عنوان معیارهای قابل گزارش، موجب می‌شود تنها فرایندهایی که بیشترین/کمترین حافظه را (مطابق -J) مصرف می‌کنند، در گزارش مجموع بایت‌های نوشته‌شده توسط فرایندها گنجانده شوند. از آنجا که mem.util.used یک معیار تک‌مقداری است (و بنابراین دامنهٔ نمونهٔ مشترکی با معیارهای مرتبط با فرایند ندارد)، طبق معمول گزارش خواهد شد. -o, --http-timeout زمان انتظار (به ثانیه) هنگام ارسال یک HTTP POST با گزینهٔ -u. مقدار پیش‌فرض 2.5 ثانیه است. -O origin, --origin=origin هنگام گزارش معیارهای بایگانی‌شده، شروع گزارش‌گیری از origin درون بازهٔ زمانی (ببینید -S و -T). برای توضیحات کامل دربارهٔ نحو origin، به PCPIntro(1) مراجعه کنید. -p, --http-pass گذرواژه هنگام استفاده از احراز هویت پایه‌ایِ HTTP با گزینهٔ -u. -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 برابر با 0 باشد یا -s مشخص نشده باشد، pcp2opentelemetry به‌صورت پیوسته نمونه‌برداری و گزارش می‌دهد (در حالت بی‌درنگ) یا تا انتهای مجموعه بایگانی‌های 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) مراجعه کنید. هنگامی که برای تعیین مدت‌زمان اجرا پیش از خروج pcp2opentelemetry استفاده می‌شود، چنانچه هیچ samples (تعداد نمونه‌ای) مشخص نشده باشد (به -s مراجعه کنید)، تعداد نمونه‌های گزارش‌شده به interval (بازهٔ زمانی) بستگی خواهد داشت (به -t مراجعه کنید). اگر samples داده شده باشد، آنگاه interval به‌گونه‌ای تنظیم می‌شود تا امکان گزارش samples در طول مدت‌زمان اجرا فراهم گردد. در صورتی که هر سه گزینهٔ -T، -s و -t مشخص شده باشند، endtime زمان واقعی اجرای pcp2opentelemetry را تعیین می‌کند. -u, --url آدرس URL برای ارسال یک درخواست HTTP POST (به‌جای خروجی استاندارد پیش‌فرض). -U, --http-user نام کاربری هنگام استفاده از احراز هویت اولیهٔ HTTP (Basic Authentication) با گزینهٔ -u. -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) pcp2opentelemetry.conf فایل پیکربندی pcp2opentelemetry (به -c مراجعه کنید) $PCP_SYSCONF_DIR/pmrep/*.conf فایل‌های پیکربندی پیش‌فرض pmrep ارائه‌شده توسط سیستم محیط 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 برای به‌دست آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید..SH "همچنین ببینید (SEE ALSO)" PCPIntro(1)، mkaf(1)، pcp(1)، pcp2elasticsearch(1)، pcp2graphite(1)، pcp2influxdb(1)، pcp2openmetrics(1)، pcp2spark(1)، pcp2xlsx(1)، pcp2xml(1)، pcp2json(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 PCP2OPENTELEMETRY(1)