'\"macro stdmacro
.\"
.\" Copyright (c) 2010 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH SHEET2PCP 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
sheet2pcp \- وارد کردن داده‌های صفحه‌گسترده و ایجاد بایگانی PCP
.SH "خلاصه دستور (SYNOPSIS)"
\fBsheet2pcp\fR
[\fB\-h\fR \fIhost\fR]
[\fB\-V\fR \fIversion\fR]
[\fB\-Z\fR \fItimezone\fR]
\fIinfile\fR \fImapfile\fR \fIoutfile\fR
.SH "توضیحات (DESCRIPTION)"
.de SAMPLE
.RS 2n
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..
ابزار \fBsheet2pcp\fR برای خواندن یک صفحه‌گسترده حاوی داده (\fIinfile\fR)
و تبدیل آن به یک بایگانی Performance
Co-Pilot (\s-1PCP\s0) با نام پایه \fIoutfile\fR در نظر گرفته شده است.
.PP
صفحه‌گسترده ورودی می‌تواند در هر یک از قالب‌های متداول باشد، مشروط بر آنکه
ماژول‌های Perl مربوطه نصب شده باشند (بخش \fB\s-1هشدارها (CAVEATS)\s0\fR
در زیر را ببینید). صفحه‌گسترده باید «نرمال‌سازی» شده باشد،
به‌گونه‌ای که هر سطر حاوی داده‌هایی برای یک بازه زمانی یکسان باشد، و یکی
از ستون‌ها حاوی تاریخ و زمان برای داده‌های موجود در هر
سطر باشد.
.PP
بایگانی \s-1PCP\s0 حاصل می‌تواند همراه با تمام ابزارهای کلاینت \s-1PCP\s0
برای رسم نمودار زیرمجموعه‌هایی از داده‌ها با استفاده از \fBpmchart\fR(1)،
انجام خلاصه‌سازی و گزارش‌گیری داده‌ها، فیلتر کردن با
موتور استنتاج \s-1PCP\s0 به نام \fBpmie\fR(1) و غیره به کار گرفته شود.
.PP
فایل \fImapfile\fR فرآیند وارد کردن را کنترل کرده و نگاشت
داده‌ها از ستون‌های صفحه‌گسترده بر مدل داده‌ای \s-1PCP\s0 را تعریف می‌کند. این فایل
با فرمت \s-1XML\s0 نوشته شده و از ساختار نحوی تعریف‌شده در بخش
\fB\s-1پیکربندی نگاشت (MAPPING CONFIGURATION)\s0\fR در زیر پیروی می‌کند.
.PP
مجموعه‌ای از فایل‌های فیزیکی با پیشوند \fIoutfile\fR ایجاد خواهند شد.
این فایل‌ها عبارتند از: \fIoutfile\fR\fB.0\fR (داده‌های کارایی)،
\fIoutfile\fR\fB.meta\fR (متاداده‌ای که داده‌های کارایی را توصیف می‌کند) و
\fIoutfile\fR\fB.index\fR (یک نمایه زمانی برای بهبود کارایی عملیات بازپخش
در بایگانی). اگر هر یک از این فایل‌ها از قبل وجود داشته باشد،
آن‌گاه \fBsheet2pcp\fR آن‌ها را بازنویسی \fBنخواهد کرد\fR و با یک پیام خطا
خارج خواهد شد.
.PP
گزینه \fB\-h\fR جایگزینی برای ویژگی
\fBhostname\fR در عنصر \fB<sheet>\fR در \fImapfile\fR
است که در زیر شرح داده شده است. اگر هر دو مشخص شده باشند، مقدار درج‌شده در \fImapfile\fR
استفاده می‌شود.
.PP
گزینه
.B \-V
نسخه بایگانی PCP خروجی را مشخص می‌کند.
به‌طور پیش‌فرض، نسخه بایگانی
.B $PCP_ARCHIVE_VERSION
(که در نگارش‌های کنونی PCP برابر ۳ است)
استفاده می‌شود، و تنها مقادیر
پشتیبانی‌شده کنونی برای
.I version
برابر ۲ یا ۳ هستند.
.PP
گزینه \fB\-Z\fR جایگزینی برای ویژگی
\fBtimezone\fR در عنصر \fB<sheet>\fR در \fImapfile\fR
است که در زیر شرح داده شده است. اگر هر دو مشخص شده باشند، مقدار درج‌شده در \fImapfile\fR
استفاده می‌شود.
.PP
دستور \fBsheet2pcp\fR یک اسکریپت Perl است که از پوشش پرل PCP::LogImport
بر روی کتابخانه \fIlibpcp_import\fR در \s-1PCP\s0
استفاده می‌کند، و می‌تواند به عنوان نمونه‌ای برای توسعه ابزارهای
جدید جهت وارد کردن انواع دیگر داده‌های کارایی و ایجاد بایگانی‌های \s-1PCP\s0 به کار رود.
.SH "پیکربندی نگاشت (MAPPING CONFIGURATION)"
.IX Header "MAPPING CONFIGURATION"
فایل \fImapfile\fR حاوی مشخصات در قالب استاندارد \s-1XML\s0 است.
.PP
تمام مشخصات در یک عنصر \fB<sheet>\fR ... \fB</sheet>\fR
قرار می‌گیرند.
تگ \fBsheet\fR از ویژگی‌های اختیاری زیر پشتیبانی می‌کند:
.IP "\fBheading\fR" 10
.IX Item "heading"
تعداد سطرهای سربرگ را که باید در ابتدای صفحه‌گسترده پیش از پردازش داده‌ها نادیده گرفته شوند،
مشخص می‌کند.
مثال: heading="1".
.IP "\fBhostname\fR" 10
.IX Item "hostname"
تنظیم نام میزبان مبدا در بایگانی \s-1PCP\s0 (حالت
پیش‌فرض استفاده از نام میزبان سیستم محلی است).
مثال: hostname="some.where.com".
.IP "\fBtimezone\fR" 10
.IX Item "timezone"
تنظیم منطقه زمانی مبدا در بایگانی \s-1PCP\s0 (حالت
پیش‌فرض استفاده از \s-1UTC\s0 است). منطقه زمانی باید در
قالب +HHMM (برای ساعت و دقیقه شرق \s-1UTC\s0) یا \-HHMM (برای ساعت
و دقیقه غرب \s-1UTC\s0) باشد. به‌ویژه توجه فرمایید که \fBهیچ‌یک\fR از قالب‌های \fBzoneinfo\fR
(موسوم به Olson)، مانند Europe/Paris، یا قالب پوزیکس \fB\s-1TZ\s0\fR، مانند
\s-1EST+5\s0 مجاز نیستند.
مثال: timezone="+1100".
.IP "\fBdatefmt\fR" 10
.IX Item "datefmt"
قالب تاریخ وارد شده از صفحه‌گسترده می‌تواند به صورت الحاق
مقدارهایی مشخص شود که
ترتیب فیلدهای سال (\fBY\fR)، ماه (\fBM\fR) و روز (\fBD\fR) را در یک تاریخ تعیین می‌کنند.
حالت‌های پشتیبانی‌شده عبارتند از \fB\s-1DMY\s0\fR (پیش‌فرض)،
\fB\s-1MDY\s0\fR و \fB\s-1YMD\s0\fR.
مثال: datefmt="\s-1YMD\s0".
.PP
یک عنصر \fB<sheet>\fR حاوی
یک یا چند مشخصه سنجه به
فرم \fB<metric>\fR\fImetricname\fR\fB</metric>\fR است. تگ \fBmetric\fR
از ویژگی‌های اختیاری زیر پشتیبانی می‌کند:
.IP "\fBpmid\fR" 10
.IX Item "pmid"
شناسه سنجه‌های کارایی (\s-1PMID\s0)، که به صورت ۳ عدد
جداشده با نقطه (.) مشخص می‌شود تا
فیلدهای \fBdomain\fR، \fBcluster\fR و \fBitem\fR از \s-1PMID\s0 را تنظیم کند؛ برای جزئیات
بیشتر درباره PMIDها به \fB\s-1PMNS\s0\fR(5) مراجعه کنید. در صورت حذف، \s-1PMID\s0 به‌طور خودکار
توسط \fBpmiAddMetric\fR(3) اختصاص داده می‌شود.
مقدار \fB\s-1PM_ID_NULL\s0\fR می‌تواند برای تعیین صریح
رفتار پیش‌فرض استفاده شود.
مثال‌ها: pmid="60.0.2"، pmid="\s-1PM_ID_NULL\s0".
.IP "\fBindom\fR" 10
.IX Item "indom"
هر سنجه ممکن است دارای یک یا چند مقدار باشد. اگر یک سنجه \fBهمیشه\fR
یک مقدار داشته باشد، منفرد است و دامنه نمونه (Instance Domain) باید روی
\fB\s-1PM_INDOM_NULL\s0\fR تنظیم شود.
در غیر این صورت، \fBindom\fR باید به صورت ۲ عدد جداشده با یک نقطه (.) مشخص شود
تا فیلدهای \fBdomain\fR و \fBordinal\fR از دامنه نمونه تنظیم شوند.
مثال‌ها: indom="\s-1PM_INDOM_NULL\s0"، indom="60.3"، indom="\s-1PMI_DOMAIN\s0.4".
.sp
بیش از یک سنجه می‌توانند دامنه نمونه یکسانی را به اشتراک بگذارند، مشروط بر آنکه مقادیر
آن سنجه‌ها بر روی مجموعه‌های مشابهی از نمونه‌ها تعریف شده باشند؛ مانند تمام سنجه‌های مربوط به هر رابط
شبکه. رویه معمول این است که فیلد \fBdomain\fR برای \fBpmid\fR و \fBindom\fR
یکسان باشد؛ در صورتی که ویژگی \fBpmid\fR وجود نداشته باشد،
آن‌گاه فیلد \fBdomain\fR برای \fBindom\fR باید دامنه رزرو شده
\fB\s-1PMI_DOMAIN\s0\fR باشد.
.sp
اگر ویژگی \fBindom\fR مشخص نشود، دامنه نمونه پیش‌فرض برای
سنجه \fB\s-1PM_INDOM_NULL\s0\fR خواهد بود.
.IP "\fBunits\fR" 10
.IX Item "units"
مقیاس و بُعد مقادیر سنجه در راستای محورهای فضا، زمان
و شمارش (رویدادها، پیام‌ها، بسته‌ها و غیره) با یک ۶\-تایی (6-tuple) مشخص می‌شود.
این مقادیر به تابع \fBpmiUnits\fR(3) ارسال می‌شوند تا یک
ساختار \fIpmUnits\fR ایجاد شود. برای شرح کامل
تمام فیلدهای این ساختار به \fBpmLookupDesc\fR(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" (میکروثانیه بر رویداد).
.IP "\fBtype\fR" 10
.IX Item "type"
نوع داده سنجه را مشخص می‌کند.
برای شرح کامل مقادیر ممکن برای نوع داده به \fBpmLookupDesc\fR(3)
مراجعه کنید؛ مقدار پیش‌فرض \fB\s-1PM_TYPE_FLOAT\s0\fR است.
مثال‌ها: type="\s-1PM_TYPE_32\s0"، type="\s-1PM_TYPE_U64\s0"، type="\s-1PM_TYPE_STRING\s0".
.IP "\fBsem\fR" 10
.IX Item "sem"
معناشناسی (semantics) سنجه را تعریف می‌کند.
برای شرح کامل مقادیر ممکن به \fBpmLookupDesc\fR(3)
مراجعه کنید؛ مقدار پیش‌فرض \fB\s-1PM_SEM_INSTANT\s0\fR است.
مثال‌ها: sem="\s-1PM_SEM_COUNTER\s0"، type="\s-1PM_SEM_DISCRETE\s0".
.PP
سایر مشخصات، ستون‌های داده را \fBبه ترتیب\fR با استفاده از
\fBدقیقاً\fR یک عنصر \fB<datetime>\fR\fB</datetime>\fR،
یک یا چند عنصر \fB<data>\fR\fImetricspec\fR\fB</data>\fR
و
یک یا چند عنصر \fB<skip>\fR\fB</skip>\fR تعریف می‌کنند.
.PP
عنصر \fB<datetime>\fR ستونی را مشخص می‌کند که در آن تاریخ و زمان جهت
تشکیل برچسب زمانی در بایگانی \s-1PCP\s0 برای تمام داده‌های موجود در
هر سطر از بایگانی \s-1PCP\s0 قرار دارد.
.PP
برای عنصر \fB<data>\fR،
یک \fImetricspec\fR
شامل یک نام سنجه (همان‌طور که در یک عنصر قبلی \fB<metric>\fR
تعریف شده است)، و در صورت تمایل نام یک نمونه محصور در کروشه است؛
مانند <data>hinv.ncpu</data>، <data>kernel.all.load[1 minute]</data>.
.PP
تگ \fBskip\fR ستونی را مشخص می‌کند که هنگام آماده‌سازی
داده‌ها برای بایگانی \s-1PCP\s0 باید نادیده گرفته شود.
.PP
ترتیب عناصر \fB<datetime>\fR، \fB<data>\fR و
\fB<skip>\fR با ترتیب ستون‌ها در صفحه‌گسترده
مطابقت دارد. اگر تعداد عناصر با تعداد ستون‌ها
یکسان نباشد، یک هشدار صادر می‌شود و عناصر یا ستون‌های اضافی،
هیچ مقدار سنجه‌ای در بایگانی خروجی تولید نمی‌کنند.
.SS "\s-1مثال (EXAMPLE)\s0"
.IX Subsection "EXAMPLE"
فایل \fImapfile\fR ...
.PP
.SAMPLE
    <?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>
.ESAMPLE
.PP
می‌تواند برای صفحه‌گسترده‌ای به کار رود که چند سطر اول آن به شکل زیر است:
.PP
.SAMPLE
    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
.ESAMPLE
.SH "هشدارها (CAVEATS)"
.IX Header "CAVEATS"
تنها برگه اول از \fIinfile\fR پردازش خواهد شد.
.PP
برای قالب‌های گوناگون صفحه‌گسترده، ماژول‌های Perl اضافی باید نصب شوند؛
اگرچه این ماژول‌ها در زمان اجرا بررسی می‌شوند و بنابراین تنها ماژول‌های مورد نیاز برای
انواع مشخصی از صفحه‌گسترده‌ها که مایل به پردازش آن‌ها هستید باید نصب باشند:
.IP "\fB*.csv\fR" 6
.IX Item "*.csv"
صفحه‌گسترده‌ها در قالب مقادیر جداشده با کاما (\s-1CSV\s0) به \fBText::CSV_XS\fR(3pm) نیاز دارند.
.IP "\fB*.sxc\fR یا \fB*.ods\fR" 6
.IX Item "*.sxc or *.ods"
اسناد OpenOffice به \fBSpreadsheet::ReadSXC\fR(3pm) نیاز دارند که خود به
\fBArchive::Zip\fR(3pm) وابسته است.
.IP "\fB*.xls\fR" 6
.IX Item "*.xls"
اسناد کلاسیک Microsoft Office به \fBSpreadsheet::ParseExcel\fR(3pm) نیاز دارند،
که خود به \fBOLE::Storage_Lite\fR(3pm) وابسته است.
.IP "\fB*.xlsx\fR" 6
.IX Item "*.xlsx"
اسناد Microsoft OpenXML به \fBSpreadsheet::XLSX\fR(3pm) نیاز دارند. به‌نظر می‌رسد \fBsheet2pcp\fR
با اسناد OpenXML که از OpenOffice ذخیره شده‌اند کار نمی‌کند.
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای مقداردهی و پیکربندی
نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، فایل
\fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP می‌تواند برای مشخص کردن یک فایل پیکربندی
جایگزین، همان‌طور که در \fBpcp.conf\fP(5) شرح داده شده، استفاده شود.
.PP
برای متغیرهای محیطی موثر بر ابزارهای PCP، به \fBpmGetOptions\fP(3) مراجعه کنید.
.SH "همچنین ببینید (SEE ALSO)"
.BR pmchart (1),
.BR pmie (1),
.BR pmlogger (1),
.BR sed (1),
.BR pmiAddMetric (3),
.BR pmLookupDesc (3),
.BR pmiUnits (3),
.BR Archive::Zip (3pm),
.BR Date::Format (3pm),
.BR Date::Parse (3pm),
.BR PCP::LogImport (3pm),
.BR OLE::Storage_Lite (3pm),
.BR Spreadsheet::ParseExcel (3pm),
.BR Spreadsheet::ReadSXC (3pm),
.BR Spreadsheet::XLSX (3pm),
.BR Text::CSV_XS (3pm),
.BR XML::TokeParser (3pm)
و
.BR LOGIMPORT (3).

.\" control lines for scripts/man-spell
.\" +ok+ CSV_XS DMY EST HHMM MDY OLE OpenXML
.\" +ok+ ParseExcel ReadSXC Storage_Lite SysTime TokeParser UTF XLSX YMD
.\" +ok+ aka ar csv datefmt datetime hinv metricname metricspec ncpu ods
.\" +ok+ sem sxc sys xls