MMV(5) File Formats Manual MMV(5)

mmv - مقادیر نگاشت‌شده در حافظه برای Performance Co-Pilot

$PCP_TMP_DIR/mmv/<file>

فایل‌های موجود در $PCP_TMP_DIR/mmv یا توسط توابع mmv_stats_init(3) و mmv_stats2_init(3) از کتابخانه libpcp_mmv تولید می‌شوند، یا توسط یک ماژول زبان بومی مانند Parfait (در Java)، Speed (در Golang) یا Hornet (در Rust).

ممکن است چندین فایل در این دایرکتوری وجود داشته باشد که هر فایل نمایانگر یک منبع واحد از معیارهای کارایی (Performance Metrics) است. این معیارها توسط pmdammv(1) جمع‌آوری می‌شوند که آن‌ها را به سایر بخش‌های زیرساخت Performance Co-Pilot صادر می‌کند.

هر فایل با سرایند (Header) زیر آغاز می‌شود:

Offset Length Name
0 4 tag == "MMV\0"
4 4 Version (1 or 2)
8 8 Generation 1
16 8 Generation 2
24 4 Number of TOC entries
28 4 Flags
32 4 Process identifier (PID)
36 4 Cluster identifier

شماره نسخه مشخص می‌کند که کدام قالب چیدمان نگاشت مورد استفاده قرار گرفته است. دو نسخه وجود دارد که هر دو بسیار شبیه به یکدیگرند، همان‌طور که در ادامه توضیح داده شده است. تنها هدف قالب نسخه ۲ MMV امکان استفاده از نام‌های طولانی‌تر برای معیارها و نمونه‌ها است. اگر نام‌های طولانی‌تر از MMV_NAMEMAX استفاده نمی‌شوند، بهتر است از قالب نسخه ۱ MMV استفاده شود زیرا به نسخه‌های قدیمی‌تر PCP نیز امکان مصرف داده‌ها را می‌دهد. پشتیبانی از قالب نسخه ۲ در انتشار pcp-3.11.4 اضافه شد.

شماره‌های نسل (Generation numbers) برچسب‌های زمانی هنگام ایجاد فایل هستند و برای اینکه فایل توسط MMV PMDA پردازش شود باید با یکدیگر مطابقت داشته باشند.

فلگ‌ها می‌توانند شیوه‌های رفتار مورد نظر کلاینت از MMV PMDA را مشخص کنند - برای مثال فلگ MMV_FLAG_PROCESS مشخص می‌کند که تنها در صورتی مقادیر صادر شوند که فرآیند مشخص‌شده توسط PID در حال حاضر در حال اجرا باشد.

در نهایت، در صورت تنظیم شدن، شناسه کلاستر راهنمایی برای MMV PMDA است تا مشخص کند هنگام تشکیل شناسه‌های تک‌تک معیارها، چه کلاستری باید برای این برنامه استفاده شود. یک شناسه معیار کارایی (به PMDA(3) مراجعه کنید) از شماره دامنه PMDA، شماره کلاستر و شماره‌های آیتم منفرد توصیف‌شده در بخش Metrics تشکیل می‌شود.

پس از سرایند حداقل ۲ بخش TOC (جدول محتویات) می‌آید: یک بخش برای معیارها (Metrics) و دیگری برای مقادیر (Values). بخش TOC ساختار زیر را دارد:

Offset Length Value
0 4 Section Type (see mmv_stats.h)
4 4 Number of entries in the section
8 8 Section's offset from the start of the file

انواع بخش‌ها عبارتند از:

1: Indoms (تعاریف دامنه نمونه یا Instance Domain Definitions)
2: Instances (نمونه‌ها)
3: Metrics (تعاریف معیارها)
4: Values (مقادیر)
5: String (رشته)
6: Labels (برچسب‌ها)

تنها بخش‌های الزامی، Metrics و Values هستند. بخش‌های Indoms و Instances در هر دو نسخه تنها در صورتی وجود دارند که معیارهایی با چندین نمونه موجود باشند. بخش‌های String تنها در صورتی ظاهر می‌شوند که معیارهایی با مقادیر رشته‌ای وجود داشته باشند، هنگامی که Metrics یا Indoms با متن راهنما تعریف شده باشند، یا در قالب نسخه ۲ MMV که در آن نام معیارها و نام نمونه‌ها در بخش‌های رشته‌ای ذخیره می‌شوند (که فضای به مراتب بیشتری نسبت به قالب نسخه ۱ MMV برای این نام‌ها فراهم می‌کند). بخش‌های Label تنها در صورتی ظاهر می‌شوند که معیارهایی با برچسب‌ها (جفت‌های نام/مقدار) نشانه‌گذاری شده باشند. برچسب‌ها در قالب نسخه ۳ MMV پشتیبانی می‌شوند.

مدخل‌های موجود در بخش‌های Indoms ساختار زیر را دارند:

Offset Length Value
0 4 Unique serial number for this domain
4 4 Number of entries in the domain
8 8 Offset to first Instance or Instance2
16 8 Short help text offset
24 8 Long help text offset

مدخل‌های موجود در بخش Instances (نسخه ۱) ساختار زیر را دارند:

Offset Length Value
0 8 Offset into the indom section
8 4 Unused padding (zero filled)
12 4 Internal instance identifier
16 64 External instance identifier

مدخل‌های موجود در بخش Instances (نسخه ۲) ساختار زیر را دارند:

Offset Length Value
0 8 Offset into the indom section
8 4 Unused padding (zero filled)
12 4 Internal instance identifier
16 8 External instance identifier string offset

مدخل‌های موجود در بخش Metrics (نسخه ۱) ساختار زیر را دارند:

Offset Length Value
0 64 Metric Name
64 4 Metric Item (see PMDA(3))
68 4 Metric Type (see mmv_stats.h)
72 4 Semantics (see PMAPI(3))
76 4 Dimensions (see PMAPI(3))
80 4 Instance Domain ID
84 4 Unused padding (zero filled)
88 8 Short help text offset
96 8 Long help text offset

مدخل‌های موجود در بخش Metrics (نسخه ۲) ساختار زیر را دارند:

Offset Length Value
0 8 Metric Name string offset
8 4 Metric Item (see PMDA(3))
12 4 Metric Type (see mmv_stats.h)
16 4 Semantics (see PMAPI(3))
20 4 Dimensions (see PMAPI(3))
24 4 Instance Domain ID
28 4 Unused padding (zero filled)
32 8 Short help text offset
40 8 Long help text offset

مدخل‌های موجود در بخش Values ساختار زیر را دارند:

Offset Length Value
0 8 pmAtomValue (see PMAPI(3))
8 8 Extra space for STRING and ELAPSED
16 8 Offset into the Metrics section
24 8 Offset into the Instances section

هر مدخل در بخش رشته‌ها یک آرایه نویسه‌ای ۲۵۶ بایتی است که حاوی یک رشته کاراکتری پایان‌یافته با NULL است. بنابراین هر رشته حداکثر ۲۵۶ بایت طول دارد که شامل کاراکتر پایانی NULL نیز می‌شود.

مدخل‌های موجود در بخش Labels (نسخه ۳) ساختار زیر را دارند:

Offset Length Value
0 4 Flags - PM_LABEL_ CLUSTER, ITEM, INDOM, INSTANCES and OPTIONAL
4 4 Identifier for given type (indom, cluster or item)
8 4 Internal Instance or PM_IN_NULL
12 244 Payload (Name and Value JSONB String)

هر مدخل در بار داده (Payload) یک آرایه نویسه‌ای حداکثر ۲۴۴ بایتی است که حاوی یک جفت name:value پایان‌یافته با NULL در قالب JSON است. نویسه‌های فاصله خالی بی‌اهمیت (Insignificant whitespace) نباید وجود داشته باشند. نام برچسب‌ها تنها از نویسه‌های الفبایی-عددی یا زیرخط (Underscore) تشکیل می‌شوند و باید با یک نویسه الفبایی آغاز گردند. نویسه‌های بزرگ و کوچک متمایز از یکدیگر در نظر گرفته می‌شوند.

PCPIntro(1), pmdammv(1), PMAPI(3), PMDA(3), mmv_stats_registry(3), pcp.conf(5) و pcp.env(5).

Performance Co-Pilot