PMLOGEXTRACT(1) General Commands Manual PMLOGEXTRACT(1)

pmlogextract - کاهش حجم، استخراج، الحاق و ادغام آرشیوهای Performance Co-Pilot

pmlogextract [-dfmwxz?] [-c configfile] [-D debug] [-S starttime] [-s samples] [-T endtime] [-V version] [-v volsize] [-Z timezone] input [...] output

pmlogextract یک یا چند آرشیو Performance Co-Pilot (PCP) مشخص‌شده توسط input را می‌خواند و یک آرشیو PCP ادغام‌شده و/یا کاهش‌یافته در output ایجاد می‌کند. هر آرگومان input یا یک نام است یا فهرستی از نام‌های جداشده با کاما، و هر نام، نام یک فایل از یک آرشیو، نام پایه یک آرشیو، یا نام یک دایرکتوری حاوی یک یا چند آرشیو است. ماهیت ادغام توسط تعداد آرشیوهای input کنترل می‌شود، در حالی که ماهیت کاهش حجم داده‌ها توسط آرگومان‌های خط فرمان کنترل می‌شود. آرگومان‌های input باید آرشیوهایی باشند که توسط pmlogger(1) همراه با داده‌های کارایی جمع‌آوری‌شده از همان میزبان ایجاد شده باشند، اما معمولاً در دوره‌های زمانی متفاوت و احتمالاً (هرچند نه معمولاً) با معیارهای کارایی متفاوتی که ثبت شده‌اند.

اگر تنها یک input مشخص شده باشد، رفتار پیش‌فرض صرفاً رونوشت برداشتن از آرشیو PCP ورودی input (با تبدیل احتمالی به نسخه جدیدتری از قالب آرشیو، به -V در زیر مراجعه کنید) در آرشیو PCP خروجی output است. هنگامی که دو یا چند آرشیو PCP به عنوان input مشخص شوند، آرشیوها ادغام (یا الحاق) شده و در output نوشته می‌شوند.

در آرشیو output ممکن است یک رکورد <mark> در زمانی درست پس از پایان هر یک از آرشیوهای input درج شود تا ناپیوستگی زمانی احتمالی میان پایان یک آرشیو input و شروع آرشیو input بعدی را نشان دهد. برای اطلاعات بیشتر به بخش رکوردهای نشانه (MARK RECORDS) در زیر مراجعه کنید. هیچ رکورد <mark> پس از پایان آخرین رکورد (از نظر ترتیب زمانی) از آرشیو(های) input وجود ندارد..SH "گزینه‌ها (OPTIONS)" گزینه‌های موجود خط فرمان عبارتند از:

تنها معیارهای مشخص‌شده در config را از آرشیو(های) PCP input استخراج می‌کند. نحو config پذیرفته‌شده توسط pmlogextract با جزئیات بیشتر در بخش CONFIGURATION FILE SYNTAX شرح داده شده است.
حالت اضطراری (Desperate). به‌طور معمول در صورت بروز یک خطای مهلک، تمام ردپای آرشیو PCP که تا حدی در output نوشته شده است، حذف می‌شود. با گزینهٔ -d، آرشیو output حذف نمی‌شود.
در بیشتر کاربردهای معمول، تمام آرشیوهای input در یک منطقهٔ زمانی جمع‌آوری شده‌اند. اما اگر چنین نباشد، pmlogextract باید یکی از مناطق زمانی آرشیوهای input را برای استفاده به عنوان منطقهٔ زمانی آرشیو output انتخاب کند. پیش‌فرض، استفاده از منطقهٔ زمانی آخرین آرشیو input است. گزینهٔ -f استفاده از منطقهٔ زمانی نخستین آرشیو input را تحمیل می‌کند.
همان‌طور که در بخش MARK RECORDS در ادامه شرح داده شده است، گاهی اوقات می‌توان رکوردهای <mark> را با اطمینان از آرشیو output حذف کرد. اگر گزینهٔ -m مشخص شود، بررسی‌های epilogue و prologue نادیده گرفته می‌شوند و یک رکورد <mark> همواره در انتهای هر آرشیو input (به جز آخرین مورد) درج خواهد شد. این رفتار اولیه و اصلی pmlogextract است.
تعیین آغاز یک پنجرهٔ زمانی برای محدود کردن رکوردهای پردازش‌شده؛ رجوع کنید به PCPIntro(1). همچنین گزینهٔ -w را ببینید.
آرگومان samples تعداد نمونه‌ها (یا رکوردها) را برای نوشتن در output تعیین می‌کند. اگر samples برابر با 0 باشد یا -s مشخص نشده باشد، pmlogextract تا انتهای تمام آرشیوهای input یا تا انتهای پنجرهٔ زمانی مشخص‌شده توسط -T (هر کدام که زودتر فرا برسد) ادامه می‌دهد. گزینهٔ -s در صورت وقوعِ زودتر، گزینهٔ -T را لغو می‌کند (نادیده می‌گیرد).
تعیین پایان یک پنجرهٔ زمانی برای محدود کردن رکوردهای پردازش‌شده؛ رجوع کنید به PCPIntro(1). همچنین گزینهٔ -w را ببینید.
هر آرشیو PCP نسخه‌ای برای قالب رکورد فیزیکی دارد که در حال حاضر 2 یا 3 است. به‌طور پیش‌فرض، آرشیو output با نسخه‌ای برابر با بیشینهٔ نسخهٔ آرشیوهای input ایجاد می‌شود. گزینهٔ -V می‌تواند برای تحمیل صریح نسخه برای output استفاده شود، مشروط بر این که version کوچک‌تر از نسخهٔ آرشیوی نباشد که طبق قاعدهٔ پیش‌فرض انتخاب می‌شد.

برای مثال، تعیین -V 3 می‌تواند برای تولید یک آرشیو output نسخهٔ 3 از آرشیوهای input که ممکن است ترکیبی از نسخهٔ 2 و/یا نسخهٔ 3 باشند، استفاده شود.

آرشیو output بالقوه یک مجموعه دادهٔ چندجلدی است، و گزینهٔ -v باعث می‌شود که pmlogextract پس از رسیدن حجم یک جلد آرشیو به volsize، یک جلد جدید را آغاز کند. اگر volsize یک عدد صحیح باشد، در این صورت حداکثر volsize رکورد در هر جلد نوشته خواهد شد. اگر volsize یک عدد صحیح با پسوند b یا bytes باشد، حداکثر volsize بایت در هر جلد نوشته خواهد شد. سایر واحدهای معتبر اندازهٔ فایل عبارتند از: K، Kb، KiB، Kbyte، Kilobyte برای کیلوبایت و M، Mb، KiB، Mbyte، Megabyte برای مگابایت و G، Gb، GiB، Gbyte، Gigabyte برای گیگابایت. این واحدها می‌توانند به صورت اختیاری دارای پسوند s بوده و از حروف بزرگ یا کوچک تشکیل شوند. به عنوان جایگزین، volsize می‌تواند یک عدد صحیح یا ممیز شناور با پسوند واحد زمانی باشد، همان‌طور که در PCPIntro(1) برای آرگومان interval (در گزینهٔ استاندارد خط فرمان -t در PCP) شرح داده شده است..nf چند مثال از قالب‌های مختلف:
-s 100 -s 100bytes -s 100K -s 100Mb -s 10Gbyte -s 10mins -s 1.5hours

حالت پیش‌فرض برای pmlogextract تولید کمترین تعداد ممکن از جلدها است.

مستقل از هر گزینهٔ -v، هر جلد از یک آرشیو به حداکثر 2^31 بایت محدود شده است، بنابراین pmlogextract پیش از رسیدن به این حد، به‌طور خودکار یک جلد جدید برای آرشیو ایجاد می‌کند.

در مواردی که -S و -T یک بازه زمانی را درون یک روز مشخص می‌کنند، پرچم -w باعث می‌شود که داده‌های درون آن بازه زمانی، برای هر روز موجود در آرشیو استخراج شوند. برای نمونه، گزینه‌های -w -S @11:00 -T @15:00 مشخص می‌کنند که pmlogextract باید تنها رکوردهای آرشیو مربوط به بازه‌های زمانی ۱۱ صبح تا ۳ بعدازظهر در هر روز را شامل شود. هنگامی که از -w استفاده می‌شود، آرشیو output شامل رکوردهای <mark> خواهد بود تا ناپیوستگی زمانی بین پایان یک بازه زمانی و آغاز بازه بعدی را نشان دهد.
انتظار می‌رود متادیتا (نام، PMID، نوع، معناشناسی و واحدها) برای هر سنجه در تمام آرشیو(های) PCP input که آن سنجه در آن‌ها وجود دارد یکسان باشد. در موارد نادر، مانند هنگام توسعه، در کنترل کیفیت (QA) و زمان ارتقای یک PMDA، ممکن است چنین نباشد و pmlogextract مشکل را گزارش کرده و بدون ایجاد آرشیو output، متوقف خواهد شد. این کار به این منظور انجام می‌شود تا مشکل پیش از تلاش مجدد برای ادغام، با pmlogrewrite(1) برطرف گردد. در محیط‌های بدون نظارت (unattended) یا QA، ممکن است ترجیح داده شود که ادغام اجباری شده و سنجه‌های دارای متادیتای ناهمخوان نادیده گرفته شوند. گزینهٔ -x این کار را انجام می‌دهد.
استفاده از timezone هنگام نمایش تاریخ و زمان در پیام‌های تشخیصی. Timezone در قالب متغیر محیطی TZ است، آن‌گونه که در environ(7) شرح داده شده است. پیش‌فرض این است که ابتدا از منطقه زمانی میزبان محلی استفاده شود.
استفاده از منطقه زمانی محلی میزبانی که در آرشیو(های) input آمده است هنگام نمایش تاریخ و زمان در پیام‌های تشخیصی. پیش‌فرض این است که ابتدا از منطقه زمانی میزبان محلی استفاده شود.
-?, --help
نمایش پیام راهنمای استفاده و خروج..SH "ساختار فایل پیکربندی (CONFIGURATION FILE SYNTAX)" فایل configfile شامل معیارهای مورد نظر است - تنها آن معیارهایی (یا نمونه‌هایی) که به طور صریح یا ضمنی در فایل پیکربندی ذکر شده باشند در آرشیو output گنجانده خواهند شد. هر مشخصه باید در یک خط جدید آغاز شود و می‌تواند در فایل پیکربندی شامل چندین خط باشد. نمونه‌ها نیز می‌توانند مشخص شوند، اما اختیاری هستند. قالب هر مشخصه به صورت زیر است: 
        metric
یا
        metric [ instance ... ]

که در آن metric می‌تواند نام یک برگ یا غیربرگ از یک معیار در فضای نام معیارهای کارایی (PMNS، به PMNS(5) مراجعه کنید) باشد. اگر یک metric به یک گرهٔ غیربرگ در PMNS اشاره کند، pmlogextract به صورت بازگشتی در PMNS پایین رفته و تمام معیارهای متناظر با گره‌های برگ فرزند را در بر خواهد گرفت.

نمونه‌ها اختیاری هستند و به صورت فهرستی از شناسه‌های instance جداشده با فاصله (یا کاما) مشخص می‌شوند، در حالی که فهرست در کروشه‌ها محصور شده است. هر شناسهٔ instance می‌تواند یک عدد یا یک رشته (محصور در علامت‌های نقل‌قول تکی یا دوتایی) باشد. شناسه‌های instance عددی، به عنوان شناسه‌های نمونهٔ داخلی فرض می‌شوند، در غیر این صورت مقادیر رشته‌ای به عنوان شناسه‌های نمونهٔ خارجی در نظر گرفته می‌شوند؛ برای اطلاعات بیشتر به pmGetInDom(3) مراجعه کنید. اگر هیچ نمونه‌ای داده نشود، آن‌گاه همهٔ نمونه‌های معیار(های) مربوطه استخراج خواهند شد.

هرگونه فاصلهٔ خالی اضافی نادیده گرفته می‌شود و کامنت‌ها را می‌توان با پیشوند «#» اضافه کرد.

این نمونه‌ای از یک configfile معتبر است:


#
# config file for pmlogextract
#


kernel.all.cpu
kernel.percpu.cpu.sys ["cpu0","cpu1"]
disk.dev ["dks0d1"]

هنگامی که بیش از یک آرشیو input داده‌های کارایی را برای آرشیو output تأمین می‌کنند، ممکن است رکوردهای <mark> برای نشان دادن احتمال ناپیوستگی زمانی در داده‌های کارایی درج شوند.

یک رکورد <mark> شامل یک برچسب زمانی بدون داده‌های کارایی است و برای نشان دادن این استفاده می‌شود که بازه‌ای زمانی در آرشیو PCP وجود دارد که در آن مقدار هیچ‌یک از معیارهای کارایی مشخص نیست، چرا که در طول این دوره هیچ pmlogger(1) فعالی برای جمع‌آوری داده‌های کارایی وجود نداشته است. از آن‌جا که این دوره‌ها اغلب با راه‌اندازی مجدد یک سرویس یا pmcd(1) یا بازراه‌اندازی سیستم همراه‌اند، ممکن است تردید قابل توجهی در مورد تداوم داده‌های کارایی در این بازهٔ زمانی وجود داشته باشد.

بیشتر آرشیوهای کنونی با یک رکورد prologue در ابتدا و یک رکورد epilogue در انتها ایجاد می‌شوند. این رکوردها وضعیت pmcd(1) را در آن زمان مشخص می‌کنند و می‌توانند توسط pmlogextract برای تعیین این موضوع استفاده شوند که هیچ ناپیوستگی‌ای میان پایان یک آرشیو و رکورد خروجی بعدی وجود ندارد و در نتیجه رکورد <mark> را می‌توان با اطمینان از آرشیو output حذف کرد.

دلیل منطقی رکوردهای <mark> را می‌توان با یک مثال نشان داد. یک آرشیو input را در نظر بگیرید که در ساعت 00:10 آغاز شده و در 09:15 همان روز به پایان می‌رسد، و آرشیو input دیگری که در ساعت 09:20 همان روز آغاز شده و در ساعت 00:10 صبح روز بعد پایان می‌یابد. این وضعیت یک حالت بسیار متداول برای آرشیوهایی است که توسط pmlogger_check(1) و pmlogger_daily(1) مدیریت و دوره‌ای (rotate) می‌شوند.

آرشیو output ایجاد شده توسط pmlogextract شامل موارد زیر خواهد بود:
00:10.000    نخستین رکورد از اولین آرشیو ورودی
...
09:15.000    آخرین رکورد از اولین آرشیو ورودی
09:15.001    رکورد <mark>
09:20.000    نخستین رکورد از دومین آرشیو ورودی
...
01:10.000    آخرین رکورد از دومین آرشیو ورودی

بازهٔ زمانی که داده‌های کارایی در آن وجود ندارند، دقیقاً پس از ساعت 09:15 آغاز شده و درست پیش از 09:20 پایان می‌یابد. هنگامی که آرشیو output با هر یک از ابزارهای گزارش‌گیری PCP پردازش می‌شود، رکورد <mark> برای نشان دادن دوره‌ای از داده‌های ناموجود به کار می‌رود. به عنوان مثال با استفاده از آرشیو output فوق، تصور کنید فردی می‌خواهد میانگین نرخ I/O را در فواصل ۳۰ دقیقه‌ای همگام‌شده با ساعت کامل و نیم‌ساعت گزارش کند. معیار شمارندهٔ I/O از نوع شمارنده (counter) است، بنابراین میانگین نرخ I/O نیازمند دو مقدار معتبر از زمان‌های نمونه‌برداری متوالی است. برای تمامی فواصل منتهی به 09:00 مقادیری وجود خواهد داشت، سپس در 09:30 به دلیل رکورد <mark> هیچ مقداری وجود نخواهد داشت، سپس در 10:00 نیز مقداری نخواهد بود زیرا مقدار «قبلی» در 09:30 در دسترس نیست، سپس نرخ دوباره در 10:30 گزارش شده و هر ۳۰ دقیقه تا آخرین مقدار گزارش‌شده در 01:00 ادامه می‌یابد.

وجود رکوردهای <mark> در یک آرشیو PCP را می‌توان با استفاده از pmlogdump(1) تشخیص داد، جایی که یک برچسب زمانی و یادداشت <mark> برای نشان دادن یک رکورد <mark> به کار می‌رود..SH "بررسی‌های متاداده (METADATA CHECKS)" هنگامی که بیش از یک آرشیو input مشخص شده باشد، pmlogextract تعدادی بررسی را انجام می‌دهد تا اطمینان حاصل کند متاداده برای معیارهایی که در بیش از یکی از آرشیوهای input حضور دارند، سازگار است. این بررسی‌ها شامل موارد زیر است:

  • نوع دادهٔ معیار (metric data type) یکسان باشد
  • معناشناسی معیار (metric semantics) یکسان باشد
  • واحدهای سنجش معیار (metric units) یکسان باشند
  • معیار یا همواره مفرد (singular) باشد یا همواره دامنه نمونهٔ (instance domain) یکسانی داشته باشد
  • معیارهای دارای نام یکسان، PMID یکسانی داشته باشند
  • معیارهای دارای PMID یکسان، نام یکسانی داشته باشند

اگر هر یک از این بررسی‌ها با شکست مواجه شود، pmlogextract جزئیات را گزارش کرده و بدون ایجاد آرشیو output متوقف می‌شود.

برای رفع این مغایرت‌های معنایی، پیش از استفاده از pmlogextract، از pmlogrewrite(1) برای تبدیل آرشیوهای input به آرشیوهای معادل با متادادهٔ سازگار استفاده کنید.

برای راهکارهای جایگزینِ رفتار پیش‌فرض در مدیریت خطاها حین بررسی متاداده، به گزینه‌های خط فرمان -x و -d در بالا مراجعه کنید.

معیارهای prologue (شامل pmcd.pmlogger.archive ،pmcd.pmlogger.host و pmcd.pmlogger.port) که در ابتدای آرشیو به‌طور خودکار توسط pmlogger ثبت می‌شوند، ممکن است در آرشیو خروجی تولید شده توسط pmlogextract وجود نداشته باشند. این معیارها تنها زمانی که آرشیو در حال ایجاد است اهمیت دارند، و پس از پایان ضبط هیچ کاربردی نخواهند داشت.

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

اگر یکی از آرشیوهای input فاقد هرگونه رکورد آرشیو باشد، یک هشدار “empty archive” صادر شده و از آن آرشیو صرف‌نظر می‌شود.

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

در صورت تشخیص هرگونه خطا، pmlogextract با وضعیت غیرصفر خارج خواهد شد..SH "فایل‌ها (FILES)" برای هر یک از آرشیوهای input و output، چندین فایل فیزیکی استفاده می‌شود.

متاداده (توضیحات متریک‌ها، دامنه‌های نمونه و غیره) برای آرشیو
جلد اولیه مقادیر متریک‌ها (جلدهای بعدی دارای پسوندهای 1، 2، ... هستند) - برای input این فایل‌ها ممکن است قبلاً با bzip2(1) یا gzip(1) فشرده شده باشند و از این رو ممکن است یک پسوند اضافی .bz2 یا .gz داشته باشند.
فهرست زمانی برای پشتیبانی از دسترسی تصادفی سریع به سایر فایل‌های موجود در آرشیو.

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

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

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

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

گزینه توضیحات
appl0 پیام‌های عیب‌یابی تجزیه‌کننده برای configfile در صورت تعیین -c
appl1 تخصیص‌های حافظه و عملیات‌های reclist
appl2 آزمون‌های پنجره زمانی و پایان فایل
appl3 تصمیم‌گیری‌های نگارش آرشیو ورودی و خروجی
appl4 مدیریت و دستکاری دامنه‌های نمونه
appl5 تعویض جلد خروجی

PCPIntro(1)، pmlc(1)، pmlogdump(1)، pmlogger(1)، pmlogreduce(1)، pmlogrewrite(1)، pcp.conf(5)، pcp.env(5) و PMNS(5).

PCP Performance Co-Pilot