PMDAOPENTELEMETRY(1) General Commands Manual PMDAOPENTELEMETRY(1)

pmdaopentelemetry - عامل PMDA برای OpenTelemetry

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

دستور pmdaopentelemetry یک عامل دامنه معیارهای کارایی (PMDA) است که به‌صورت پویا معیارهای PCP را از نقاط انتهایی (endpoints) پیکربندی‌شدهٔ OpenTelemetry که دسترسی مبتنی بر HTTP به معیارهای برنامه را فراهم می‌کنند، ایجاد می‌نماید.

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

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

pmstore opentelemetry.control.debug value

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

گزینهٔ -d می‌تواند برای بازنویسی شمارهٔ دامنهٔ پیش‌فرض معیارهای کارایی ( domain ) که به‌طور پیش‌فرض برابر با 164 است، استفاده شود. اکیداً توصیه می‌شود که این مقدار تغییر داده نشود. شمارهٔ domain باید برای هر PMDA روی یک میزبان منحصربه‌فرد باشد، و همین شمارهٔ domain باید برای PMDA مربوط به pmdaopentelemetry روی همهٔ میزبان‌ها استفاده شود. همچنین گزینهٔ -r را ببینید که امکان تغییر ریشهٔ فضای نام پویا را از مقدار پیش‌فرض opentelemetry فراهم می‌کند.

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

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

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

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

هر فایلی با پسوند .url که در دایرکتوری پیکربندی یا زیردایرکتوری‌های آن یافت شود، شامل یک URL کامل از نوع HTTP یا HTTPS است که pmdaopentelemetry می‌تواند از طریق آن به یک نقطهٔ پایانی (endpoint) مربوط به OpenTelemetry دسترسی پیدا کند. دسترسی به فایل‌های محلی نیز با یک URL متداول به صورت file:///somepath/somefile پشتیبانی می‌شود، که در این حالت somepath/somefile باید حاوی داده‌های سنجه با قالب‌بندی OpenTelemetry باشد.

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

HEADER: headername: value ... to end of line
مورد headername و مقدار آن را به سرایند‌های (headers) ارسالی در درخواست 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 مقایسه می‌شود. قاعدهٔ ساده این است که نخستین تطابق عبارت باقاعدهٔ فیلتر برای یک نام برگ سنجهٔ خاص، قاعده‌ای است که حاکم خواهد بود. اگر هیچ عبارت باقاعدهٔ فیلتری منطبق نشود (یا هیچ فیلتری وجود نداشته باشد)، سنجه به‌طور پیش‌فرض گنجانده می‌شود؛ یعنی در صورت عدم تعیین فیلتر، فیلتر پیش‌فرض عبارت است از: FILTER: INCLUDE METRIC .* این سازوکار با نسخه‌های قدیمی‌تر فایل پیکربندی که از فیلترها پشتیبانی نمی‌کردند، سازگار به عقب است. به‌طور معمول از چندین خط FILTER: استفاده می‌شود؛ مثلاً برای گنجاندن برخی سنجه‌ها و مستثنی کردن بقیه، از FILTER: EXCLUDE METRIC .* به‌عنوان آخرین فیلتر از میان چندین فیلتر که سنجه‌های مورد نظر را می‌گنجانند، استفاده کنید. برعکس، برای مستثنی کردن برخی سنجه‌ها اما گنجاندن همهٔ موارد دیگر، از FILTER: EXCLUDE METRIC regex. استفاده کنید. در این حالت، نیازی نیست (گرچه اشکالی هم ایجاد نمی‌کند) که فیلتر پایانی FILTER: INCLUDE METRIC .* مشخص شود، زیرا همان‌گونه که در بالا ذکر شد، هر سنجه‌ای که با هیچ عبارت باقاعده‌ای منطبق نشود، به‌طور پیش‌فرض گنجانده خواهد شد.

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

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

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

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

برای جزئیات کامل قالب‌های ارائه‌ی OpenTelemetry، ببینید: https://github.com/open-telemetry/opentelemetry-proto
blob/main/opentelemetry/proto/metrics/v1/metrics.proto.

فایل‌های پیکربندی اسکریپتی توسط PMDAی pmdaopentelemetry با همان بافت (context) و خط‌مشی SELinux مربوط به pmcd(1) محلی اجرا می‌شوند. برای اسکریپت‌های ساده، این موضوع معمولاً مشکلی ایجاد نمی‌کند. با این حال ممکن است برای اسکریپت‌هایی که فراخوانی‌های سیستمی یا کتابخانه‌ایِ محدودشده توسط بافت و خط‌مشی‌های حاکم SELinux را انجام می‌دهند، خطاهای AVC رخ دهد. در این موارد اعطای یک‌جانبه‌ی یک خط‌مشی اجرای نامحدود (unconfined) به 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) مراجعه کنید.

تمام متریک‌های حاصل از فایلی به نام JOB.* به عنوان متریک‌های PCP با پیشوند نام متریک opentelemetry.JOB صادر خواهند شد. بنابراین، نام JOB باید یک نام غیربرگ (non-leaf) معتبر برای نام‌های متریک PMNS در PCP باشد. اگر نام JOB دارای چندین بخش جداشده با نقطه باشد، نام‌های PMNS حاصل شامل آن بخش‌ها خواهند بود و باید دقت شود تا تعاریف دارای هم‌پوشانی نباشند؛ به عنوان مثال، متریک‌های بازگردانده‌شده توسط JOB.response ممکن است با متریک‌های بازگردانده‌شده توسط JOB.response.time هم‌پوشانی یا تداخل داشته باشند.

مدخل‌های فایل پیکربندی (نشانی‌های URL یا اسکریپت‌ها) که در زیردایرکتوری‌های دایرکتوری پیکربندی یافت می‌شوند نیز منجر به نام‌های سلسله‌مراتبی متریک خواهند شد. به عنوان مثال، یک فایل پیکربندی به نام $PCP_PMDAS_DIR/opentelemetry/config.d/mysource/latency/get.url منجر به ایجاد متریک‌هایی (از طریق واکشی آن نشانی URL مبدأ) در زیر opentelemetry.mysource.latency.get در فضای نام PCP می‌شود. اسکریپت‌های موجود در زیردایرکتوری‌های دایرکتوری پیکربندی نیز به طور مشابه به ایجاد نام‌های سلسله‌مراتبی متریک PCP منجر می‌شوند..SH "نام‌های متریک پویا (DYNAMIC METRIC NAMES)" همان‌طور که در بالا توضیح داده شد، می‌توان بدون نیاز به راه‌اندازی مجدد PMDA، تغییرات و موارد جدیدی را در فایل‌های دایرکتوری پیکربندی اعمال کرد. این تغییرات به‌طور خودکار شناسایی می‌شوند و نام‌های متریک PCP زیر opentelemetry در PMNS متناسب با آن به‌روزرسانی خواهند شد؛ بدین معنا که متریک‌های جدید به‌صورت پویا افزوده شده و/یا متریک‌های موجود حذف می‌شوند. علاوه بر این، pmdaopentelemetry از پروتکل PMCD_NAMES_CHANGE در pmFetch(3) که در نسخهٔ ۴.۰ PCP معرفی شد پشتیبانی می‌کند. به‌ویژه، اگر متریک‌های opentelemetry توسط pmlogger(1) در نسخهٔ ۴.۰ یا بالاتر PCP لاگ می‌شوند، متریک‌های جدیدی که در نتیجهٔ تغییرات در دایرکتوری پیکربندی PMDA پدیدار می‌شوند، به‌طور خودکار شروع به ثبت شدن می‌کنند؛ به شرط آنکه ریشهٔ فضای نام PMDA مربوط به opentelemetry برای ثبت در فایل پیکربندی pmlogger پیکربندی شده باشد. برای جزئیات بیشتر به pmlogger(1) مراجعه کنید. نمونه‌ای از چنین فایل پیکربندی pmlogger عبارت است از: 

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

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

فراداده باید در داده‌های json توسط نقطهٔ پایانی (URL یا اسکریپت) منبع opentelemetry ارائه شود. یک روش جایگزین، تعیین مستقیم این موارد در فایل پیکربندی URL است، که این مزیت را دارد که در صورت نادرست یا مفقود بودن فراداده، نیازی به تغییر منبع/نقطهٔ پایانی نیست. فرادادهٔ مشخص‌شده در فایل پیکربندی URL، بر هرگونه فرادادهٔ درون‌خطی (in-line) اولویت داشته و جایگزین آن می‌شود.

نحو فایل پیکربندی برای تعیین فراداده به صورت زیر است:
METADATA: regex type indom semantics units ... to 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 با units معادل 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 باشد؛ که در این صورت متریک هیچ دامنه نمونه‌ای نخواهد داشت (یعنی تکینه است)، حتی اگر برچسب‌هایی داشته باشد که در غیر این صورت برای نام‌گذاری نمونه استفاده می‌شدند..SH "معیارهای کنترلی (CONTROL METRICS)" PMDA معیارهای کنترلی ویژه‌ای را نگهداری می‌کند که در ادامه شرح داده شده‌اند. به‌جز opentelemetry.control.debug، هر یک از این معیارها برای هر منبع معیار پیکربندی‌شده، یک نمونه (instance) دارند. همهٔ این معیارها دارای مقادیر عدد صحیح با معناشناسی شمارنده (counter semantics) هستند، به‌جز opentelemetry.control.status که دارای یک مقدار رشته‌ای (string) است. توجه به این نکته حائز اهمیت است که واکشی هر یک از معیارهای opentelemetry.control تنها در صورتی شمارنده‌ها و مقادیر وضعیت را به‌روزرسانی می‌کند که URL متناظر واقعاً واکشی شود. اگر URL منبع واکشی نشود، مقادیر معیار کنترلی بازخوانی را تحریک نمی‌کنند و مقادیر کنترلی گزارش‌شده نشان‌دهنده آخرین واکشی از هر منبع متناظر خواهند بود.

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

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

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

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

ساختار داخلی pmdaopentelemetry و libpcp محدودیت‌های عددی خاصی را بر تعداد منابع (4095)، معیارهای درون هر منبع (1024)، و نمونه‌ها به ازای هر معیار (4194304) اِعمال می‌کنند..SH "نصب (INSTALLATION)" برای نصب PMDA مربوط به OpenTelemetry با استفاده از اسکریپت Install به‌عنوان کاربر ریشه (root) عمل کنید:

# cd $PCP_PMDAS_DIR/opentelemetry
# ./Install

برای حذف نصب، اقدامات زیر باید به‌عنوان کاربر ریشه انجام شوند:

# cd $PCP_PMDAS_DIR/opentelemetry
# ./Remove

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

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

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

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

PCPIntro(1), audit2allow(1), pmcd(1), pminfo(1), pmlogger(1), pmdaopenmetrics(1), pmstore(1), PMWEBAPI(3), pmFetch(3), pmLookupLabels(3), semodule(1)

PCP Performance Co-Pilot