PMPROXY(1) General Commands Manual PMPROXY(1)

pmproxy - پیشکاری برای گردآوری و پرس‌وجوی معیارهای کارایی

pmproxy [-AdfFt?] [-c conffile] [-D debug] [-h host[,host ...] [-i ipaddress] [-l logfile] [-L bytes] [-p port[,port ...] [-r port[,port ...] [-s sockname] [-U username] [-x outfile]

دستور pmproxy به‌عنوان یک پیشکار پروتکل عمل می‌کند و به کلاینت‌های پایش Performance Co-Pilot (PCP) اجازه می‌دهد تا به‌صورت غیرمستقیم به یک یا چند سرور pmcd(1) و/یا سرورهای کلید-مقدار (مانند https://valkey.io) متصل شوند.

در حالت کارکرد پیش‌فرض، pmproxy یک REST API برای سرویس‌های PCP ارائه می‌دهد (برای جزئیات به PMWEBAPI(3) مراجعه کنید). این قابلیت‌ها شامل ارائه یک رابط متنی Open Metrics - https://openmetrics.io - برای معیارهای PCP در /metrics، دسترسی آنی به معیارهای PCP از طریق رابط‌های /pmapi، و دسترسی به قابلیت‌های سریع و مقیاس‌پذیر پرس‌وجوی سری زمانی PCP ارائه‌شده در هماهنگی با یک سرور کلید-مقدار (برای جزئیات به pmseries(1) مراجعه کنید) از طریق رابط‌های REST در /query است.

دستور pmproxy می‌تواند در یک دامنه فایروال یا روی گره «سَر» (head) کلاستر مستقر شود؛ در جایی که آدرس IP میزبان‌های ارائه‌دهنده pmcd و/یا سرور کلید-مقدار (مانند https://valkey.io) ممکن است برای کلاینت‌های پایش PCP ناشناخته باشد، اما آدرس IP میزبانی که pmproxy را اجرا می‌کند برای این کلاینت‌ها مشخص است. به‌طور مشابه، کلاینت‌ها ممکن است تنها دسترسی شبکه‌ای به میزبانی داشته باشند که pmproxy روی آن اجرا می‌شود، در حالی که از آن میزبان دسترسی شبکه به میزبان‌های هدفِ اجراکننده pmcd و/یا سرور کلید-مقدار وجود دارد.

رفتار کلاینت‌های پایش PCP یا توسط متغیر محیطی PMPROXY_HOST یا از طریق مشخصات گسترش‌یافته نام میزبان کنترل می‌شود (برای جزئیات به PCPIntro(1) مراجعه کنید). اگر از هیچ‌کدام از این سازوکارها استفاده نشود، کلاینت‌ها اتصالات PMAPI(3) خود را مستقیماً به pmcd برقرار می‌کنند. اگر نحوِ نام میزبان پیشکار استفاده شود یا متغیر PMPROXY_HOST تنظیم شده باشد، این مقدار باید نام میزبان یا آدرس IP سیستمی باشد که pmproxy روی آن اجرا می‌شود، و کلاینت‌ها به‌صورت غیرمستقیم و از طریق سرویس‌های پیشکار پروتکلِ pmproxy به pmcd یا سرور کلید-مقدار متصل خواهند شد.

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

غیرفعال‌سازی اعلان سرویس (advertisement). به‌طور پیش‌فرض، pmproxy حضور خود در شبکه را با استفاده از هر سازوکارِ موجود اعلان می‌کند و به ابزارهای پایش از راه دور در پیدا کردن آن کمک می‌رساند. با این گزینه، سازوکارهای یادشده غیرفعال می‌شوند.
مسیر یک فایل پیکربندی اختیاری conffile را با قالبی که در بخش «CONFIGURATION» توضیح داده شده است مشخص می‌کند. این گزینه به این معنی است که pmproxy در حالت timeseries اجرا می‌شود.
به‌طور پیش‌فرض، pmproxy ترجیح می‌دهد در حالت جدید timeseries اجرا شود و REST API، ورودی/خروجی شبکه ناهمگام، سری‌های زمانی مقیاس‌پذیر و اتصالات امن با استفاده از OpenSSL را فراهم کند. با این حال، در استقرارهای قدیمی ممکن است استفاده از پیاده‌سازی همگام و اصلی pmproxy با استفاده از بخش شبکه libpcp ترجیح داده شود؛ این حالت با استفاده از این گزینه قابل دستیابی است. توجه داشته باشید که گزینه‌های -d و -t ناسازگار با یکدیگر (مانعة‌الجمع) هستند.
به‌طور پیش‌فرض، pmproxy به‌صورت یک دیمن راه‌اندازی می‌شود. گزینه -f مشخص می‌کند که برنامه باید در پیش‌زمینه اجرا شود. این گزینه هنگام تلاش برای عیب‌یابی مشکلات در برقراری اتصال بسیار کاربردی است.
مانند -f، گزینه -F نیز pmproxy را در پیش‌زمینه اجرا می‌کند، اما برخی کارهای مدیریتی داخلی (مانند ایجاد فایل «pid» و تغییر شناسه کاربر) را نیز انجام می‌دهد. این گزینه برای مواقعی در نظر گرفته شده که pmproxy توسط systemd(1) یا launchd(1) اجرا شده و دیمن‌سازی از پیش توسط systemd(1) یا launchd(1) انجام گرفته است و نیازی به انجام مجدد آن توسط pmproxy نیست؛ وضعیتی که هنگام مشخص نکردن هیچ‌یک از گزینه‌های -f یا -F رخ می‌دهد.

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

میزبانِ ( host) جایگزین سرور کلید-مقدار را برای اتصال جهت پرس‌وجوی سری‌های زمانی مشخص می‌کند و بر تمام تنظیمات فایل پیکربندی تقدم دارد. این گزینه به این معنی است که pmproxy در حالت timeseries اجرا می‌شود.
این گزینه معمولاً فقط روی میزبان‌هایی با بیش از یک رابط شبکه استفاده می‌شود (امری رایج برای میزبان‌های فایروال و گره «head» که در آن‌ها pmproxy برای مدیریت دسترسی به یک شبکه داخلی مستقر شده است). اگر هیچ گزینه -i مشخص نشده باشد، pmproxy اتصالات کلاینت PCP را روی هر یک از آدرس‌های IP میزبان خود می‌پذیرد. گزینه -i برای مشخص کردن صریح یک آدرس IP که اتصالات کلاینت PCP باید روی آن پذیرفته شوند به کار می‌رود. مقدار ipaddress باید در قالب استاندارد نقطه‌دار باشد (مانند 100.23.45.6). گزینه -i می‌تواند چندین بار برای تعریف فهرستی از آدرس‌های IP استفاده شود. در صورت مشخص شدن یک یا چند گزینه -i ، تلاش برای اتصال روی هر آدرس IP دیگری رد خواهد شد..TP -l logfile, --log=logfile به‌طور پیش‌فرض یک فایل گزارش رویداد (لاگ) با نام pmproxy.log در دایرکتوری جاری نوشته می‌شود. گزینهٔ -l باعث می‌شود فایل گزارش رویداد به جای پیش‌فرض، در logfile مشخص‌شده نوشته شود. اگر این logfile قابل ایجاد نباشد یا نتوان در آن نوشت، خروجی به‌جای آن به خطای استاندارد (standard error) ارسال می‌شود.
PDUهای دریافتی توسط pmproxy از کلاینت‌های پایشگر PCP، به‌طور پیش‌فرض به حداکثر اندازهٔ ۶۵۵۳۶ بایت محدود شده‌اند تا در برابر حملات منع سرویس (Denial of Service) مقابله شود. گزینهٔ -L می‌تواند برای تغییر حداکثر اندازهٔ PDU ورودی استفاده شود.
یک شمارهٔ port جایگزین را برای گوش دادن به اتصالات کلاینت مشخص می‌کند. مقدار پیش‌فرض 44322 است.
الزام می‌کند که تمامی اتصالات کلاینت، یک گواهی کلاینت (client certificate) معتبر ارائه دهند.
یک شمارهٔ port جایگزین برای اتصال به سرور کلید-مقدار (key-value) جهت پرس‌وجوی سری‌های زمانی مشخص می‌کند، که بر هرگونه تنظیمات فایل پیکربندی ارجحیت دارد. این گزینه به این معناست که pmproxy در حالت timeseries اجرا می‌شود.
مسیر یک سوکت محلی دامنهٔ یونیکس (unix domain socket) را مشخص می‌کند (تنها برای پلتفرم‌هایی که از این خانوادهٔ سوکت پشتیبانی می‌کنند). مقدار پیش‌فرض $PCP_RUN_DIR/pmproxy.socket است. این گزینه به این معناست که pmproxy در حالت timeseries اجرا می‌شود.
الزام می‌کند که تمام اتصالات کلاینت احراز هویت شوند.
در حالت کشف خودکار سری‌های زمانی آرشیو (archive timeseries discovery) اجرا می‌شود. این حالت کاری، رابط‌های برنامه‌نویسی PMWEBAPI(3) REST را فعال می‌کند، آرشیوهای فعال سیستم را که توسط pmlogger(1) نوشته می‌شوند به‌طور پویا و خودکار شناسایی کرده و آن‌ها را به یک سرور کلید-مقدار (مانند https://valkey.io) وارد می‌کند تا امکان پرس‌وجوی سریع و مقیاس‌پذیر سری‌های زمانی که در pmseries(1) شرح داده شده است، فراهم شود. توجه داشته باشید که در این حالت کاری، pmproxy تنها آرشیوهای فعال در حال رشد را دنبال (log-tail) و بارگیری (ingest) می‌کند؛ مانند آرشیوهایی که توسط یک یا چند نمونه از pmlogger(1) نوشته می‌شوند. هنگامی که یک آرشیو برای نخستین بار کشف می‌شود (معمولاً، اما نه لزوماً، در زمان راه‌اندازی pmproxy)، تمام فراداده‌ها بارگذاری شده و به سرور کلید-مقدارِ پیکربندی‌شده ارسال می‌شوند؛ با این حال دقت کنید که تنها داده‌های جدید مربوط به مقادیر معیارها از انتهای هر آرشیو بارگیری می‌شوند. آرشیوهای فشرده‌شده هرگز رشد نمی‌کنند و به همین دلیل نادیده گرفته می‌شوند. گزینهٔ --load در pmseries(1) را به عنوان سازوکاری پشتیبانی‌شده برای بارگذاری دستی تمامی داده‌های مقادیر معیار از آرشیوهای جمع‌آوری‌شدهٔ قبلی (غیرفعال)، چه فشرده باشند و چه نباشند، ببینید. طبیعی است، هرچند الزامی نیست، که مجموعه‌ای از آرشیوهای بارگذاری‌شده به‌صورت دستی، بازهٔ زمانی یکسانی را پوشش دهند؛ به عنوان مثال داده‌های آرشیو یک هفتهٔ بخصوص برای یک یا چند میزبان در یک مرکز دادهٔ یکسان.
پیش از شروع پذیرش بسته‌های ورودی از کلاینت‌های پایشگر PCP، هویت username مشخص‌شده را به خود می‌گیرد.
پیش از آنکه فایل گزارش رویدادِ ( logfile) pmproxy بتواند باز شود، ممکن است pmproxy با خطایی مرگبار مواجه شود که مانع از شروع به کار آن گردد. به‌طور پیش‌فرض، خروجی توصیف‌کنندهٔ این خطا به /dev/tty ارسال می‌شود، اما می‌توان آن را به outfile هدایت کرد.
-?, --help
نمایش پیام راهنمای استفاده و خروج.

هنگام اجرا در حالت کاری timeseries، پیکربندی زمان اجرا نسبتاً پیچیده بوده و به‌طور معمول از طریق فایل $PCP_SYSCONF_DIR/pmproxy/pmproxy.conf مدیریت می‌شود. این فایل در قالب متداول «ini» است، همراه با سرآیند بخش‌ها و متغیرها و مقادیر مجزا درون هر بخش. فایل پیکربندی نصب‌شده به عنوان بخشی از PCP، تمامی بخش‌ها و گزینه‌های موجود را مستند کرده است.

در یک نگاه کلی، از بخش [pmproxy] می‌توان برای فعال یا غیرفعال کردن صریح هر یک از پروتکل‌های مختلف استفاده کرد.

بخش [http] امکان تنظیم دقیق تنظیمات سرور HTTP مورد استفاده توسط pmproxy را فراهم می‌کند. متغیر chunksize اندازهٔ بافر کدگذاری انتقال تکه‌ای (chunked transfer encoding) را تعیین می‌کند و مقدار پیش‌فرض آن اندازهٔ صفحه سیستم (pagesize) است. تنظیمات پروتکل HTTP مربوط به کنترل دسترسی را می‌توان با استفاده از گزینه‌های Access-Control-Allow-Headers و Access-Control-Max-Age تنظیم کرد. بررسی این هدرهای پروتکل HTTP فراتر از حوزهٔ این سند است، اما مقادیر پیش‌فرض مناسب درون فایل پیکربندی pmproxy.conf شرح داده شده‌اند.

بخش [keys] امکان پیکربندی اطلاعات اتصال برای یک یا چند فرآیند سرور کلید-مقدار پشتیبان (نام‌های میزبان و پورت‌ها) را فراهم می‌آورد. توجه داشته باشید که برای دسترسی به چندین سرور کلید-مقدار (مقیاس‌پذیر)، متغیر servers در این بخش می‌تواند فهرستی از جفت‌های hostname:port باشد که با کاما از یکدیگر جدا شده‌اند. همچنین، می‌تواند یک سرور کلید-مقدار میزبان منفرد باشد که با استفاده از دستور «CLUSTER INFO» از آن پرس‌وجو خواهد شد تا چندین میزبان پشتیبان را به‌طور خودکار پیکربندی کند.

در نسخه‌های پیشین PCP (قبل از نسخه ۶)، بخش پیکربندی متفاوتی برای این منظور استفاده می‌شد - سرورهای کلید-مقدار servers در بخش [pmseries] مشخص می‌شدند و این شیوه همچنان به عنوان جایگزین پشتیبان برای سازگاری با گذشته پذیرفته می‌شود..SH "راه‌اندازی و توقف PMPROXY (STARTING AND STOPPING PMPROXY)" به‌طور معمول، pmproxy به‌صورت خودکار در زمان راه‌اندازی سیستم (boot time) آغاز به کار کرده و هنگام خاموش شدن سیستم متوقف می‌شود. در شرایط خاصی ممکن است راه‌اندازی یا توقف دستی pmproxy ضروری باشد. برای این کار باید دسترسی کاربر ریشه (superuser) را داشت و دستور

# $PCP_RC_DIR/pmproxy start

را برای راه‌اندازی pmproxy، یا دستور

# $PCP_RC_DIR/pmproxy stop

را برای توقف pmproxy وارد کرد. راه‌اندازی pmproxy در زمانی که از قبل در حال اجراست، همانند متوقف کردن و سپس راه‌اندازی دوباره آن است.

به‌طور معمول pmproxy برای اتصالات کلاینت‌های PCP روی شماره درگاه TCP/IP 44322 (و همچنین 44323 در صورت فعال بودن timeseries) که در https://www.iana.org ثبت شده است، گوش فرا می‌دهد. می‌توان از متغیر محیطی PMPROXY_PORT یا گزینه خط فرمان -p برای مشخص کردن شماره درگاه(های) جایگزین در هنگام راه‌اندازی pmproxy استفاده کرد؛ در هر دو حالت، مشخص‌سازی به شکل فهرستی از یک یا چند شماره درگاه عددی است که با کاما از هم جدا شده‌اند. اگر از هر دو روش استفاده شود یا چندین گزینه -p در خط فرمان قرار گیرد، pmproxy به اجتماع مجموعه درگاه‌های مشخص‌شده از طریق تمام گزینه‌های -p و متغیر محیطی PMPROXY_PORT گوش خواهد داد. اگر درگاه‌های غیرپیش‌فرض با pmproxy استفاده شوند، باید دقت کرد که PMPROXY_PORT در محیط هر برنامه کلاینتی که قصد اتصال به pmproxy را دارد نیز مقداردهی شده باشد، یا اینکه از نحو گسترش‌یافته مشخص‌سازی میزبان استفاده شود (برای جزئیات به PCPIntro(1) مراجعه کنید).

اگر pmproxy از قبل در حال اجرا باشد، پیام “Error: OpenRequestSocket bind: Address already in use” ظاهر خواهد شد. این پیام همچنین ممکن است زمانی ظاهر شود که pmproxy در حالی خاموش شده باشد که درخواستی از سوی یک کلاینت هنوز در حال انجام بوده است. در این حالت، یک سوکت درخواست در وضعیت TIME_WAIT باقی مانده است و تا زمانی که سیستم آن را نبندد (پس از سپری شدن دوره مهلت زمانی)، اجرای مجدد pmproxy امکان‌پذیر نخواهد بود.

علاوه بر گزینه‌های استاندارد اشکال‌زدایی PCP (ببینید pmdbg(1))، pmproxy در حال حاضر از گزینه اشکال‌زدایی context برای ردگیری برقراری و قطع اتصالات کلاینت پشتیبانی می‌کند.

$PCP_PMPROXYOPTIONS_PATH
گزینه‌های خط فرمان برای pmproxy هنگامی که از طریق $PCP_RC_DIR/pmproxy اجرا می‌شود. تمام خطوط مربوط به گزینه‌های خط فرمان باید با یک خط تیره (-) به عنوان اولین نویسه آغاز شوند.
$PCP_SYSCONFIG_DIR/pmproxy
متغیرهای محیطی که هنگام اجرای pmproxy تنظیم خواهند شد. تنها تنظیماتی به شکل “PMPROXY_VARIABLE=value” پذیرفته خواهند شد.
./pmproxy.log
(یا $PCP_LOG_DIR/pmproxy/pmproxy.log هنگامی که به‌طور خودکار راه‌اندازی می‌شود)
تمام پیام‌ها و گزارش‌های خطا به اینجا هدایت می‌شوند.
/etc/pki/tls
دایرکتوری پیش‌فرض پایگاه داده گواهی‌های OpenSSL که به‌صورت اختیاری برای اتصال Secure Socket Layer در حالت عملیاتی timeseries استفاده می‌شود. این گواهی‌ها را می‌توان از جمله با استفاده از ابزار openssl ایجاد و بررسی کرد.

علاوه بر متغیرهای محیطی PCP که در بخش PCP ENVIRONMENT در ادامه توضیح داده شده است، چندین متغیر محیطی دیگر وجود دارند که بر تعاملات میان یک کلاینت نظارتی PCP، pmproxy و pmcd تأثیر می‌گذارند.

برای کلاینت نظارتی PCP، این مقدار (یا شماره درگاه پیش‌فرض) به pmproxy ارسال شده و برای اتصال به pmcd استفاده می‌شود. در محیط pmproxy، متغیر PMCD_PORT استفاده نمی‌شود.
برای کلاینت نظارتی PCP، این متغیر نام میزبان یا نشانی IP میزبانی است که pmproxy روی آن اجرا می‌شود. در نسخه‌های اخیر PCP (از نسخه ۳ به بعد)، نحو گسترش‌یافته نام میزبان جایگزین این متغیر شده است (برای جزئیات به PCPIntro(1) مراجعه کنید).
برای کلاینت نظارتی PCP، این متغیر درگاهی است که pmproxy روی آن اتصالات را می‌پذیرد. مقدار پیش‌فرض 44322 و همچنین در صورت فعال بودن timeseries برابر با 44323 است.
(ببینید PCPIntro(1)) برای کلاینت نظارتی PCP، تنظیم این متغیرهای محیطی مهلت‌های زمانی مورد استفاده برای تعاملات بین کلاینت و pmproxy را تغییر می‌دهد (بدون توجه به اینکه کدام pmcd در حال استفاده است). برای pmproxy، همین متغیرهای محیطی مهلت‌های زمانی میان pmproxy و تمام نمونه‌های pmcd(1) را کنترل می‌کنند (بدون توجه به اینکه کدام کلاینت نظارتی دخیل است).

در صورت تنظیم روی مقدار 1، متغیر محیطی PMPROXY_LOCAL باعث خواهد شد که pmproxy تنها در حالت عملیاتی localhost اجرا شود، به طوری که تنها به رابط loopback متصل می‌گردد.

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

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

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

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

گزینه توضیحات
appl0 اتصال‌ها و قطع اتصال‌های کلاینت
appl1 حالت ثبت وقایع اضطراری (desperate logging)، که در آن یک نقطه و در ادامه PID مربوط به pmproxy در نام Rlogfile پیش از آخرین نقطه درج می‌شود؛ به‌طوری‌که مثلاً pmproxy.log به pmproxy.<pid>.log تبدیل می‌شود
appl2 ثبت وقایع URLهای ورودی HTTP (این مورد با گزینهٔ اشکال‌زدایی http نیز فعال می‌شود، اما دومی دامنهٔ گسترده‌تری دارد زیرا اشکال‌زدایی را در کتابخانه‌های مورد استفادهٔ pmproxy نیز فعال می‌سازد)

PCPIntro(1), pmcd(1), pmdbg(1), pmlogger(1), pmseries(1), PMAPI(3), PMWEBAPI(3), pmGetOptions(3), pcp.conf(5) و pcp.env(5).

PCP Performance Co-Pilot