نام (NAME)

pmlogrewrite - بازنویسی آرشیوهای ثبت عملکرد Performance Co-Pilot (PCP)

خلاصه دستور (SYNOPSIS)

pmlogrewrite [-Cdiqsvw?] [-c config] [-D debug] [-V version] inlog [outlog]

توضیحات (DESCRIPTION)

دستور pmlogrewrite مجموعه‌ای از آرشیوهای Performance Co-Pilot (PCP) مشخص‌شده توسط inlog را خوانده و یک آرشیو PCP جدید در outlog ایجاد می‌کند. در کاربرد معمول، از گزینه -c برای معرفی یک یا چند فایل پیکربندی استفاده می‌شود که حاوی مشخصات و قواعد (بخش نحو قواعد بازنویسی (REWRITING RULES SYNTAX) در زیر را ببینید) هستند و نحوه تبدیل داده‌ها و متادیتای inlog برای تولید outlog را شرح می‌دهند.

کاربرد متداول pmlogrewrite برای سازگاری با تغییرات و تکامل عامل‌های دامنه متریک عملکرد (PMDAها) است، جایی که نام‌ها، متادیتا و معناشناسی متریک‌ها و دامنه‌های نمونه (instance domains) مرتبط با آن‌ها ممکن است در طول زمان تغییر کنند؛ برای مثال، ارتقای نوع یک متریک از عدد صحیح ۳۲ بیتی به ۶۴ بیتی، یا تغییر نام گروهی از متریک‌ها. برای موارد کاربرد بیشتر، به بخش مثال‌ها (EXAMPLES) مراجعه کنید.

همچنین می‌توان از pmlogrewrite برای پالایش و حذف اطلاعات حساس (redact) از آرشیوهای PCP استفاده کرد؛ به‌ویژه در شرایطی که آرشیوها باید به سازمان دیگری ارسال شوند یا الزامات مربوط به سیاست‌های حریم خصوصی و قوانین حقوقی رعایت گردد. برای نمونه‌ای از کاربرد pmlogrewrite در این زمینه، به pmlogredact(1) مراجعه کنید.

ابزار pmlogrewrite بیشترین کاربرد را در مواردی دارد که تغییرات PMDA یا بروز خطاها در محیط عملیاتی، منجر به ایجاد آرشیوهایی شده باشند که امکان ادغام آن‌ها با pmlogextract(1) وجود ندارد. با پیش‌پردازش آرشیوها توسط pmlogrewrite، آرشیوهای حاصل ممکن است قابلیت ادغام با pmlogextract(1) را به دست آورند.

ورودی inlog باید مجموعه‌ای از آرشیوهای PCP ایجادشده توسط pmlogger(1) یا ابزارهایی باشد که توانایی خواندن و ساخت آرشیوهای PCP را دارند، مانند pmlogextract(1) و pmlogreduce(1). مقدار inlog فهرستی از نام‌ها است که با ویرگول (کاما) از هم جدا شده‌اند و هر کدام می‌تواند نام پایه یک آرشیو یا نام پوشه‌ای حاوی یک یا چند آرشیو باشد.

اگر گزینه -c مشخص نشود، رفتار پیش‌فرض این است که به سادگی outlog را به عنوان یک کپی از inlog ایجاد می‌کند. این عملیات کمی پیچیده‌تر از cat(1) است، زیرا هر آرشیو PCP از چندین فایل فیزیکی مجزا تشکیل شده است.

اگرچه pmlogrewrite می‌تواند برای ترمیم برخی مشکلات سازگاری و یکپارچگی داده‌ها در آرشیوهای PCP استفاده شود، اما دسته‌ای از وظایف ترمیم وجود دارند که توسط pmlogrewrite پشتیبانی نمی‌شوند و ابزار pmloglabel(1) ممکن است در این موارد ابزار مفیدی باشد.

گزینه‌ها (OPTIONS)

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

-c config, --config=config: اگر config یک فایل یا پیوند نمادین (symlink) باشد، قواعد بازنویسی را از آنجا خوانده و تحلیل (parse) می‌کند. اگر config یک پوشه باشد، تمام فایل‌ها یا پیوندهای نمادین درون آن پوشه (به استثنای آن‌هایی که با نقطه «.» شروع می‌شوند) برای تامین قواعد بازنویسی به کار می‌روند. در حالت پوشه، پویش با استفاده از scandir(3) و الگوریتم مرتب‌سازی مبتنی بر strcmp(3) انجام می‌شود، بنابراین ورودی‌ها به ترتیب نام فایل مرتب و پردازش می‌شوند. استفاده همزمان از چند گزینه -c مجاز است.
-C, --check: قواعد بازنویسی را تحلیل و بررسی کرده و خارج می‌شود. آرشیو outlog ایجاد نمی‌شود، بنابراین در حضور گزینه -C، این آرگومان اختیاری است. هنگامی که گزینه -C مشخص می‌شود، به طور خودکار گزینه‌های -v و -w را نیز فعال می‌کند تا تمام پیام‌های مشروح و هشدارهای حین تحلیل config نمایش داده شوند.
-d, --desperate: حالت اضطراری (Desperate mode). در حالت عادی اگر خطای مهلکی رخ دهد، تمام آثار آرشیو PCP نیمه‌کاره نوشته‌شده در outlog حذف می‌شوند. با استفاده از گزینه -d، آرشیو نیمه‌کاره ایجادشده در outlog حذف نمی‌شود.
-i: به جای ایجاد outlog، با استفاده از گزینه -i آرشیو inlog به صورت درجا (in-place) بازنویسی می‌شود. ابتدا یک آرشیو موقت با نام‌های موقت ایجاد شده و سپس به inlog تغییر نام می‌یابد؛ به طوری که اگر خطایی (به جز هشدارها) رخ دهد، inlog بدون تغییر باقی می‌ماند.
-q, --quick: حالت سریع؛ اگر هیچ عملیات بازنویسی برای انجام وجود نداشته باشد (هیچ داده عمومی، دامنه نمونه یا متریکی از inlog تغییر نکند)، pmlogrewrite بلافاصله پس از تحلیل فایل‌های پیکربندی با کد وضعیت ۰ (موفقیت‌آمیز) خارج شده و outlog ایجاد نمی‌شود.
-s, --scale: هنگامی که «واحدهای» یک متریک تغییر می‌کنند، اگر ابعاد از نظر فضا، زمان و شمارش بدون تغییر بمانند، ضریب مقیاس (scale factor) در حال تغییر است؛ مانند تبدیل BYTE به KBYTE، یا MSEC-1 به USEC-1، یا تبدیل مرکب MBYTE.SEC-1 به KBYTE.USEC-1. علت این امر ممکن است این باشد که (الف) متادیتای اولیه اشتباه بوده اما مقادیر درون inlog صحیح هستند، یا (ب) متادیتا تغییر می‌کند و بنابراین مقادیر نیز باید تغییر کنند. رفتار پیش‌فرض pmlogrewrite مطابق حالت (الف) است. اگر حالت (ب) مد نظر باشد، از گزینه -s استفاده کنید تا مقادیر تمام متریک‌هایی که دارای تغییر ضریب مقیاس هستند در هر نتیجه مجدداً مقیاس‌بندی شوند. برای کنترل دقیق‌تر روی تغییر مقیاس مقادیر، به گزینه RESCALE در بندهای UNITS و EXTRAUNITS از قواعد بازنویسی متریک در زیر مراجعه کنید.
-v, --verbose: فعال کردن حالت مشروح (verbose).
-V version, --version=version: نسخه آرشیو PCP خروجی در حال تولید را مشخص می‌کند. در حال حاضر نسخه‌های ۲ و ۳ از قالب آرشیو پشتیبانی می‌شوند. نسخه inlog باید حداکثر برابر با version باشد (ارتقای نسخه مجاز است، اما تنزل نسخه مجاز نیست). به طور پیش‌فرض، در غیاب گزینه -V، نسخه outlog مشابه نسخه inlog خواهد بود.
-w, --warnings: انتشار هشدارها. به طور معمول pmlogrewrite در مورد هشدارهای غیرمهلک سکوت می‌کند، چرا که انتظار می‌رود برای یک آرشیو خاص، برخی (یا حتی همه) مشخصات بازنویسی اعمال نشوند. به عنوان مثال، تغییرات یک PMDA ممکن است در مجموعه‌ای از قواعد بازنویسی گنجانده شده باشد، اما یک آرشیو منفرد ممکن است شامل تمام متریک‌های تغییریافته یا تمام دامنه‌های نمونه و نمونه‌های اصلاح‌شده نباشد. از آنجا که این موارد طبیعی هستند، مانع اجرای pmlogrewrite نمی‌شوند و قواعدی که روی inlog اعمال‌پذیر نیستند به طور پیش‌فرض نادیده گرفته می‌شوند. مشابهاً، ممکن است برخی قواعد بازنویسی تغییری ایجاد نکنند، زیرا متادیتای درون inlog از قبل با هدف قاعده بازنویسی (برای اصلاح داده‌های نسخه پیشین PMDA) مطابقت دارد. پرچم -w انتشار هشدار برای تمام این موارد را اجباری می‌کند.
-?, --help: نمایش راهنمای استفاده از دستور و خروج.

آرگومان outlog در تمام موارد الزامی است، مگر در حالتی که گزینه -i مشخص شده باشد.

نحو قواعد بازنویسی (REWRITING RULES SYNTAX)

یک فایل پیکربندی شامل صفر یا چند قاعده بازنویسی به شرح زیر است.

کلمات کلیدی و نویسه‌های خاص نشانه‌گذاری در زیر با فونت bolditalic نشان داده شده‌اند و به حروف بزرگ و کوچک حساس نیستند (case-insensitive)؛ بنابراین METRIC، metric و Metric همگی در قواعد بازنویسی معادل یکدیگرند.

نویسه «#» یک توضیح (comment) را آغاز می‌کند و باقی‌مانده آن خط نادیده گرفته می‌شود. در غیر این صورت، فرمت ورودی نسبتاً آزاد است و فاصله‌های خالی اختیاری (فاصله، تب یا خطوط جدید) می‌توانند میان عناصر واژگانی قواعد قرار گیرند.

یک قاعده بازنویسی global (سراسری) دارای ساختار زیر است:

GLOBAL { globalspec ... }

که در آن globalspec شامل صفر یا چند بند (clause) زیر است:

HOSTNAME -> hostname

رکوردهای برچسب را در آرشیو PCP outlog به گونه‌ای تغییر می‌دهد که به نظر برسد متریک‌ها از میزبان hostname جمع‌آوری شده‌اند.

TIME -> delta

هم مقادیر متریک‌ها و هم متادیتای دامنه‌های نمونه در یک آرشیو PCP دارای برچسب‌های زمانی (timestamp) هستند. این بند اجبار می‌کند که تمام برچسب‌های زمانی به میزان delta تعدیل شوند؛ که در آن delta می‌تواند دارای یک علامت اختیاری «+» (پیش‌فرض) یا «-»، تعداد ساعت اختیاری به همراه دو نقطه «:»، تعداد دقیقه اختیاری به همراه دو نقطه «:»، تعداد ثانیه‌ها و بخش کسری اختیاری ثانیه‌ها پس از ممیز «.» باشد. ساده‌ترین مثال «30» برای افزایش ۳۰ ثانیه‌ای برچسب‌های زمانی است. یک مثال پیچیده‌تر «-23:59:59.999» است تا برچسب‌های زمانی به میزان یک میلی‌ثانیه کمتر از یک شبانه‌روز به عقب برده شوند.

TIMEZONE -> "timezone"
TZ -> "timezone"

رکوردهای برچسب را در آرشیو PCP outlog به گونه‌ای تغییر می‌دهد که به نظر برسد متریک‌ها از میزبانی با منطقه زمانی محلی timezone جمع‌آوری شده‌اند. مقدار timezone باید داخل نقل‌قول دوتایی (double quotes) محصور شود و با قواعد ساختاری معتبر منطقه زمانی پلتفرم محلی، معمولاً فرمت Posix TZ، مطابقت داشته باشد؛ مانند AEST-10. برای اطلاعات بیشتر به tzset(3) مراجعه کنید.

کلمه کلیدی TZ نام مستعاری برای TIMEZONE است.

ZONEINFO -> "zoneinfo"

رکوردهای برچسب را در آرشیو PCP outlog تغییر می‌دهد تا چنین به نظر برسد که متریک‌ها از میزبانی با منطقه زمانی محلی zoneinfo جمع‌آوری شده‌اند. مقدار zoneinfo باید داخل نقل‌قول دوتایی محصور شود و با قواعد ساختاری منطقه زمانی zoneinfo پلتفرم محلی همخوانی داشته باشد؛ معمولاً یک دو نقطه به همراه مسیر زیر /usr/share/zoneinfo، مانند :Africa/Timbuktu. برای اطلاعات بیشتر به tzset(3) مراجعه فرمایید.

استفاده از بند zoneinfo تنها در صورتی مجاز است که نسخه آرشیو خروجی حداقل ۳ باشد.

FEATURES -> feature-bits

رکوردهای برچسب را در آرشیو PCP outlog به گونه‌ای تغییر می‌دهد که به نظر برسد متریک‌ها از سیستمی با یک pmlogger(1) جمع‌آوری شده‌اند که از «ویژگی‌های» تعریف‌شده توسط مقدار عدد صحیح feature-bits پشتیبانی می‌کند؛ این مقدار از طریق عملگر «یا» (OR) بیتی روی پرچم‌های ویژگی مورد نظر همان‌طور که در LOGARCHIVE(5) تعریف شده، تشکیل می‌شود. همچنین، feature-bits را می‌توان با استفاده از ماکروی BITS() مشخص کرد که فهرستی از اعداد صحیح جداشده با ویرگول (در محدوده فراگیر ۰ تا ۳۱) را دریافت کرده و بیت‌های مربوطه را تنظیم می‌کند. به عنوان مثال:

features -> bits(31,7,1)

استفاده از بند features تنها در صورتی مجاز است که نسخه آرشیو خروجی حداقل ۳ باشد.

یک قاعده بازنویسی indom یک دامنه نمونه (instance domain) را تغییر می‌دهد و ساختار زیر را دارد:

INDOM domain.serial { indomspec ... }

که در آن domain و serial یک یا چند دامنه نمونه موجود از inlog را مشخص می‌کنند؛ معمولاً domain یک عدد صحیح در محدوده ۱ تا ۵۱۰ و serial یک عدد صحیح در محدوده ۰ تا ۴۱۹۴۳۰۴ است.

به عنوان یک حالت خاص، serial می‌تواند یک ستاره «*» باشد که نشان می‌دهد قاعده بر تمام دامنه‌های نمونه با شماره دامنه domain اعمال می‌شود.

اگر یک دامنه نمونه تعیین‌شده در inlog وجود نداشته باشد، قاعده هیچ تاثیری نخواهد داشت.

مقدار indomspec شامل صفر یا چند مورد از بندهای زیر است:

INAME "oldname" -> "newname"

نام نمونه مشخص‌شده با نام خارجی oldname به newname تغییر می‌یابد. هر دو مقدار oldname و newname باید داخل نقل‌قول دوتایی (double quotes) محصور شوند.

به عنوان یک حالت خاص، نام جدید می‌تواند کلمه کلیدی DELETE (بدون نقل‌قول) باشد، که در این صورت نمونه oldname از outlog حذف کامل (expunge) می‌شود؛ این کار آن را از متادیتای دامنه نمونه و تمام مقادیر این نمونه را برای کلیه متریک‌های مرتبط حذف می‌کند.

اگر نام‌های نمونه حاوی فاصله‌های خالی تعبیه‌شده باشند، باید با توجه به قاعده نام‌گذاری نمونه‌های PCP که بخش اولیه غیرفاصله‌ای نام نمونه را به عنوان بخش یکتا برای مقاصد تطبیق و تضمین یکتایی در نظر می‌گیرد، دقت ویژه‌ای به کار رود؛ برای بررسی این موضوع به pmdaInstance(3) مراجعه فرمایید.

برای نمونه، یک دامنه نمونه فرضی را برای متریکی در نظر بگیرید که شامل ۲ نمونه با نام‌های زیر است:

red
eek urk

سپس چند بند احتمالی INAME می‌تواند به صورت زیر باشد:

"eek" -> "yellow like a flower": قابل قبول است، oldname به نام "eek" با نمونه "eek urk" مطابقت دارد.
"red" -> "eek": خطا، newname به نام "eek" با نمونه موجود "eek urk" تداخل و تطابق دارد.
"eek urk" -> "red of another hue": خطا، newname به نام "red of another hue" با نمونه موجود "red" تداخل و تطابق دارد.

INAME REPLACE /pattern/ -> "replacement"

هر نام نمونه خارجی در دامنه نمونه با عبارت باقاعده (regular expression) pattern تطبیق داده می‌شود و هنگام یافتن تطابق، نام بر اساس بخش‌های تطبیق‌یافته توسط pattern و دستورالعمل replacement تغییر می‌کند. pattern از نحو عبارت باقاعده تعمیم‌یافته پازیکس (Posix Extended Regular Expression، به regex(7) مراجعه کنید) پیروی می‌کند و replacement از نحو دستور s در sed(1) پیروی می‌نماید؛ بنابراین & و \1 تا \9 می‌توانند برای انتخاب تمام یا زیررشته‌هایی از نام نمونه که با pattern تطبیق یافته‌اند استفاده شوند.

توجه داشته باشید که عملیات تطبیق و جایگزینی حداکثر یک بار برای هر نام نمونه خارجی انجام می‌شود؛ بنابراین اگر توالی‌های تکراری در نام وجود داشته باشد که با pattern تطبیق یابند، تنها اولین مورد تطبیق داده شده و replacement روی آن اعمال می‌گردد.

مقدار pattern معمولاً درون اسلش (/) یا نقل‌قول دوتایی (") محصور می‌شود. می‌توان از نویسه گریز (\) قبل از هر یک از فرانویسه‌های شرح‌داده‌شده در regex(3) برای مشخص کردن نویسه لفظی (literal) استفاده کرد، مانند \( یا \[ یا \+ و ... جداکننده‌های محصورکننده را نمی‌توان با کاراکتر گریز اسکیپ کرد، بنابراین برای درج یک اسلش واقعی، از نقل‌قول دوتایی به عنوان جداکننده استفاده کنید و برعکس.

مقدار replacement معمولاً درون نقل‌قول دوتایی (") یا اسلش (/) قرار می‌گیرد. می‌توان از نویسه گریز (\) قبل از & یا \ برای مشخص کردن لفظی این نویسه‌ها استفاده کرد. جداکننده‌های محصورکننده اسکیپ‌پذیر نیستند، بنابراین برای درج یک نقل‌قول دوتایی واقعی، از اسلش به عنوان جداکننده استفاده کنید و برعکس.

اگر نام‌های نمونه پس از جایگزینی حاوی فاصله‌های تعبیه‌شده باشند، باید در ارتباط با قاعده نام‌گذاری نمونه‌های PCP دقت خاصی مبذول شود؛ قاعده‌ای که بخش اولیه غیرفاصله‌ای نام را به عنوان بخش یکتای نام جهت تطبیق و یکتایی در نظر می‌گیرد. برای مطالعه بیشتر به pmdaInstance(3) مراجعه کنید.

در اینجا چند مثال آورده شده است:

{ iname replace /[a-z]*foo[a-z]*/ -> "FOO" }: جایگزینی هر کلمه حاوی "foo" با "FOO"
{ iname replace "([0-9]+) /.*/(.*)" -> "\1 \2" }: حذف مسیر پوشه، به طوری که نام نمونه (برای یکی از متریک‌های proc PMDA) از "2981799 /home/kenj/bin/foobar" تبدیل به "2981799 foobar" می‌شود و بدین ترتیب پوشه خانگی و به طور ضمنی نام کاربری مخفی می‌گردد

INAME REDACT

جایگزینی هر نام نمونه خارجی در دامنه نمونه با رشته "inst [redacted]" که در آن inst شناسه داخلی نمونه در قالب ASCII است.

INDOM -> newdomain.newserial

متادیتای دامنه نمونه و تمام متریک‌های مرتبط با آن دامنه نمونه را تغییر می‌دهد. به عنوان یک حالت خاص، newserial می‌تواند یک ستاره «*» باشد که به معنای استفاده از serial قاعده بازنویسی indom است، اگرچه این حالت بیشترین کاربرد را زمانی دارد که serial نیز ستاره باشد. به عنوان مثال:

indom 29.* { indom -> 109.* }

تمام دامنه‌های نمونه را از دامنه ۲۹ به دامنه ۱۰۹ منتقل می‌کند.

INDOM -> DUPLICATE newdomain.newserial

حالت خاصی از بند قبلی INDOM است که در آن دامنه نمونه یک نسخه تکثیرشده (duplicate) از دامنه نمونه domain.serial در قاعده بازنویسی indom است و سپس هرگونه قواعد نگاشت روی دامنه نمونه کپی‌شده newdomain.newserial اعمال می‌شود. این ویژگی زمانی مفید است که یک PMDA تفکیک شده و همان دامنه نمونه باید برای هر دو دامنه domain و newdomain بازتولید شود. به عنوان مثال اگر متریک‌های foo.one و foo.two هر دو روی دامنه نمونه 12.34 تعریف شده باشند و foo.two به PMDA دیگری با دامنه 27 منتقل شود، قواعد بازنویسی زیر می‌تواند به کار رود:

indom 12.34 { indom -> duplicate 27.34 }
metric foo.two { indom -> 27.34 pmid -> 27.*.* }

INST oldid -> newid

شناسه نمونه مشخص‌شده با شناسه داخلی oldid به newid شماره‌گذاری مجدد می‌شود. هر دو مقدار oldid و newid اعداد صحیحی در محدوده ۰ تا 231-1 هستند.

به عنوان یک حالت خاص، newid می‌تواند کلمه کلیدی DELETE باشد که در این صورت نمونه oldid از outlog حذف کامل خواهد شد و از متادیتای دامنه نمونه به همراه تمام مقادیر این نمونه برای کلیه متریک‌های مربوطه پاک می‌شود.

یک قاعده بازنویسی metric دارای ساختار زیر است:

METRIC metricid { metricspec ... }

که در آن metricid یک یا چند متریک موجود در inlog را با استفاده از نام متریک یا کدگذاری داخلی برای PMID متریک به صورت domain.cluster.item مشخص می‌کند. در حالت دوم، معمولاً domain یک عدد صحیح در محدوده ۱ تا ۵۱۰، cluster یک عدد صحیح در محدوده ۰ تا ۴۰۹۵، و item یک عدد صحیح در محدوده ۰ تا ۱۰۲۳ خواهد بود.

به عنوان حالت‌های خاص، item می‌تواند یک ستاره «*» باشد که نشان می‌دهد قاعده بر تمام متریک‌های با شماره دامنه domain و شماره کلاستر cluster اعمال می‌شود؛ یا cluster می‌تواند یک ستاره باشد که نشان می‌دهد قاعده بر تمام متریک‌های با شماره دامنه domain و شماره آیتم item اعمال می‌گردد؛ یا هر دوی cluster و item می‌توانند ستاره باشند، که در این صورت قاعده بر تمام متریک‌های دارای شماره دامنه domain اعمال می‌شود.

اگر یک متریک تعیین‌شده در inlog وجود نداشته باشد، قاعده هیچ تاثیری نخواهد داشت.

مقدار metricspec شامل صفر یا چند بند زیر است:

DELETE

متریک به طور کامل از outlog حذف می‌شود؛ هم متادیتا و هم تمام مقادیر آن در نتایج به کلی پاک (expunge) می‌گردند.

INDOM -> newdomain.newserial [ pick ]

متادیتا را برای تغییر دامنه نمونه این متریک اصلاح می‌کند. دامنه نمونه جدید باید در outlog وجود داشته باشد.

بند اختیاری pick می‌تواند برای انتخاب یک مقدار ورودی، یا محاسبه یک مقدار تجمیعی از روی نمونه‌های موجود در یک نتیجه ورودی، یا انتساب یک شناسه نمونه داخلی به یک مقدار خروجی منفرد به کار رود. اگر بند pick مشخص نشود، رفتار پیش‌فرض کپی کردن تمام مقادیر ورودی از هر نتیجه ورودی به یک نتیجه خروجی است؛ با این حال اگر دامنه نمونه ورودی منفرد باشد (indom PM_INDOM_NULL)، آن‌گاه باید به مقدار خروجی یک شناسه نمونه داخلی اختصاص یابد که به طور پیش‌فرض 0 است، مگر اینکه توسط بندهای INST یا INAME به شرح زیر بازنویسی شود.

گزینه‌های قابل انتخاب برای pick به شرح زیر هستند:

OUTPUT FIRST: انتخاب مقدار اولین نمونه از هر نتیجه ورودی
OUTPUT LAST: انتخاب مقدار آخرین نمونه از هر نتیجه ورودی
OUTPUT INST instid: انتخاب مقدار نمونه دارای شناسه داخلی instid از هر نتیجه؛ توالی پردازش قواعد بازنویسی تضمین می‌کند که پردازش OUTPUT پیش از شماره‌گذاری مجدد شناسه‌های نمونه از هر قاعده indom مرتبط رخ دهد، بنابراین instid باید یکی از شناسه‌های نمونه داخلی باشد که در inlog ظاهر می‌شود
OUTPUT INAME "name": انتخاب مقدار نمونه دارای نام خارجی name از هر نتیجه؛ توالی پردازش قواعد تضمین می‌کند که پردازش OUTPUT پیش از تغییر نام نمونه از هر قاعده indom مرتبط انجام گیرد، بنابراین name باید یکی از نام‌های خارجی نمونه باشد که در inlog ظاهر شده است
OUTPUT MIN: انتخاب کوچک‌ترین مقدار در هر نتیجه (نوع متریک باید عددی باشد و شناسه نمونه خروجی برای دامنه نمونه غیرمنفرد، 0 خواهد بود)
OUTPUT MAX: انتخاب بزرگ‌ترین مقدار در هر نتیجه (نوع متریک باید عددی باشد و شناسه نمونه خروجی برای دامنه نمونه غیرمنفرد، 0 خواهد بود)
OUTPUT SUM: انتخاب مجموع تمام مقادیر در هر نتیجه (نوع متریک باید عددی باشد و شناسه نمونه خروجی برای دامنه نمونه غیرمنفرد، 0 خواهد بود)
OUTPUT AVG: انتخاب میانگین تمام مقادیر در هر نتیجه (نوع متریک باید عددی باشد و شناسه نمونه خروجی برای دامنه نمونه غیرمنفرد، 0 خواهد بود)

اگر دامنه نمونه ورودی منفرد باشد (indom PM_INDOM_NULL)، صرف‌نظر از هرگونه مشخصات pick، حداکثر یک مقدار در هر نتیجه ورودی وجود دارد و بنابراین FIRST، LAST، MIN، MAX، SUM و AVG همگی معادل یکدیگرند و شناسه نمونه خروجی 0 خواهد بود.

به طور کلی مشخص کردن یک عمل بازنویسی برای یک متادیتا یا مقادیر نتایج یکسان بیش از یک بار خطا محسوب می‌شود؛ مثلاً بیش از یک بند INDOM برای یک دامنه نمونه یکسان. تنها استثنا، تداخل احتمالی میان بندهای INDOM در قواعد indom و metric است. به عنوان مثال، متریک sample.bin بر روی دامنه نمونه 29.2 در inlog تعریف شده است و مورد زیر قابل قبول است (اگرچه افزونه و تکراری است):

indom 29.* { indom -> 109.* }
metric sample.bin { indom -> 109.2 }

اما مورد زیر یک خطا است، زیرا دامنه نمونه برای sample.bin دارای دو تعریف متناقض خواهد بود:

indom 29.* { indom -> 109.* }
metric sample.bin { indom -> 123.2 }

INDOM -> NULL[ pick ]

متریک (که قبلاً باید بر روی یک دامنه نمونه تعریف شده باشد) تغییر می‌یابد تا به یک متریک منفرد (singular) تبدیل شود. این کار شامل تغییر متادیتا و ادغام و فروپاشی تمام نتایج برای این متریک است، به گونه‌ای که مقادیر متعدد به یک مقدار واحد تبدیل شوند.

بخش اختیاری pick در این بند نحوه محاسبه آن مقدار واحد برای هر نتیجه را تعریف می‌کند و از همان قواعد شرح‌داده‌شده برای حالت INDOM غیر تهی (non-NULL) در بالا پیروی می‌نماید.

در صورت عدم تعیین pick، حالت پیش‌فرض OUTPUT FIRST است.

NAME -> newname
NAME -> newname DUPOK

متریک را در متادیتای آرشیو PCP که از فضای نام متریک‌های عملکرد (PMNS) پشتیبانی می‌کند، تغییر نام می‌دهد. مقدار newname باید از قواعد ساختاری نام‌های معتبر متریک که در PMNS(5) توصیف شده پیروی کند. در حالت عادی newname نباید با هیچ نام موجود دیگری در PMNS آرشیو مطابقت داشته باشد، اما کلمه کلیدی DUPOK می‌تواند برای رفع این محدودیت استفاده شود؛ مثلاً در مواردی که یک چرخه از تغییر نام‌های مرتبط انجام می‌شود، مانند foo -> mumble و mumble -> fratz و fratz -> foo.

PMID -> newdomain.newcluster.newitem

متادیتا و نتایج را برای شماره‌گذاری مجدد PMID متریک تغییر می‌دهد. به عنوان حالت‌های خاص، newcluster می‌تواند یک ستاره «*» باشد که به معنای استفاده از cluster در قاعده بازنویسی metric است و/یا item می‌تواند یک ستاره باشد که به معنای استفاده از item در قاعده بازنویسی metric است. این قابلیت بیشترین کاربرد را زمانی دارد که cluster و/یا item نیز ستاره باشند. به عنوان مثال:

metric 30.*.* { pmid -> 123.*.* }

تمام متریک‌ها را از دامنه ۳۰ به دامنه ۱۲۳ منتقل می‌کند.

SEM -> newsem

تغییر معناشناسی (semantics) متریک. مقدار newsem باید بخش XXX از نام یکی از ماکروهای PM_SEM_XXX تعریف‌شده در <pcp/pmapi.h> یا pmLookupDesc(3) باشد؛ مثلاً COUNTER برای PM_TYPE_COUNTER.

در اثر بند SEM هیچ بازنویسی روی مقادیر داده‌ها انجام نمی‌شود، بنابراین کاربرد آن محدود به مواردی است که نسخه‌ای از PMDA مربوطه، معناشناسی نادرستی را برای متریک صادر می‌کرده است. در مواردی که محاسبه مجدد مقادیر نتایج مورد نظر باشد، pmlogreduce(1) می‌تواند جایگزین مناسبی باشد.

TYPE -> newtype

تغییر نوع متریک که متادیتا را تغییر می‌دهد و ممکن است کدگذاری مقادیر را در نتایج عوض کند. مقدار newtype باید بخش XXX از نام یکی از ماکروهای PM_TYPE_XXX تعریف‌شده در <pcp/pmapi.h> یا pmLookupDesc(3) باشد؛ مانند FLOAT برای PM_TYPE_FLOAT.

تبدیل نوع تنها در مواردی پشتیبانی می‌شود که نوع قبلی متریک عددی باشد؛ بنابراین انواع PM_TYPE_STRING، PM_TYPE_AGGREGATE، PM_TYPE_EVENT و PM_TYPE_HIGHRES_EVENT مجاز نیستند. مشابهاً، نوع جدید متریک باید عددی یا PM_TYPE_STRING باشد. حتی در موارد عددی، برخی تبدیل‌ها ممکن است خطاهای زمان اجرا ایجاد کنند؛ مانند سرریز عدد صحیح (integer overflow)، تلاش برای بازنویسی مقدار منفی در نوع بدون علامت، یا عدم دقت مانند زمان تبدیل نوع اعشاری float یا double به رشته.

TYPE IF oldtype -> newtype

مشابه بند قبلی TYPE است، با این تفاوت که نوع متریک تنها در صورتی به newtype تغییر می‌یابد که نوع متریک در inlog برابر با oldtype باشد.

این بند در مواردی مفید است که نوع metricid در inlog وابسته به پلتفرم باشد و بنابراین به بیش از یک قاعده بازنویسی نوع نیاز باشد.

UNITS -> newunits [ RESCALE ]

مقدار newunits شش مقدار جداشده با ویرگول است. ۳ مقدار نخست ابعاد متریک را در راستای ابعاد فضا، زمان و شمارش توصیف می‌کنند؛ این‌ها مقادیر صحیح و معمولاً 0، 1 یا -1 هستند. ۳ مقدار باقی‌مانده مقیاس مقادیر متریک را در ابعاد فضا، زمان و شمارش مشخص می‌سازند. مقادیر مقیاس فضا باید 0 (اگر بعد فضا 0 باشد) یا بخش XXX از نام یکی از ماکروهای PM_SPACE_XXX باشند؛ مثلاً KBYTE برای PM_TYPE_KBYTE. مقادیر مقیاس زمان باید 0 (اگر بعد زمان 0 باشد) یا بخش XXX از نام یکی از ماکروهای PM_TIME_XXX باشند؛ مثلاً SEC برای PM_TIME_SEC. مقادیر مقیاس شمارش باید 0 (اگر بعد شمارش 0 باشد) یا ONE برای PM_COUNT_ONE باشند.

ماکروهای PM_SPACE_XXX، PM_TIME_XXX و PM_COUNT_XXX در فایل <pcp/pmapi.h> یا در pmLookupDesc(3) تعریف شده‌اند.

هنگامی که مقیاس تغییر می‌کند (اما بعد بدون تغییر باقی می‌ماند)، می‌توان از کلمه کلیدی اختیاری RESCALE استفاده کرد تا مقادیر مشابه گزینه خط فرمان -s تغییر مقیاس یابند، اما این تغییر فقط بر همین متریک اعمال می‌شود.

EXTRAUNITS -> newextraunits [ RESCALE ]

دارای معنایی مشابه بند UNITS است، با این تفاوت که newextraunits شامل هشت مقدار جداشده با ویرگول است. شش مقدار اول دقیقاً مشابه newunits در بند UNITS هستند. مقدار هفتم یکی از واحدهای «اضافی» را مشخص می‌کند و باید 0 (در صورت عدم وجود) یا بخش XXX از نام یکی از ماکروهای PM_UNIT_XXX باشد؛ مثلاً TEMPERATURE برای PM_UNIT_TEMPERATURE. مقدار هشتم مقیاس واحد «اضافی» را مشخص می‌کند و باید 0 (در صورت عدم وجود) یا بخش XXX از نام یکی از ماکروهای مرتبط PM_<unit>_XXX باشد؛ مانند C برای PM_TEMPERATURE_C (مقدار، دما بر حسب درجه سلسیوس است).

کلمه کلیدی اختیاری RESCALE دارای مفهومی مشابه بند UNITS است.

VALUE REPLACE /pattern/ -> "replacement"

مقدار هر نمونه از متریک با عبارت باقاعده pattern تطبیق داده می‌شود و هنگام یافتن تطابق، مقدار بر اساس بخش‌های تطبیق‌یافته توسط pattern و دستورالعمل replacement تغییر می‌کند. مقدار pattern از نحو عبارت باقاعده تعمیم‌یافته پازیکس (به regex(7) مراجعه کنید) پیروی می‌کند و replacement از نحو دستور s در sed(1) پیروی می‌نماید؛ بنابراین & و \1 تا \9 می‌توانند برای انتخاب تمام یا زیررشته‌هایی از مقدار که با pattern تطبیق یافته‌اند استفاده شوند.

توجه داشته باشید که تطبیق و جایگزینی حداکثر یک بار در هر مقدار متریک انجام می‌شود؛ بنابراین اگر توالی‌های مکرری در مقدار متریک با pattern تطابق یابند، تنها اولین مورد تطبیق داده شده و replacement روی آن اعمال می‌گردد.

مقدار pattern معمولاً درون اسلش (/) یا نقل‌قول دوتایی (") قرار می‌گیرد. می‌توان از نویسه گریز (\) قبل از هر یک از فرانویسه‌های شرح‌داده‌شده در regex(3) برای مشخص کردن نویسه لفظی استفاده کرد؛ مثلاً \( یا \[ یا \+ و ... جداکننده‌های محصورکننده اسکیپ‌پذیر نیستند، بنابراین برای درج یک اسلش واقعی، از نقل‌قول دوتایی به عنوان جداکننده استفاده کنید و برعکس.

مقدار replacement معمولاً درون نقل‌قول دوتایی (") یا اسلش (/) محصور می‌شود. می‌توان از نویسه گریز (\) قبل از & یا \ برای درج لفظی این نویسه‌ها استفاده کرد. جداکننده‌های محصورکننده اسکیپ‌پذیر نیستند، بنابراین برای درج نقل‌قول دوتایی واقعی، از اسلش به عنوان جداکننده استفاده کنید و برعکس.

کلمه کلیدی REPLACE اختیاری است.

این بند تنها بر متریک‌هایی قابل اعمال است که دارای مقادیری از نوع PM_TYPE_STRING باشند.

در اینجا چند مثال آورده شده است:

{ value /.*/ -> "" }: حذف مقدار در همه جا
value "/.*/(.*)" -> "\1" }: حذف مسیر یک پوشه؛ به طوری که مقدار متریک "mumble /home/kenj/bin/foobar fumble" تبدیل به "mumble foobar fumble" می‌شود و بدین ترتیب پوشه خانگی و نام ورود کاربر پنهان می‌گردد

هنگام تغییر شماره دامنه برای یک متریک یا دامنه نمونه، شماره دامنه جدید معمولاً با شماره دامنه یک PMDA موجود مطابقت خواهد داشت. اگر چنین نباشد، شماره دامنه جدید نباید تصادفی انتخاب شود؛ فایل $PCP_VAR_DIR/pmns/stdpmid را برای شماره دامنه‌هایی که قبلاً به PMDAها تخصیص یافته‌اند بررسی کنید.

یک قاعده بازنویسی text یک رکورد متن راهنما (help text) را تغییر می‌دهد و ساختار زیر را دارد:

TEXT textid [ texttype ] [ "textcontent" ] { textspec ... }

که در آن textid متریک یا دامنه نمونه‌ای را که متن در حال حاضر با آن مرتبط است مشخص می‌کند و می‌تواند به صورت METRIC metricid یا INDOM domain.serial باشد.

مقدار metricid ساختار و معنایی مشابه قاعده بازنویسی METRIC دارد (در بالا ملاحظه کنید) و domain.serial دارای ساختار و مفهومی مشابه قاعده بازنویسی INDOM است (در بالا ملاحظه کنید).

مقدار اختیاری texttype نوع متن را مشخص می‌کند و می‌تواند یکی از موارد زیر باشد: ONELINE برای انتخاب متن راهنمای تک‌خطی، HELP برای انتخاب متن کامل راهنما، یا ALL یا یک ستاره «*» برای انتخاب هر دو نوع متن راهنما. اگر texttype مشخص نشود، مقدار پیش‌فرض ONELINE خواهد بود.

مقدار اختیاری textcontent رکوردهای متنی انتخاب‌شده را به مواردی که شامل محتوای تعیین‌شده هستند محدودتر می‌کند. نویسه‌هایی مانند نقل‌قول دوتایی می‌توانند با قرار دادن یک بک‌اسلش «\» قبل از آن‌ها اسکیپ شوند.

اگر یک رکورد متن راهنمای مشخص‌شده در inlog وجود نداشته باشد، قاعده هیچ اثری نخواهد داشت.

مقدار textspec شامل صفر یا چند بند از موارد زیر است:

DELETE

متن انتخاب‌شده به طور کامل از outlog حذف می‌شود.

INDOM -> newdomain.newserial

متن را با دامنه نمونه مشخص‌شده مرتبط می‌سازد. به عنوان یک حالت خاص، newserial می‌تواند یک ستاره «*» باشد که به معنای استفاده از serial در قاعده بازنویسی text است؛ البته این حالت بیشترین فایده را زمانی دارد که serial نیز ستاره باشد. به عنوان مثال:

text indom 29.* all { indom -> 109.* }

تمام متن‌های مرتبط با دامنه‌های نمونه از دامنه ۲۹ را به دامنه ۱۰۹ مرتبط می‌کند.

METRIC -> newdomain.newcluster.newitem

متن را مجدداً با متریک مشخص‌شده مرتبط می‌کند. به عنوان حالت‌های خاص، newcluster می‌تواند یک ستاره «*» باشد که به معنای استفاده از cluster قاعده بازنویسی text است و/یا item می‌تواند یک ستاره باشد که به معنای استفاده از item قاعده بازنویسی text است. این مورد بیشترین کاربرد را زمانی دارد که cluster و/یا item نیز ستاره باشند. به عنوان مثال:

text metric 30.*.* all { metric -> 123.*.* }

تمام متن‌های مرتبط با متریک‌ها را از دامنه ۳۰ به دامنه ۱۲۳ مرتبط می‌سازد.

TEXT -> "new-text"

محتوای متن انتخاب‌شده را با new-text جایگزین می‌کند.

یک قاعده بازنویسی label یک رکورد برچسب (label record) را تغییر می‌دهد و ساختار زیر را دارد:

LABEL labelid [ instance ] [ "label-name" ] [ "label-value" ] { labelspec ... }

که در آن labelid به زمینه سراسری (global context) اشاره می‌کند یا دامنه متریک، کلاستر متریک، آیتم متریک، دامنه نمونه یا نمونه‌های دامنه نمونه را که برچسب در حال حاضر با آن‌ها مرتبط است مشخص می‌سازد، و می‌تواند یکی از موارد زیر باشد: CONTEXT یا DOMAIN domainid یا CLUSTER domainid.clusterid یا ITEM metricid یا INDOM domain.serial یا INSTANCES domain.serial.

مقدار metricid دارای شکل و معنایی مشابه با قاعده بازنویسی METRIC است (در بالا ملاحظه فرمایید). مقدار clusterid می‌تواند یک ستاره «*» باشد که نشان می‌دهد قاعده بر تمام متریک‌های با شماره دامنه domainid اعمال می‌شود، به همان ترتیبی که از ستاره در کلاستر درون metricid استفاده می‌شد.

مقدار domain.serial دارای ساختار و مفهومی مشابه با قاعده بازنویسی INDOM است (در بالا ملاحظه کنید).

در حالت یک labelid از نوع INSTANCES، نام یا شماره یک نمونه خاص می‌تواند به صورت اختیاری به عنوان instance مشخص شود. این نام یا شماره می‌تواند حذف شود یا به عنوان یک ستاره «*» تعیین گردد تا نشان دهد برچسب‌های تمام نمونه‌های دامنه نمونه مشخص‌شده انتخاب شده‌اند. اگر یک نام نمونه مشخص شده باشد، باید درون نقل‌قول دوتایی قرار گیرد. اگر نام نمونه حاوی فاصله‌های خالی تعبیه‌شده باشد، باید با توجه به قاعده نام‌گذاری نمونه‌های PCP که بخش اولیه غیرفاصله‌ای نام نمونه را به عنوان بخش یکتا برای تطبیق و تضمین یکتایی در نظر می‌گیرد دقت شود؛ برای مطالعه بیشتر پیرامون این موضوع به pmdaInstance(3) مراجعه نمایید.

در تمام حالات، یک "label-name" و/یا یک "label-value" می‌تواند به صورت اختیاری درون نقل‌قول دوتایی مشخص شود تا برچسب‌های دارای نام و/یا مقدار داده‌شده انتخاب شوند. هر یک از این‌ها می‌توانند به صورت جداگانه حذف شوند یا به صورت ستاره «*» درج گردند تا نشان دهند برچسب‌های دارای همه نام‌ها و/یا مقادیر انتخاب می‌شوند.

اگر یک رکورد برچسب مشخص‌شده در inlog وجود نداشته باشد، قاعده هیچ اثری نخواهد داشت.

مقدار labelspec شامل صفر یا چند بند زیر است:

DELETE

برچسب‌های انتخاب‌شده به طور کامل از outlog حذف می‌شوند.

NEW "new-label-name" "new-label-value"

یک برچسب جدید با نام "new-label-name" و مقدار "new-label-value" ایجاد شده و با labelid مشخص‌شده و instance اختیاری (در حالت INSTANCES labelid) مرتبط می‌گردد. اگر "label-name" یا "label-value" مشخص شده باشند، به همراه یک هشدار نادیده گرفته می‌شوند. اگر instance برای یک labelid از نوع INSTANCES مشخص نشده باشد، آن‌گاه یک برچسب جدید برای هر نمونه در دامنه نمونه مشخص‌شده ایجاد خواهد شد.

LABEL -> "new-label-name"

نام برچسب یا برچسب‌های انتخاب‌شده به "new-label-name" تغییر می‌یابد.

VALUE -> "new-label-value"

مقدار برچسب یا برچسب‌های انتخاب‌شده به "new-label-value" تغییر می‌کند.

DOMAIN -> newdomain

برچسب یا برچسب‌های انتخاب‌شده را مجدداً با دامنه متریک مشخص‌شده مرتبط می‌سازد. به عنوان مثال:

label domain 30 { domain -> 123 }

تمام برچسب‌های مرتبط با دامنه‌ها را از دامنه ۳۰ به دامنه ۱۲۳ مرتبط می‌کند.

CLUSTER -> newdomain.newcluster

برچسب یا برچسب‌های انتخاب‌شده را مجدداً با کلاستر متریک مشخص‌شده مرتبط می‌کند. به عنوان یک حالت خاص، newcluster می‌تواند یک ستاره «*» باشد که به معنای استفاده از cluster قاعده بازنویسی label است. این مورد زمانی بیشترین کاربرد را دارد که cluster نیز ستاره باشد. به عنوان مثال:

label cluster 30.* { cluster -> 123.* }

تمام برچسب‌های مرتبط با کلاسترها را از دامنه ۳۰ به دامنه ۱۲۳ متصل می‌سازد.

ITEM -> newdomain.newcluster.newitem

برچسب یا برچسب‌های انتخاب‌شده را با آیتم متریک مشخص‌شده مرتبط می‌کند. به عنوان حالت‌های خاص، newcluster می‌تواند یک ستاره «*» باشد که به معنای استفاده از cluster قاعده بازنویسی label است و/یا item می‌تواند یک ستاره باشد که به معنای استفاده از item قاعده بازنویسی label است. این ویژگی بیشترین کاربرد را زمانی دارد که cluster و/یا item نیز ستاره باشند. به عنوان مثال:

label item 30.*.* { item -> 123.*.* }

تمام برچسب‌های مرتبط با متریک‌ها را از دامنه ۳۰ به دامنه ۱۲۳ منتقل می‌نماید.

INDOM -> newdomain.newserial

برچسب یا برچسب‌های انتخاب‌شده را با دامنه نمونه مشخص‌شده مرتبط می‌سازد. به عنوان یک حالت خاص، newserial می‌تواند یک ستاره «*» باشد که به معنای استفاده از serial قاعده بازنویسی label است؛ هرچند این مورد بیشترین فایده را زمانی دارد که serial نیز ستاره باشد. به عنوان مثال:

label indom 29.* { indom -> 109.* }

تمام برچسب‌های مرتبط با دامنه‌های نمونه را از دامنه ۲۹ به دامنه ۱۰۹ مرتبط می‌کند.

INSTANCES -> newdomain.newserial

مشابه INDOM است، با این تفاوت که برچسب یا برچسب‌های انتخاب‌شده را مجدداً با نمونه‌های دامنه نمونه مشخص‌شده مرتبط می‌سازد.

مثال‌ها (EXAMPLES)

برای ارتقای مقادیر متریک‌های IOPS به ازای هر دیسک به ۶۴ بیتی جهت امکان تجمیع در یک بازه زمانی طولانی به منظور برنامه‌ریزی ظرفیت، یا به این دلیل که PMDA برای صادر کردن شمارنده‌های ۶۴ بیتی تغییر یافته است و ما می‌خواهیم آرشیوهای قدیمی را به گونه‌ای تبدیل کنیم که بتوانند در کنار آرشیوهای جدید پردازش شوند:

metric disk.dev.read { type -> U64 }
metric disk.dev.write { type -> U64 }
metric disk.dev.total { type -> U64 }

نمونه‌های مرتبط با متریک میانگین بار kernel.all.load را می‌توان با قواعد زیر تغییر نام داد و شماره‌گذاری مجدد کرد:

# برای Linux PMDA، متریک kernel.all.load روی
# دامنه نمونه 60.2 تعریف شده است
indom 60.2 {
    inst 1 -> 60 iname "1 minute" -> "60 second"
    inst 5 -> 300 iname "5 minute" -> "300 second"
    inst 15 -> 900 iname "15 minute" -> "900 second"
}

اگر تصمیم بگیریم متریک‌های «proc» را از Linux PMDA جدا کنیم، این کار شامل تغییر شماره دامنه برای PMID این متریک‌ها و دامنه‌های نمونه مرتبط با آن‌ها خواهد بود. قواعد زیر یک آرشیو قدیمی را بازنویسی می‌کنند تا با تغییرات پس از تفکیک PMDA مطابقت داشته باشد:

# تمام متریک‌های proc لینوکس در ۷ کلاستر قرار دارند
metric 60.8.* { pmid -> 123.*.* }
metric 60.9.* { pmid -> 123.*.* }
metric 60.13.* { pmid -> 123.*.* }
metric 60.24.* { pmid -> 123.*.* }
metric 60.31.* { pmid -> 123.*.* }
metric 60.32.* { pmid -> 123.*.* }
metric 60.51.* { pmid -> 123.*.* }
# تنها یک دامنه نمونه برای متریک‌های proc لینوکس وجود دارد
indom 60.9 { indom -> 123.0 }

اگر متریک foo.count_em به عنوان یک «long» بومی صادر شده باشد، ممکن است روی برخی پلتفرم‌ها یک عدد صحیح ۳۲ بیتی و روی پلتفرم‌های دیگر یک عدد صحیح ۶۴ بیتی باشد. بررسی‌های بعدی نشان می‌دهد که مقدار در واقع بدون علامت است، بنابراین قواعد زیر می‌تواند استفاده شود:

metric foo.count_em {
	type if 32 -> U32
	type if 64 -> U64
}

عیب‌یابی (DIAGNOSTICS)

تمام شرایط خطای شناسایی‌شده توسط pmlogrewrite بر روی stderr به همراه توضیحات متنی (اگرچه گاهی مختصر) گزارش می‌شوند.

اگر آرشیو ورودی خراب (corrupted) باشد (این امر در صورتی ممکن است رخ دهد که نمونه pmlogger نویسنده آرشیو ناگهان متوقف شود)، pmlogrewrite موقعیت خرابی در فایل را شناسایی و گزارش می‌کند و هیچ اطلاعات بعدی از آن آرشیو پردازش نخواهد شد.

اگر آرشیو ورودی فاقد هرگونه رکورد آرشیو باشد، هشدار «آرشیو خالی» (empty archive) صادر شده و هیچ پردازشی انجام نمی‌شود.

در صورت بروز هرگونه خطا، pmlogrewrite با وضعیت غیرصفر خارج خواهد شد.

فایل‌ها (FILES)

برای هر یک از آرشیوهای inlog و outlog، چندین فایل فیزیکی استفاده می‌شود:

archive.meta: متادیتا (توضیحات متریک، دامنه‌های نمونه و غیره) برای آرشیو
archive.0: حجم اولیه مقادیر متریک‌ها (حجم‌های بعدی دارای پسوندهای 1، 2، ... هستند).
archive.index: نمایه زمانی (temporal index) برای پشتیبانی از دسترسی تصادفی سریع به سایر فایل‌های درون آرشیو.

محیط 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 استفاده کنید تا فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها را به دست آورید.

گزینه‌های اشکال‌زدایی ویژه pmlogrewrite به شرح زیر هستند:

Option	Description
appl0	خواندن و نوشتن آرشیو برای حجم‌های داده و متادیتا
appl1	تغییرات متادیتا (توصیف‌کننده‌های متریک، دامنه‌های نمونه، متن راهنما، برچسب‌های متریک)
appl2	تغییرات مقدار متریک (pmResult)
appl3	مدیریت -q و توضیح تغییرات مورد نیازی که دلیل عدم خروج سریع هستند
appl4	عیب‌یابی تحلیل‌گر فایل config
appl5	تطبیق regex(7) برای تغییرات مقدار متریک و تغییرات نام نمونه
appl6	اسکنر واژگانی فراخوانی‌شده از تحلیل‌گر فایل config
appl7	عیب‌یابی‌های مربوط به تولید نمایه زمانی (temporal index)

همچنین ببینید (SEE ALSO)

PCPIntro(1), pmlogdump(1), pmlogextract(1), pmlogger(1), pmloglabel(1), pmlogredact(1), pmlogreduce(1), PMAPI(3), pmLookupDesc(3), pmdaInstance(3), scandir(3), tzset(3), LOGARCHIVE(5), PMNS(5), pcp.conf(5), pcp.env(5) و regex(7).