PMDAOPENMETRICS(1) General Commands Manual PMDAOPENMETRICS(1)

pmdaopenmetrics - عامل دامنه معیارهای کارایی OpenMetrics

$PCP_PMDAS_DIR/openmetrics/pmdaopenmetrics [-D] [-n] [-c config] [-d domain] [-l logfile] [-R refresh_timeout] [-r root] [-t timeout] [-u user]

برنامهٔ pmdaopenmetrics یک «عامل دامنهٔ معیارهای کارایی» (PMDA) است که به‌طور پویا معیارهای PCP را از نقاط پایانی پیکربندی‌شدهٔ OpenMetrics (که دسترسی مبتنی بر HTTP به معیارهای برنامه‌ها را فراهم می‌کنند) ایجاد می‌کند. این PMDA در اصل پلی میان Prometheus و PCP ایجاد می‌کند و به PCP امکان می‌دهد داده‌های کارایی را به‌سادگی از بیش از ۶۵۰ نقطهٔ پایانی ثبت‌شده و بسیاری از نقاط پایانی اختصاصی دیگر برنامه‌ها دریافت کند.

دایرکتوری پیش‌فرض config، $PCP_PMDAS_DIR/openmetrics/config.d/ است؛ بخش ``CONFIGURATION SOURCES'' در زیر را ببینید. مهلت زمانی (timeout) پیش‌فرض واکشی URL برابر با 2 ثانیه است. کاربر پیش‌فرض (user)، اگر با گزینهٔ -u مشخص نشده باشد، کاربر فعلی است. اگر گزینهٔ -n داده شود، فهرست فایل‌های پیکربندی پیش از پردازش مرتب نخواهد شد. این فهرست به‌طور پیش‌فرض مرتب می‌شود، اما در صورت وجود تعداد زیادی از فایل‌های پیکربندی (URLها و/یا اسکریپت‌ها) ممکن است این کار پرهزینه باشد.

اگر گزینهٔ -D داده شود، پیام‌های عیب‌یابی بیشتری در فایل لاگ PMDA نوشته خواهد شد که به‌طور پیش‌فرض $PCP_LOG_DIR/pmcd/openmetrics.log است (همچنین گزینهٔ -l در زیر را ببینید). علاوه بر این، معیار openmetrics.control.debug همان پرچم اشکال‌زدایی را کنترل می‌کند و می‌تواند با دستور زیر تنظیم شود:

pmstore openmetrics.control.debug value

که در آن value می‌تواند برابر با 1 (برای فعال‌سازی پیام‌های لاگ پرجزئیات) یا 0 (برای غیرفعال‌سازی پیام‌های لاگ پرجزئیات) باشد. این قابلیت به‌ویژه برای بررسی هدرهای http ارسال‌شده به هر درخواست واکشی، تنظیمات فیلتر و سایر جزئیات پردازشی که هنگام فعال بودن پرچم اشکال‌زدایی در لاگ ثبت می‌شوند، مفید است.

از گزینهٔ -d می‌توان برای بازنویسی شمارهٔ domain (دامنهٔ) پیش‌فرض معیارهای کارایی استفاده کرد که مقدار پیش‌فرض آن 144 است. اکیداً توصیه می‌شود این مقدار را تغییر ندهید. شمارهٔ domain باید برای هر PMDA روی یک میزبان متفاوت باشد، و از همان شمارهٔ domain باید برای PMDAی pmdaopenmetrics روی تمام میزبان‌ها استفاده شود. همچنین گزینهٔ -r را ببینید که اجازه می‌دهد ریشهٔ فضای نام پویا از مقدار پیش‌فرض openmetrics تغییر داده شود.

از گزینهٔ -l می‌توان برای تعیین logfile به‌عنوان مقصد پیام‌های PMDA به جای مقدار پیش‌فرض، یعنی $PCP_LOG_DIR/pmcd/openmetrics.log، استفاده کرد. به‌عنوان یک حالت خاص، logfile می‌تواند برابر با "-" باشد تا پیام‌ها به جای آن به جریان stderr ارسال شوند، مانند -l-. این جریان معمولاً همان جریان stderr برای فرایند والد، یعنی pmcd(1) است که خود ممکن است stderr را تغییر مسیر داده باشد. این تغییر مسیر معمولاً در محیط‌های کانتینری یا هنگام استفاده از dbpmda(1) بیشترین کاربرد را دارد.

گزینهٔ -r امکان تغییر ریشهٔ فضای نام پویا از مقدار پیش‌فرض openmetrics به root را فراهم می‌کند. در ترکیب با سایر گزینه‌های خط فرمان، این قابلیت اجازه می‌دهد pmdaopenmetrics به‌عنوان یک PMDAی متمایز با فضای نام معیارها و دامنهٔ معیارهای جداگانه روی همان سیستم میزبان مستقر شود. توجه داشته باشید که تمام PMDAها به یک شماره دامنهٔ یکتا نیاز دارند، بنابراین گزینهٔ -d نیز باید مشخص شود. استفاده از گزینهٔ -r ممکن است مقادیر پیش‌فرض برخی دیگر از گزینه‌های خط فرمان را نیز تغییر دهد، برای مثال نام پیش‌فرض فایل لاگ و دایرکتوری پیکربندی پیش‌فرض.

گزینهٔ -R به کاربر اجازه می‌دهد timeout (مهلت زمانی) بین تازه‌سازی‌های کلاستر را بر حسب ثانیه پیکربندی کند. مقدار پیش‌فرض 10 ثانیه است..SH "منابع پیکربندی (CONFIGURATION SOURCES)" در حین اجرا، pmdaopenmetrics به‌صورت دوره‌ای و بازگشتی دایرکتوری $PCP_PMDAS_DIR/openmetrics/config.d (یا دایرکتوری مشخص‌شده با گزینهٔ -c) را به دنبال فایل‌های منبع URL (*.url) و اسکریپت‌ها یا باینری‌های اجرایی پویش می‌کند. هر فایلی که فاقد پسوند .url بوده یا قابل اجرا نباشد، نادیده گرفته می‌شود - این ویژگی اجازه می‌دهد تا فایل‌های مستنداتی مانند «README» و تعاریف توابع اسکریپت‌های غیرقابل اجرای «common» بدون اینکه به عنوان فایل‌های پیکربندی در نظر گرفته شوند، در این مسیر قرار داشته باشند.

نیازی نیست که یک سرور راه دور همواره بالا یا در حال اجرا باشد - این PMDA با URLهای راه دوری که ممکن است در طول زمان فعال و غیرفعال شوند مدارا می‌کند. این PMDA داده‌ها و متاداده‌ها را زمانی که در دسترس باشند مخابره کرده، و در صورت از کار افتادن آن‌ها، خطا بازمی‌گرداند. شناسه‌های متریک PCP، و شناسه‌های داخلی و خارجی دامنهٔ نمونه (instance domain) ذخیره شده و زمانی که منابع متریک مشخصی در دسترس قرار گیرند و/یا زمانی که PMDA بازراه‌اندازی شود، بازیابی خواهند شد. علاوه بر این، PMDA زمان‌های تغییر دایرکتوری را بررسی کرده و فایل‌های پیکربندی جدید یا تغییریافته را به‌صورت پویا مجدداً پویش می‌کند. هنگام افزودن، حذف یا تغییر فایل‌های پیکربندی، بازراه‌اندازی PMDA لازم نیست.

هر فایلی با پسوند .url که در دایرکتوری پیکربندی یا زیردایرکتوری‌های آن یافت شود، شامل یک URL کامل HTTP یا HTTPS است که pmdaopenmetrics می‌تواند از طریق آن به یک نقطهٔ پایانی OpenMetrics دسترسی داشته باشد. دسترسی به فایل محلی نیز با یک URL متعارف file:///somepath/somefile پشتیبانی می‌شود، که در این حالت somepath/somefile باید حاوی داده‌های متریک با قالب‌بندی openmetrics باشد.

خط اول یک فایل پیکربندی .url باید همان‌گونه که در بالا شرح داده شد، URL باشد. خطوط بعدی، در صورت وجود، با یک کلمهٔ کلیدی پیشوندگذاری می‌شوند که می‌توان از آن برای تغییر درخواست http GET استفاده کرد. یک کلمهٔ کلیدی باید به ':' (دو نقطه) ختم شود و متن آن تا انتهای خط ادامه می‌یابد. خطوط توضیح که با # شروع می‌شوند و خطوط خالی نادیده گرفته خواهند شد. تنها کلمات کلیدی که در حال حاضر پشتیبانی می‌شوند HEADER: و FILTER: هستند.

HEADER: headername: value ... to end of line
headername و مقدار آن را به هدرهای ارسال‌شده در درخواست http GET برای URL پیکربندی‌شده اضافه می‌کند. یک فایل پیکربندی نمونه که ۳ هدر پرکاربرد و یک توکن احراز هویت را ارائه می‌دهد می‌تواند به این شکل باشد:


http://somehost/path/endpoint.html
# this is a comment
HEADER: Accept: text/html
HEADER: Keep-Alive: 300
HEADER: Connection: keep-alive
HEADER: Authorization: token ABCDEF1234567890

همان‌گونه که در بالا اشاره شد، مقادیر هدر تا انتهای خط ادامه دارند. آن‌ها می‌توانند حاوی هر نویسهٔ معتبری از جمله دو نقطه باشند. فاصله‌های متوالی به یک تک‌فاصله تبدیل شده و فاصله‌های ابتدا و انتهای خط حذف (trim) می‌گردند. یک کاربرد معمول هدرها، پیکربندی یک proxy agent و پارامترهای گوناگونی است که ممکن است به آن‌ها نیاز داشته باشد..SH "فیلتر کردن سنجه‌ها (METRIC FILTERING)" فیلتر کردن سنجه یکی از قابلیت‌های فایل پیکربندی است که امکان گنجاندن یا مستثنی کردن سنجه‌های دریافت شده، یعنی فیلتر کردن آن‌ها را فراهم می‌کند. این قابلیت مفید است زیرا بیشتر پایانه‌ها چندین سنجه را بازمی‌گردانند، و معمولاً تنها برخی از آن‌ها برای اهداف نظارت کاربرد دارند. نحو دستور به صورت زیر است:
FILTER: INCLUDE METRIC regex
یا
FILTER: EXCLUDE METRIC regex
نام‌های پویای سنجه که با regex مطابقت دارند، همان‌گونه که مشخص شده در فضای نام گنجانده یا مستثنی خواهند شد. توجه داشته باشید که تنها مؤلفهٔ برگ PMNS از نام سنجه (همان‌طور که از منبع URL دریافت شده است) با الگوی regex مقایسه می‌شود. قاعدهٔ ساده این است که اولین تطابق regex فیلتر برای یک نام برگ سنجهٔ خاص، قاعده‌ای است که حاکم خواهد بود. اگر هیچ regex فیلتری تطابق نداشته باشد (یا اصلاً فیلتری وجود نداشته باشد)، سنجه به صورت پیش‌فرض گنجانده می‌شود؛ یعنی فیلتر پیش‌فرض در صورت مشخص نشدن هیچ فیلتری عبارت است از: FILTER: INCLUDE METRIC .* این سازوکار با نسخه‌های قدیمی‌تر فایل پیکربندی که از فیلترها پشتیبانی نمی‌کردند، سازگار به عقب است. معمولاً چندین خط FILTER: استفاده می‌شود؛ برای مثال، جهت گنجاندن برخی سنجه‌ها و مستثنی کردن تمام سنجه‌های دیگر، از FILTER: EXCLUDE METRIC .* به عنوان آخرین فیلتر از میان چندین فیلتری که سنجه‌های مورد نظر را می‌گنجانند استفاده کنید. برعکس، برای مستثنی کردن برخی سنجه‌ها اما گنجاندن سایر آن‌ها، از FILTER: EXCLUDE METRIC regex استفاده کنید. در این حالت نیازی نیست (اگرچه مشکلی هم ایجاد نمی‌کند) که فیلتر نهاییِ FILTER: INCLUDE METRIC .* مشخص شود، چرا که همان‌طور که در بالا گفته شد، هر سنجه‌ای که با هیچ regex فیلتری مطابقت نداشته باشد، به صورت پیش‌فرض گنجانده خواهد شد.

فیلتر کردن برچسب‌ها از نحو و معناشناسیِ مشابه با FILTER: در فیلتر کردن سنجه‌ها استفاده می‌کند. FILTER: EXCLUDE LABEL regex تمام برچسب‌هایی را که نام برچسب آن‌ها با regex تطابق دارد، از تمام سنجه‌های تعریف‌شده توسط فایل پیکربندی حذف خواهد کرد. همان قواعد فیلترهای سنجه برای فیلترهای برچسب نیز برقرار است – یک قاعدهٔ ضمنی: FILTER: INCLUDE LABEL .* برای تمام برچسب‌هایی که با هیچ قاعدهٔ فیلتر برچسب قبلی مطابقت ندارند اعمال می‌شود. FILTER: OPTIONAL LABEL regex مشخص می‌کند که نام‌های برچسب منطبق باید در مجموعه‌برچسب‌های بازگردانده شدهٔ سنجه گنجانده شوند (یعنی شامل شوند)، اما نباید به عنوان بخشی از نام‌های نمونهٔ خارجی استفاده گردند. تمام برچسب‌های گنجانده‌شده‌ای که اختیاری نیستند (یعنی برچسب‌های intrinsic) به هم متصل شده و برای نام‌گذاری نمونهٔ خارجی به کار می‌روند. علاوه بر این، برچسب‌های غیرذاتی (یعنی برچسب‌هایی که به عنوان OPTIONAL نشانه‌گذاری شده‌اند) پرچم PM_LABEL_OPTIONAL را در مجموعه‌برچسب‌های بازگردانده شده توسط فراخوانی‌های بازگشتی notes تنظیم خواهند داشت. این پرچم بر نحوهٔ استفاده از برچسب‌ها در برخی کلاینت‌ها تأثیر می‌گذارد. برای جزئیات بیشتر، به pmLookupLabels(3) و صفحات راهنمای مرتبط مراجعه کنید. توجه داشته باشید که نام‌های نمونهٔ خارجی با شناسهٔ عددی داخلی منحصربه‌فرد نمونه شروع شده و به دنبال آن یک فاصله قرار می‌گیرد، بنابراین نام‌های نمونهٔ خارجی همیشه یکتا هستند.

در فیلتر کردن برچسب‌ها احتیاط لازم است، زیرا به طور پیش‌فرض تمام برچسب‌ها برای ساخت نام نمونهٔ PCP استفاده می‌شوند. با مستثنی کردن برخی برچسب‌ها (یا تغییر وضعیت آن‌ها به اختیاری)، نام‌های نمونه تغییر خواهند کرد. علاوه بر این، مستثنی کردن تمام برچسب‌ها برای یک سنجهٔ خاص باعث می‌شود آن سنجه به حالت مفرد (singular) تغییر یابد، یعنی هیچ دامنهٔ نمونه‌ای (instance domain) نداشته باشد. با مستثنی کردن برخی برچسب‌ها، نمونه‌های مختلف بازگردانده شده توسط URL یا مدخل پیکربندی اسکریپت‌شده برای یک سنجهٔ یکسان ممکن است به موارد تکراری تبدیل شوند. هنگامی که چنین موارد تکراری رخ می‌دهد، آخرین نمونهٔ تکراری بازگردانده شده توسط URL پایانی یا اسکریپت بر نمونه‌های قبلی اولویت دارد. به این دلایل، توصیه می‌شود قواعد فیلتر کردن برچسب هنگام تعریف اولیهٔ فایل پیکربندی تعیین شوند و پس از آن تغییر نکنند. اگر تغییری در فیلتر کردن برچسب لازم باشد، فایل پیکربندی باید تغییر نام داده شود، که عملاً یک سنجهٔ جدید (یا مجموعه‌ای از سنجه‌های همتا به همان صورتی که توسط URL یا اسکریپت بازگردانده می‌شوند) را با نام‌گذاری نمونهٔ جدید (یا تغییریافته) تعریف می‌کند.

کلیدواژه‌های ناشناخته در فایل‌های پیکربندی در فایل لاگ PMDA گزارش می‌شوند، اما در غیر این صورت نادیده گرفته خواهند شد..SH "منابع اسکریپتی (SCRIPTED SOURCES)" اسکریپت‌های اجرایی موجود در دایرکتوری $PCP_PMDAS_DIR/openmetrics/config.d یا زیردایرکتوری‌های آن اجرا خواهند شد و جریان stdout شامل داده‌های سنجه با قالب‌بندی openmetrics به گونه‌ای تجزیه می‌شود که گویی از یک URL یا فایل آمده است. جریان stderr یک اسکریپت به فایل لاگ PMDA ارسال می‌شود که به طور پیش‌فرض در مسیر $(PCP_LOG_DIR)/pmcd/openmetrics.log یافت می‌شود.

توجه داشته باشید که منابع اسکریپتی از فیلتر کردن برچسب یا سنجه (همان‌طور که در بالا برای منابع URL توضیح داده شد) پشتیبانی نمی‌کنند - آن‌ها می‌توانند به سادگی فیلتر کردن مورد نظر را در خود اسکریپت با استفاده از sed(1)، awk(1) یا هر ابزار دلخواه دیگری انجام دهند.

در ادامه یک مثال ساده از یک ورودی پیکربندی اسکریپتی آمده است: 

#! /bin/sh
awk '{
    print("# HELP loadavg local load average")
    print("# TYPE loadavg gauge")
    printf("loadavg {interval=\"1-minute\"} %.2f\n", $1)
    printf("loadavg {interval=\"5-minute\"} %.2f\n", $2)
    printf("loadavg {interval=\"15-minute\"} %.2f\n", $3)
}' /proc/loadavg

این اسکریپت در زمان اجرا داده‌های سنجه با قالب‌بندی OpenMetrics زیر را تولید می‌کند: 

# HELP loadavg local load average
# TYPE loadavg gauge
loadavg {interval="1-minute"} 0.12
loadavg {interval="5-minute"} 0.27
loadavg {interval="15-minute"} 0.54

اگر اسکریپت بالا در فایلی با نام $PCP_PMDAS_DIR/openmetrics/config.d/local/system.sh ذخیره و اجرایی شود، منجر به ایجاد یک سنجه جدید PCP به نام openmetrics.local.system.loadavg خواهد شد که دارای سه نمونه برای مقادیر فعلی میانگین بار خواهد بود: 1-minute، 5-minute و 15-minute.

ورودی‌های پیکربندی اسکریپتی ممکن است بیش از یک نام سنجه برگ PCP تولید کنند. به عنوان مثال، اسکریپت «system.sh» بالا می‌تواند با خواندن /proc/stat در سیستم محلی، سنجه‌های دیگری مانند آمار CPU را نیز صادر کند. چنین سنجه‌های اضافی به عنوان سنجه‌های همتا در همان زیردرخت سنجه PCP ظاهر خواهند شد. در مورد شمارنده‌های CPU، تعریف نوع سنجه باید counter باشد، نه gauge. برای جزئیات کامل در مورد قالب‌های نمایش openmetrics، ببینید: https://github.com/OpenObservability/OpenMetrics/blob/master/specification/OpenMetrics.md.

فایل‌های پیکربندی اسکریپتی توسط PMDA با نام pmdaopenmetrics با همان بافتار و خط‌مشی SELinux مربوط به pmcd(1) محلی اجرا می‌شوند. برای اسکریپت‌های ساده، مانند مثال میانگین بار که در بالا توضیح داده شد، این موضوع معمولاً مشکلی ایجاد نمی‌کند. با این حال، ممکن است برای اسکریپت‌هایی که فراخوانی‌های کتابخانه‌ای یا سیستمیِ محدودشده توسط بافتار و خط‌مشی‌های حاکم SELinux را انجام می‌دهند، خطاهای AVC رخ دهد. در این موارد امکان‌پذیر نیست که به طور یک‌جانبه به pmcd یا PMDAهای آن خط‌مشی اجرای نامحدود اعطا شود. در این موارد خاصِ سیستم، ایجاد یک ماژول خط‌مشی محلی SELinux ضروری خواهد بود. این کار را می‌توان با گرفتن رکورد(های) AVC از لاگ بازرسی محلی، تولید یک ماژول خط‌مشی محلی با استفاده از audit2allow و سپس بارگذاری ماژول جدید با استفاده از semodule انجام داد؛ به عنوان مثال به صورت زیر: 

    $ sudo grep '^type=AVC.*pcp' /var/log/audit/audit.log \
    | audit2allow -M mypolicy
    $ sudo semodule -i mypolicy.pp

اگر لازم است این خط‌مشی‌های محلی در میان راه‌اندازی‌های مجدد سیستم پایدار بمانند، می‌توان اسکریپت کوتاهی مشابه مثال بالا را به فایل RC محلی مربوط به pmcd (معمولاً /etc/pcp/pmcd/rc.local) اضافه کرد. برای جزئیات بیشتر، ببینید: audit2allow(1) و semodule(1)..SHنام‌گذاری متریک‌ها (METRIC NAMING) تمام متریک‌های حاصل از فایلی با نام JOB.* به‌عنوان متریک‌های PCP با پیشوند نام متریک openmetrics.JOB صادر (export) خواهند شد. بنابراین، نام JOB باید یک نام غیربرگ (non-leaf) معتبر برای نام‌های متریک PMNS در PCP باشد. اگر نام JOB دارای چندین بخش جداشده با نقطه باشد، نام‌های PMNS حاصل نیز آن بخش‌ها را در بر خواهند گرفت و باید دقت شود تا اطمینان حاصل گردد هیچ تداخل تعریفی وجود ندارد؛ به عنوان مثال متریک‌های بازگردانده شده توسط JOB.response ممکن است با متریک‌های بازگردانده شده توسط JOB.response.time هم‌پوشانی یا تداخل داشته باشند.

ورودی‌های فایل پیکربندی (نشانی‌های URL یا اسکریپت‌ها) که در زیرپوشه‌های دایرکتوری پیکربندی یافت می‌شوند نیز منجر به نام‌های سلسله‌مراتبی متریک خواهند شد. برای مثال، یک فایل پیکربندی با نام $PCP_PMDAS_DIR/openmetrics/config.d/mysource/latency/get.url منجر به ایجاد متریک‌هایی (از طریق واکشی آن URL مبدا) در زیر openmetrics.mysource.latency.get در فضای نام PCP خواهد شد. اسکریپت‌های موجود در زیرپوشه‌های دایرکتوری پیکربندی نیز به طور مشابه منجر به نام‌های سلسله‌مراتبی متریک در PCP می‌شوند.

همان‌طور که در بالا شرح داده شد، می‌توان بدون نیاز به راه‌اندازی مجدد PMDA، تغییرات و موارد جدیدی را در فایل‌های درون دایرکتوری پیکربندی ایجاد کرد. این تغییرات به طور خودکار شناسایی می‌شوند و نام‌های متریک PCP در زیر openmetrics در PMNS بر همین اساس به‌روزرسانی خواهند شد؛ یعنی متریک‌های جدید به‌صورت پویا افزوده شده و/یا متریک‌های موجود حذف می‌گردند. علاوه بر این، pmdaopenmetrics از پروتکل PMCD_NAMES_CHANGE در pmFetch(3) که در نگارش 4.0 از PCP معرفی شد تبعیت می‌کند. به‌ویژه، اگر متریک‌های openmetrics توسط pmlogger(1) نگارش 4.0 یا بالاتر ثبت (log) شوند، متریک‌های جدیدی که در نتیجهٔ تغییرات در دایرکتوری پیکربندی PMDA ظاهر می‌شوند، به‌طور خودکار شروع به ثبت شدن خواهند کرد؛ به شرطی که ریشهٔ فضای نام PMDA در openmetrics برای ثبت در فایل پیکربندی pmlogger پیکربندی شده باشد. برای جزئیات بیشتر به pmlogger(1) مراجعه کنید. نمونه‌ای از چنین فایل پیکربندی pmlogger به این صورت است: 

log mandatory on 2 second {
	# log all metrics below the root of the openmetrics namespace
	openmetrics
}

داده‌های متریک بازگردانده شده توسط نشانی URL یا فایل‌های پیکربندی اسکریپتی ممکن است حاوی متاداده‌ای باشند که می‌تواند توسط PMDA در openmetrics برای تعیین معانی (semantics)، نوع داده، مقیاس‌بندی و واحدهای متریک‌های پویای ایجادشده به کار رود. این متاداده در داده‌های متریک دریافت‌شده با پیشوند # PCP5 یا # PCP مشخص می‌شود. برای کسب اطلاعات بیشتر دربارهٔ متادادهٔ PCP، به pmLookupDesc(3) و pmParseUnitsStr(3) و مثال‌های موجود در فایل‌های پیکربندی ارائه‌شده مراجعه کنید.

متادادهٔ درون‌خطی «PCP5» باید توسط نقطهٔ پایانی منبع متریک (URL یا اسکریپت) ارائه شود. راهکار جایگزین، تعیین مستقیم این موارد در فایل پیکربندی URL است که این مزیت را دارد که در صورت نادرست بودن یا نبود متاداده، نیازی به تغییر منبع/نقطه پایانی نخواهد بود. متادادهٔ مشخص‌شده در فایل پیکربندی URL بر هرگونه متادادهٔ درون‌خطی اولویت دارد.

نحو (syntax) فایل پیکربندی برای مشخص کردن متاداده به صورت زیر است:
METADATA: regex type indom semantics units ... تا EOL
که در آن:
عبارت METADATA: عینا درج می‌شود،
regex یک عبارت منظم گسترش‌یافته (extended regular expression) برای تطبیق با یک یا چند نام متریک بازگردانده شده توسط URL است،
type یکی از انواع عددی PCP است (32، u32، 64، u64، float یا double)،
indom یک نام دلخواه برای دامنهٔ نمونه (instance domain)، یا PM_INDOM_NULL است،
semantics یکی از مقادیر counter، instant یا discrete است و
units یا none است یا رشته‌ای تا پایان خط که توسط pmParseUnitsStr(3) قابل تجزیه باشد، یعنی واحدها، ابعاد و مقیاس مورد استفاده برای متریک‌های منطبق.

یک نمونه فایل پیکربندی که متریک‌ها را از نقطه پایانی /metrics در Grafana روی localhost دریافت می‌کند، تمامی متریک‌های بازگردانده‌شده توسط آن URL را به‌جز grafana_api_response_status_total فیلتر می‌کند و سپس نوع (type) متریک را یک عدد صحیح ۳۲ بیتی بدون علامت با یک دامنهٔ نمونهٔ غیرتکین به نام response و معانی counter همراه با واحدهای count تعیین می‌نماید:

http://localhost:3000/metrics
FILTER: INCLUDE METRIC grafana_api_response_status_total
FILTER: EXCLUDE METRIC .*
METADATA: grafana_api_response_status_total u32 response counter count

توجه داشته باشید که نام موجود در فیلد indom در حال حاضر نادیده گرفته می‌شود مگر اینکه PM_INDOM_NULL باشد؛ که در این صورت متریک فاقد دامنه نمونه خواهد بود (یعنی تکین یا singular است)، حتی اگر دارای برچسب‌هایی باشد که در غیر این صورت برای نام‌گذاری نمونه استفاده می‌شدند..SH "معیارهای کنترلی (CONTROL METRICS)" عامل PMDA معیارهای کنترلی ویژه‌ای را که در ادامه شرح داده شده‌اند، نگهداری می‌کند. به‌جز openmetrics.control.debug، هر یک از این معیارها به ازای هر منبع معیارِ پیکربندی‌شده، دارای یک نمونه است. تمامی این معیارها مقادیر عدد صحیح با معناشناسی شمارنده دارند، به‌جز openmetrics.control.status که دارای یک مقدار رشته‌ای است. توجه به این نکته حائز اهمیت است که واکشی هر یک از معیارهای openmetrics.control تنها در صورتی شمارنده‌ها و مقادیر وضعیت را به‌روزرسانی می‌کند که URL متناظر واقعاً واکشی شود. اگر URL منبع واکشی نشود، مقادیر معیار کنترلی بازخوانی مجدد را تحریک نمی‌کنند و مقادیر کنترلی گزارش‌شده نشان‌دهنده جدیدترین واکشی هر منبع متناظر خواهند بود.

دامنه نمونه‌ها برای معیارهای openmetrics.control با کشف منابع جدید، به‌طور پویا تنظیم می‌شود. اگر هیچ منبعی پیکربندی نشده باشد، نام‌های معیارها همچنان تعریف‌شده هستند اما دامنه نمونه خالی خواهد بود و واکشی هیچ مقداری را برنمی‌گرداند.

رشته‌ای که نشان‌دهنده وضعیت آخرین واکشی منبع متناظر است. این مقدار عموماً برای کد پاسخ http معادل 200 برابر با success خواهد بود. این معیار می‌تواند برای پایش دسترسی‌پذیری سرویس استفاده شود - مشروط بر آنکه، همان‌طور که در بالا ذکر شد، URL منبع متناظر نیز واکشی شود.
این معیار شبیه به openmetrics.control.status است، با این تفاوت که کد پاسخ عددی آخرین واکشی را نشان می‌دهد. مقدار 200 معمولاً نشان‌دهنده موفقیت و هر مقدار دیگری نشان‌دهنده شکست است. از این معیار نیز می‌توان برای پایش دسترسی‌پذیری سرویس استفاده کرد، با همان ملاحظاتی که برای openmetrics.control.status ذکر شد.
تعداد کل دفعاتی که هر منبع معیار پیکربندی‌شده از زمان شروع PMDA واکشی شده است (اگر یک URL باشد) یا اجرا شده است (اگر یک اسکریپت باشد). این معیار دارای معناشناسی شمارنده است و معمولاً توسط ابزارهای کلاینت به نرخ بر ثانیه تبدیل می‌شود.
کل زمان صرف‌شده بر حسب میلی‌ثانیه برای هر منبع معیار پیکربندی‌شده جهت بازگرداندن یک سند، بدون احتساب زمان تجزیه سند. این معیار دارای معناشناسی شمارنده است و معمولاً توسط ابزارهای کلاینت به نرخ تبدیل می‌شود، اما در حالت خام نیز به‌عنوان زمان انباشته‌شده از زمان شروع PMDA مفید است.
کل زمان صرف‌شده بر حسب میلی‌ثانیه برای هر منبع معیار پیکربندی‌شده جهت تجزیه هر سند، بدون احتساب زمان واکشی سند. این معیار دارای معناشناسی شمارنده است و معمولاً توسط ابزارهای کلاینت به نرخ تبدیل می‌شود، اما در حالت خام نیز به‌عنوان زمان تجزیه انباشته‌شده از زمان شروع PMDA مفید است.

هنگامی که به نرخ تبدیل شود، معیار calls میانگین نرخ واکشی هر منبع را در طول بازه نمونه‌برداری (اختلاف زمانی بین نمونه‌ها) نشان می‌دهد. شمارنده‌های fetch_time و parse_time، هنگامی که به نرخ تبدیل شوند، به ترتیب نشان‌دهنده میانگین تأخیر واکشی و تجزیه در طول بازه نمونه‌برداری هستند.

معیار openmetrics.control.debug دارای یک مقدار تکی است که مقدار پیش‌فرض آن 0 می‌باشد. اگر مقداری غیر صفر با استفاده از pmstore(1) در این معیار ذخیره شود، پیام‌های اشکال‌زدایی بیشتری در فایل گزارش PMDA نوشته خواهد شد.

بخش‌های درونی pmdaopenmetrics و libpcp محدودیت‌های عددی خاصی را برای تعداد منابع (4095)، معیارهای درون هر منبع (1024)، و نمونه‌ها برای هر معیار (4194304) اعمال می‌کنند.

عامل PMDA مربوط به OpenMetrics را با استفاده از اسکریپت Install به‌عنوان مدیر سیستم (root) نصب کنید:

# cd $PCP_PMDAS_DIR/openmetrics
# ./Install

برای حذف، باید مراحل زیر به‌عنوان مدیر سیستم (root) انجام شود:

# cd $PCP_PMDAS_DIR/openmetrics
# ./Remove

pmdaopenmetrics توسط pmcd(1) راه‌اندازی می‌شود و هرگز نباید به‌طور مستقیم اجرا شود. اسکریپت‌های Install و Remove هنگام نصب یا حذف عامل، به pmcd اطلاع می‌دهند.

هنگامی که اسکریپت‌ها و فایل‌های .url در پوشه پیکربندی اضافه، حذف یا تغییر داده می‌شوند، معمولاً نیازی به راه‌اندازی مجدد PMDA نیست - تغییرات در درخواست‌های بعدی به PMDA شناسایی و مدیریت خواهند شد..SH "فایل‌ها (FILES)"

$PCP_PMDAS_DIR/openmetrics/Install
اسکریپت نصب برای عامل pmdaopenmetrics
$PCP_PMDAS_DIR/openmetrics/Remove
اسکریپت حذف نصب برای عامل pmdaopenmetrics
$PCP_PMDAS_DIR/openmetrics/config.d/
شامل نشانی‌های اینترنتی (URLها) و اسکریپت‌هایی است که توسط عامل pmdaopenmetrics به‌عنوان منابع داده‌های سنجه openmetrics استفاده می‌شوند.
$PCP_LOG_DIR/pmcd/openmetrics.log
فایل لاگ پیش‌فرض برای پیام‌های خطای pmdaopenmetrics
$PCP_VAR_DIR/config/144.*
فایل‌های حاوی جدول‌های داخلی برای ماندگاری شماره‌های شناسه سنجه و نمونه (دامنه ۱۴۴).

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

PCPIntro(1), audit2allow(1), pmcd(1), pminfo(1), pmlogger(1), pmstore(1), PMWEBAPI(3), pmFetch(3), pmLookupLabels(3), semodule(1) و https://prometheus.io/docs/instrumenting/exposition_formats.

PCP Performance Co-Pilot