SHEET2PCP(1) General Commands Manual SHEET2PCP(1)

sheet2pcp - وارد کردن داده‌های صفحه‌گسترده و ایجاد بایگانی PCP

sheet2pcp [-h host] [-V version] [-Z timezone] infile mapfile outfile

ابزار sheet2pcp برای خواندن یک صفحه‌گسترده حاوی داده (infile) و تبدیل آن به یک بایگانی Performance Co-Pilot (PCP) با نام پایه outfile در نظر گرفته شده است.

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

بایگانی PCP حاصل می‌تواند همراه با تمام ابزارهای کلاینت PCP برای رسم نمودار زیرمجموعه‌هایی از داده‌ها با استفاده از pmchart(1)، انجام خلاصه‌سازی و گزارش‌گیری داده‌ها، فیلتر کردن با موتور استنتاج PCP به نام pmie(1) و غیره به کار گرفته شود.

فایل mapfile فرآیند وارد کردن را کنترل کرده و نگاشت داده‌ها از ستون‌های صفحه‌گسترده بر مدل داده‌ای PCP را تعریف می‌کند. این فایل با فرمت XML نوشته شده و از ساختار نحوی تعریف‌شده در بخش پیکربندی نگاشت (MAPPING CONFIGURATION) در زیر پیروی می‌کند.

مجموعه‌ای از فایل‌های فیزیکی با پیشوند outfile ایجاد خواهند شد. این فایل‌ها عبارتند از: outfile.0 (داده‌های کارایی)، outfile.meta (متاداده‌ای که داده‌های کارایی را توصیف می‌کند) و outfile.index (یک نمایه زمانی برای بهبود کارایی عملیات بازپخش در بایگانی). اگر هر یک از این فایل‌ها از قبل وجود داشته باشد، آن‌گاه sheet2pcp آن‌ها را بازنویسی نخواهد کرد و با یک پیام خطا خارج خواهد شد.

گزینه -h جایگزینی برای ویژگی hostname در عنصر <sheet> در mapfile است که در زیر شرح داده شده است. اگر هر دو مشخص شده باشند، مقدار درج‌شده در mapfile استفاده می‌شود.

گزینه -V نسخه بایگانی PCP خروجی را مشخص می‌کند. به‌طور پیش‌فرض، نسخه بایگانی $PCP_ARCHIVE_VERSION (که در نگارش‌های کنونی PCP برابر ۳ است) استفاده می‌شود، و تنها مقادیر پشتیبانی‌شده کنونی برای version برابر ۲ یا ۳ هستند.

گزینه -Z جایگزینی برای ویژگی timezone در عنصر <sheet> در mapfile است که در زیر شرح داده شده است. اگر هر دو مشخص شده باشند، مقدار درج‌شده در mapfile استفاده می‌شود.

دستور sheet2pcp یک اسکریپت Perl است که از پوشش پرل PCP::LogImport بر روی کتابخانه libpcp_import در PCP استفاده می‌کند، و می‌تواند به عنوان نمونه‌ای برای توسعه ابزارهای جدید جهت وارد کردن انواع دیگر داده‌های کارایی و ایجاد بایگانی‌های PCP به کار رود.

فایل mapfile حاوی مشخصات در قالب استاندارد XML است.

تمام مشخصات در یک عنصر <sheet> ... </sheet> قرار می‌گیرند. تگ sheet از ویژگی‌های اختیاری زیر پشتیبانی می‌کند:

تعداد سطرهای سربرگ را که باید در ابتدای صفحه‌گسترده پیش از پردازش داده‌ها نادیده گرفته شوند، مشخص می‌کند. مثال: heading="1".
تنظیم نام میزبان مبدا در بایگانی PCP (حالت پیش‌فرض استفاده از نام میزبان سیستم محلی است). مثال: hostname="some.where.com".
تنظیم منطقه زمانی مبدا در بایگانی PCP (حالت پیش‌فرض استفاده از UTC است). منطقه زمانی باید در قالب +HHMM (برای ساعت و دقیقه شرق UTC) یا -HHMM (برای ساعت و دقیقه غرب UTC) باشد. به‌ویژه توجه فرمایید که هیچ‌یک از قالب‌های zoneinfo (موسوم به Olson)، مانند Europe/Paris، یا قالب پوزیکس TZ، مانند EST+5 مجاز نیستند. مثال: timezone="+1100".
قالب تاریخ وارد شده از صفحه‌گسترده می‌تواند به صورت الحاق مقدارهایی مشخص شود که ترتیب فیلدهای سال (Y)، ماه (M) و روز (D) را در یک تاریخ تعیین می‌کنند. حالت‌های پشتیبانی‌شده عبارتند از DMY (پیش‌فرض)، MDY و YMD. مثال: datefmt="YMD".

یک عنصر <sheet> حاوی یک یا چند مشخصه سنجه به فرم <metric>metricname</metric> است. تگ metric از ویژگی‌های اختیاری زیر پشتیبانی می‌کند:

شناسه سنجه‌های کارایی (PMID)، که به صورت ۳ عدد جداشده با نقطه (.) مشخص می‌شود تا فیلدهای domain، cluster و item از PMID را تنظیم کند؛ برای جزئیات بیشتر درباره PMIDها به PMNS(5) مراجعه کنید. در صورت حذف، PMID به‌طور خودکار توسط pmiAddMetric(3) اختصاص داده می‌شود. مقدار PM_ID_NULL می‌تواند برای تعیین صریح رفتار پیش‌فرض استفاده شود. مثال‌ها: pmid="60.0.2"، pmid="PM_ID_NULL".
هر سنجه ممکن است دارای یک یا چند مقدار باشد. اگر یک سنجه همیشه یک مقدار داشته باشد، منفرد است و دامنه نمونه (Instance Domain) باید روی PM_INDOM_NULL تنظیم شود. در غیر این صورت، indom باید به صورت ۲ عدد جداشده با یک نقطه (.) مشخص شود تا فیلدهای domain و ordinal از دامنه نمونه تنظیم شوند. مثال‌ها: indom="PM_INDOM_NULL"، indom="60.3"، indom="PMI_DOMAIN.4".

بیش از یک سنجه می‌توانند دامنه نمونه یکسانی را به اشتراک بگذارند، مشروط بر آنکه مقادیر آن سنجه‌ها بر روی مجموعه‌های مشابهی از نمونه‌ها تعریف شده باشند؛ مانند تمام سنجه‌های مربوط به هر رابط شبکه. رویه معمول این است که فیلد domain برای pmid و indom یکسان باشد؛ در صورتی که ویژگی pmid وجود نداشته باشد، آن‌گاه فیلد domain برای indom باید دامنه رزرو شده PMI_DOMAIN باشد.

اگر ویژگی indom مشخص نشود، دامنه نمونه پیش‌فرض برای سنجه PM_INDOM_NULL خواهد بود.

مقیاس و بُعد مقادیر سنجه در راستای محورهای فضا، زمان و شمارش (رویدادها، پیام‌ها، بسته‌ها و غیره) با یک ۶-تایی (6-tuple) مشخص می‌شود. این مقادیر به تابع pmiUnits(3) ارسال می‌شوند تا یک ساختار pmUnits ایجاد شود. برای شرح کامل تمام فیلدهای این ساختار به pmLookupDesc(3) مراجعه کنید. حالت پیش‌فرض این است که هیچ مقیاس یا بُعدی به سنجه اختصاص داده نشود، یعنی units="0,0,0,0,0,0". مثال‌ها: units="0,1,0,0,PM_TIME_MSEC,0" (میلی‌ثانیه)، units="1,-1,0,PM_SPACE_MBYTE,PM_TIME_SEC,0" (مگابایت بر ثانیه)، units="0,1,-1,0,PM_TIME_USEC,PM_COUNT_ONE" (میکروثانیه بر رویداد).
نوع داده سنجه را مشخص می‌کند. برای شرح کامل مقادیر ممکن برای نوع داده به pmLookupDesc(3) مراجعه کنید؛ مقدار پیش‌فرض PM_TYPE_FLOAT است. مثال‌ها: type="PM_TYPE_32"، type="PM_TYPE_U64"، type="PM_TYPE_STRING".
معناشناسی (semantics) سنجه را تعریف می‌کند. برای شرح کامل مقادیر ممکن به pmLookupDesc(3) مراجعه کنید؛ مقدار پیش‌فرض PM_SEM_INSTANT است. مثال‌ها: sem="PM_SEM_COUNTER"، type="PM_SEM_DISCRETE".

سایر مشخصات، ستون‌های داده را به ترتیب با استفاده از دقیقاً یک عنصر <datetime></datetime>، یک یا چند عنصر <data>metricspec</data> و یک یا چند عنصر <skip></skip> تعریف می‌کنند.

عنصر <datetime> ستونی را مشخص می‌کند که در آن تاریخ و زمان جهت تشکیل برچسب زمانی در بایگانی PCP برای تمام داده‌های موجود در هر سطر از بایگانی PCP قرار دارد.

برای عنصر <data>، یک metricspec شامل یک نام سنجه (همان‌طور که در یک عنصر قبلی <metric> تعریف شده است)، و در صورت تمایل نام یک نمونه محصور در کروشه است؛ مانند <data>hinv.ncpu</data>، <data>kernel.all.load[1 minute]</data>.

تگ skip ستونی را مشخص می‌کند که هنگام آماده‌سازی داده‌ها برای بایگانی PCP باید نادیده گرفته شود.

ترتیب عناصر <datetime>، <data> و <skip> با ترتیب ستون‌ها در صفحه‌گسترده مطابقت دارد. اگر تعداد عناصر با تعداد ستون‌ها یکسان نباشد، یک هشدار صادر می‌شود و عناصر یا ستون‌های اضافی، هیچ مقدار سنجه‌ای در بایگانی خروجی تولید نمی‌کنند.

فایل mapfile ...

<?xml version="1.0" encoding="UTF-8"?>
<sheet heading="1">
    <!-- simple example -->
    <metric pmid="60.0.2" indom="60.0" units="0,1,0,0,PM_TIME_MSEC,0"
        type="PM_TYPE_U64" sem="PM_SEM_COUNTER">
    kernel.percpu.cpu.sys</metric>
    <datetime></datetime>
    <skip></skip>
    <data>kernel.percpu.cpu.sys[cpu0]</data>
    <data>kernel.percpu.cpu.sys[cpu1]</data>
</sheet>

می‌تواند برای صفحه‌گسترده‌ای به کار رود که چند سطر اول آن به شکل زیر است:

Date;"Status";"SysTime - 0";"SysTime - 1";
26/01/2001 14:05:22;"Some Busy";0.750;0.133
26/01/2001 14:05:37;"OK";0.150;0.273
26/01/2001 14:05:52;"All Busy";0.733;0.653

تنها برگه اول از infile پردازش خواهد شد.

برای قالب‌های گوناگون صفحه‌گسترده، ماژول‌های Perl اضافی باید نصب شوند؛ اگرچه این ماژول‌ها در زمان اجرا بررسی می‌شوند و بنابراین تنها ماژول‌های مورد نیاز برای انواع مشخصی از صفحه‌گسترده‌ها که مایل به پردازش آن‌ها هستید باید نصب باشند:

*.csv
صفحه‌گسترده‌ها در قالب مقادیر جداشده با کاما (CSV) به Text::CSV_XS(3pm) نیاز دارند.
*.sxc یا *.ods
اسناد OpenOffice به Spreadsheet::ReadSXC(3pm) نیاز دارند که خود به Archive::Zip(3pm) وابسته است.
*.xls
اسناد کلاسیک Microsoft Office به Spreadsheet::ParseExcel(3pm) نیاز دارند، که خود به OLE::Storage_Lite(3pm) وابسته است.
*.xlsx
اسناد Microsoft OpenXML به Spreadsheet::XLSX(3pm) نیاز دارند. به‌نظر می‌رسد sheet2pcp با اسناد OpenXML که از OpenOffice ذخیره شده‌اند کار نمی‌کند.

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

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

pmchart(1), pmie(1), pmlogger(1), sed(1), pmiAddMetric(3), pmLookupDesc(3), pmiUnits(3), Archive::Zip(3pm), Date::Format(3pm), Date::Parse(3pm), PCP::LogImport(3pm), OLE::Storage_Lite(3pm), Spreadsheet::ParseExcel(3pm), Spreadsheet::ReadSXC(3pm), Spreadsheet::XLSX(3pm), Text::CSV_XS(3pm), XML::TokeParser(3pm) و LOGIMPORT(3).

PCP Performance Co-Pilot