نام (NAME)

pmdumptext - تخلیه معیارهای کارایی در قالب یک جدول ASCII

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

pmdumptext [-CFGHilmMNoruVXz?] [-a archive] [-A align] [-c config] [-d delimiter] [-D debug] [-f format] [-h host] [-n pmnsfile] [-O offset] [-P precision] [-R lines] [-s sample] [-S starttime] [-t interval] [-T endtime] [-U string] [-w width] [-Z timezone] [metric ...]

توضیحات (DESCRIPTION)

دستور pmdumptext مقادیر معیارهای کارایی جمع‌آوری‌شده به صورت زنده یا از مجموعه‌ای از بایگانی‌های Performance Co-Pilot (PCP) را در خروجی نمایش می‌دهد. به طور پیش‌فرض، مقادیر معیارها در ستون‌هایی که با نویسهٔ تب (tab) از هم جدا شده‌اند، به همراه برچسب زمان در ابتدای آن‌ها نمایش داده می‌شوند.

مگر در مواردی که با گزینهٔ -h به یک میزبان دیگر، با گزینهٔ -a به یک یا چند مجموعه بایگانی، یا با یک پیشوند صریح :host یا /archive در metric هدایت شود (برای اطلاعات بیشتر به ادامه مراجعه کنید)، pmdumptext با دیمن گردآورنده معیارهای کارایی (PMCD) در میزبان محلی ارتباط برقرار می‌کند تا اطلاعات مورد نیاز را به دست آورد.

دستور pmdumptext می‌تواند با گزینهٔ -i در حالت تعاملی اجرا شود که مقادیر را در ستون‌هایی با عرض یکسان نمایش می‌دهد. بدون این گزینه، هیچ تلاشی برای هم‌تراز کردن مقادیر انجام نمی‌شود تا خروجی به آسانی توسط برنامه‌های دیگر قابل تجزیه باشد.

قالب‌بندی خروجی را می‌توان با تغییر دقت اعشار مقادیر توسط -P، عرض ستون‌ها با -w، و قالب‌بندی مقادیر با گزینه‌های -G و -F (به ترتیب برای کوتاه‌ترین حالت بین نماد علمی یا ارقام ثابت، و قالب با عرض ثابت) بیشتر کنترل کرد.

به طور پیش‌فرض، pmdumptext مقادیر معیارها را به واحدهای «استاندارد» (canonical) بایت، ثانیه و شمارش مقیاس‌بندی می‌کند. تنها استثنا با گزینهٔ -r است که در آن مقادیر مقیاس‌بندی نمی‌شوند. گزینهٔ -u واحدهای اندازه‌گیری هر معیار را گزارش می‌دهد.

معیارهای (metrics) مورد نظر برای تخلیه می‌توانند در خط فرمان، در یک فایل پیکربندی (config)، یا از طریق ارسال با لوله به pmdumptext در stdin مشخص شوند. یک معیار شامل یک منبع اختیاری (میزبان یا بایگانی)، نام معیار، و بلافاصله پس از نام، یک فهرست اختیاری از نمونه‌ها (instances) است. از علامت دونقطه برای جداسازی نام میزبان از معیار، و از یک اسلش (``/'') برای جداسازی نام بایگانی از معیار استفاده می‌شود. نمونه‌ها درون قلاب [ ] قرار می‌گیرند و در صورتی که بیش از یکی باشند، بین هر نمونه از یک ویرگول انگلیسی استفاده می‌شود. برای مثال، برخی از معیارهای مجاز عبارتند از:

kernel.all.cpu.idle
myhost:kernel.all.cpu.idle[cpu0,cpu3]
/path/to/myarchive/kernel.all.cpu.idle[cpu1]

هنگامی که یک metric فاقد پیشوند :host یا /archive باشد (مانند kernel.all.cpu.idle در بالا)، منبع معیار بر اساس قواعد زیر تعیین می‌شود:

(a): دیمن PMCD روی host برگرفته از گزینهٔ -h در صورت وجود؛ در غیر این صورت
(b): بایگانی archive برگرفته از نخستین گزینهٔ -a در صورت وجود؛ در غیر این صورت
(c): میزبان برگرفته از نخستین metric پیش از این که دارای پیشوند :host باشد در صورت وجود؛ در غیر این صورت
(d): بایگانی برگرفته از نخستین metric پیش از این که دارای پیشوند /archive باشد در صورت وجود؛ در غیر این صورت
(e): دیمن PMCD روی میزبان محلی، که معادل local::metric است.

قالب یک metric به تفصیل در PCPIntro(1) در بخش PERFORMANCE METRIC SPECIFICATIONS شرح داده شده است. یک مقدار نرمال‌سازی (normalization) می‌تواند به صورت اختیاری پس از نام معیار در یک فایل config یا در stdin قرار گیرد. مقدار معیار با این عدد مقیاس‌بندی خواهد شد. برای مثال، اگر فایل‌سیستم ``/dev/root'' ظرفیتی معادل 1965437 بایت داشته باشد، درصد استفاده‌شده از فایل‌سیستم را می‌توان با این config تخلیه کرد:

filesys.used[/dev/root] 19654.37

نمی‌توان از مقدار نرمال‌سازی برای metrics تعیین‌شده به عنوان آرگومان‌های خط فرمان استفاده کرد.

نیازی نیست که نام معیار حتماً یک گره برگ (leaf node) در فضای نام معیارهای کارایی (PMNS) باشد، مگر زمانی که یک یا چند نمونه (instance) مشخص شده باشد. برای مثال، برای تخلیهٔ تمامی معیارهای فایل‌سیستم، تنها تعیین filesys کافی است تا مقادیر filesys.capacity، filesys.used، filesys.free و غیره تخلیه شوند..SH "گزینه‌ها (OPTIONS)" گزینه‌های خط فرمان -A (یا --align)، -O (یا --origin)، -S (یا --start) و -T (یا --finish) تراز، افست، زمان شروع و پایان را هنگام مصورسازی معیارها از بایگانی‌ها کنترل می‌کنند. این گزینه‌ها میان بیشتر ابزارهای Performance Co-Pilot مشترک هستند و به‌طور کامل در PCPIntro(1) شرح داده شده‌اند.

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

-a archive, --archive=archive: مشخص‌کننده archive (بایگانی) تاریخی است که معیارها می‌توانند برای یک میزبان مشخص از آن دریافت شوند. archive مسیر کامل به یک فایل بایگانی، یا نام یک دایرکتوری حاوی بایگانی‌ها، یا نام پایه (basename) یک بایگانی است - که همگی پیش‌تر توسط pmlogger(1) ایجاد شده‌اند. می‌توان چندین مجموعه از بایگانی‌ها را (جداشده با کاما یا در گزینه‌های -a مختلف) از میزبان‌های متفاوت مشخص کرد، اما برای هر میزبان تنها یک مجموعه از بایگانی‌ها مجاز است. هر معیاری که با یک میزبان یا بایگانی خاص مرتبط نباشد، از اولین بایگانی به‌عنوان منبع خود استفاده خواهد کرد.
-c config, --config=config: اگر هیچ metrics (معیاری) در خط فرمان مشخص نشده باشد، می‌توان از یک فایل config برای تعیین metrics مورد نظر جهت استخراج استفاده کرد. برخلاف metrics خط فرمان، در اینجا هر معیار می‌تواند با یک مقدار نرمال‌سازی دنبال شود. خطوط خالی و خطوطی که با «#» آغاز می‌شوند نادیده گرفته می‌شوند.
-C, --check: خروج پیش از استخراج مقادیر، اما پس از تجزیه معیارها. اگر -m، -l، -N و/یا -u مشخص شده باشند، معیارها، نمونه‌ها (instances)، مقادیر نرمال و واحدها فهرست می‌شوند.
-d delimiter, --delimiter=delimiter: تعیین delimiter (جداکننده‌ای) که هر ستون از خروجی را تفکیک می‌کند. delimiter تنها می‌تواند یک نویسه منفرد باشد.
-f format, --time-format=format: استفاده از رشته format برای قالب‌بندی برچسب زمانی همراه با هر مجموعه از مقادیر. نحو این رشته مشابه ساختار شرح داده شده در strftime(3) است. یک رشته format خالی (مانند '') برچسب‌های زمانی را از خروجی حذف خواهد کرد.
-F, --fixed: تولید خروجی مقادیر در قالبی با عرض ثابت ۶ نویسه. اعداد مثبت به‌صورت dd.ddu و اعداد منفی به‌صورت [-]d.ddu نمایش داده می‌شوند. ضریب پسوندی می‌تواند مقادیر K(10^3)، M(10^6)، G(10^9) و T(10^12) را داشته باشد. برای مثال، مقدار ۴۵۶۷ حتی اگر واحد معیار بایت باشد، به‌صورت 4.57K نمایش داده می‌شود.
-G, --scientific: نمایش مقادیر با استفاده از کوتاه‌ترین حالت بین نماد علمی یا نمایش ده‌دهی (اعشاری).
-h host, --host=host: دریافت معیارهای کارایی از pmcd(1) روی host، به‌جای localhost پیش‌فرض.
-H, --headers: نمایش تمام سرآیندها پیش از استخراج مقادیر معیارها. این گزینه معادل -lmNu است.
-i, --interactive: نمایش داده‌ها در ستون‌هایی با عرض ثابت با استفاده از مقادیر با عرض ثابت (ببینید -F) به‌طوری که خوانایی انسانی داشته باشد. این گزینه را نمی‌توان همراه با -P استفاده کرد، زیرا مقادیر ممیز ثابت دارای عرض ثابت نیستند. این گزینه همچنین بر خروجی گزینه‌های -m و -u اثر می‌گذارد، چرا که نام معیارها، نمونه‌ها و واحدها کوتاه خواهند شد.
-l, --source: نمایش منبع معیارها. در حالت تعاملی، میزبان معیارها نمایش داده می‌شود. در حالت غیرتعاملی، این گزینه منبع معیارها را همراه با نام معیار نمایش می‌دهد، حتی اگر -m مشخص نشده باشد.
-m, --metrics: نمایش نام معیارها پیش از مقادیر آن‌ها. منبع و واحدهای معیارها نیز می‌توانند به‌ترتیب با گزینه‌های -l و -u در خروجی درج شوند. اگر در حالت تعاملی باشد، نام معیارها ممکن است کوتاه شود، و نام نمونه‌ها نیز در صورت لزوم، در خط بعدی کوتاه می‌شوند.
-M: نمایش شماره ستون و نام کامل معیارها پیش از استخراج هر مقداری. اگر پرچم -l نیز مشخص شده باشد، منبع معیارها نیز نمایش داده می‌شود.
-n pmnsfile, --namespace=pmnsfile: بارگذاری یک PMNS محلی جایگزین از فایل pmnsfile.
-o, --offset: هنگامی که یک برچسب زمانی گزارش می‌شود (یعنی مگر اینکه یک رشته قالب خالی با گزینه -f مشخص شده باشد)، برچسب زمانی با افست بر حسب ثانیه از شروع مجموعه بایگانی‌ها یا آغاز اجرای pmdumptext پیشوندگذاری می‌شود.
-N: نمایش فاکتورهای نرمال‌سازی پیش از مقادیر معیارها.
-p precision, --precision=precision: تنظیم دقت ( precision) مقادیر. این گزینه را نمی‌توان همراه با -F استفاده کرد، زیرا دقت در آن ثابت است. دقت پیش‌فرض ۳ است.
-r, --raw: نمایش مقادیر خام معیارها؛ بدون تبدیل شمارنده‌ها به نرخ و بدون تغییر مقیاس مقادیر به واحدهای استاندارد (canonical). این گزینه همچنین باعث می‌شود pmdumptext مقادیر نرمال‌سازی را برای هر معیار نادیده بگیرد.
-R lines, --repeat=lines: تکرار سرآیند به ازای هر lines خط از خروجی. این گزینه در حالت تعاملی و هنگام استفاده از پنجره‌های گرافیکی، برای جلوگیری از پیمایش سرآیند به خارج از بافر پنجره، و همچنین تراز مجدد سرآیند در صورت تغییر اندازه پنجره مفید است.
-s samples, --samples=samples: pmdumptext پس از این تعداد نمونه خاتمه می‌یابد.
-t interval, --interval=interval: گزینه interval از نحو توصیف‌شده در PCPIntro(1) پیروی می‌کند، و در ساده‌ترین شکل می‌تواند یک عدد صحیح بدون علامت باشد (واحد ضمنی در این حالت ثانیه است). فاصله زمانی پیش‌فرض ۱ ثانیه است..TP -u, --units واحدهای متریک‌ها را پیش از نخستین مقادیر نمایش می‌دهد، اما در صورتی که -m نیز مشخص شده باشد، پس از نام‌های متریک قرار می‌گیرد.
-U string, --unavailable=string: خروجی را در زمانی که مقادیر در دسترس نیستند به string تغییر می‌دهد. رشته پیش‌فرض ``?'' است.
-V, --version: شماره نسخه را نمایش داده و خارج می‌شود.
-w width, --widthfR=width: عرض ستون خروجی را تعیین می‌کند. رشته‌ها تا این عرض کوتاه می‌شوند، و اگر width بزرگ‌تر از ۵ باشد ممکن است پسوند ``...'' به انتهای آن‌ها افزوده شود.
-X, --extended: شماره ستون و نام کامل متریک‌ها را، یک مورد در هر خط، هم پیش از تخلیه اولین مجموعه مقادیر و هم هر بار با تکرار سربرگ، در خروجی نمایش می‌دهد.
-z, --hostzone: از منطقه زمانی محلی میزبانی که منبع متریک‌های کارایی است، همان‌طور که توسط گزینه‌های -h یا اولین گزینه -a مشخص شده است، استفاده می‌کند. پیش‌فرض استفاده از منطقه زمانی میزبان محلی است.
-Z timezone, --timezone=timezone: از timezone برای تاریخ و زمان استفاده می‌کند. Timezone در قالب متغیر محیطی TZ است، همان‌گونه که در environ(7) شرح داده شده است.
-?, --help: پیام راهنمای نحوه استفاده را نمایش داده و خارج می‌شود.

منابع چندگانه (MULTIPLE SOURCES)

دستور pmdumptext از تخلیه متریک‌ها از چندین میزبان یا مجموعه‌ای از بایگانی‌ها پشتیبانی می‌کند. متریک‌های فهرست‌شده در خط فرمان یا در فایل config می‌توانند منبع مشخصی نداشته باشند یا از منابع متفاوتی بیایند.

با این حال، هنگامی که بایگانی‌ها در خط فرمان (-a) و/یا در فایل پیکربندی مشخص شده باشند، محدودیت‌هایی اعمال می‌شود. نخست، برای هر میزبان تنها یک مجموعه بایگانی می‌تواند وجود داشته باشد. دوم، میزبان‌های هر متریکی با منبع میزبان باید با میزبانِ یک مجموعه بایگانی، چه در خط فرمان و چه پیش‌تر به عنوان منبع متریکی دیگر، مطابقت داشته باشد.

گزینه‌های -a و -h نمی‌توانند هم‌زمان با یکدیگر استفاده شوند.

تبدیل واحد (UNIT CONVERSION)

تمامی متریک‌هایی که معنای شمارنده دارند، به‌طور خودکار به نرخ در بازه زمانی نمونه‌برداری تبدیل می‌شوند. در حالت تعاملی، pmdumptext همچنین واحدهای برخی از متریک‌ها را تغییر می‌دهد تا درک آن‌ها آسان‌تر شود:

o: تمامی متریک‌های با واحدهای فضا (بایت تا ترابایت) به بایت مقیاس‌بندی می‌شوند. توجه داشته باشید که ۱۰۲۴ بایت به صورت 1.02K نمایش داده خواهد شد، نه 1.00K.
o: متریک‌هایی که شمارنده‌هایی با واحدهای زمانی هستند (نانوثانیه تا ساعت)، میزان بهره‌وری زمانی را در طول بازه نمونه‌برداری نشان می‌دهند. رشته واحد چنین متریک‌هایی به ``Time Utilization'' تغییر یافته یا به صورت خلاصه به ``util'' تبدیل می‌شود و مقادیر آن‌ها در بازه صفر تا یک نرمال‌سازی می‌شوند.

مثال‌ها (EXAMPLES)

o برای بررسی بار کاری روی دو میزبان foo و bar به‌طور هم‌زمان:

$ pmdumptext -il 'foo:kernel.all.load[1]' 'bar:kernel.all.load[1]'
             Source        foo     bar
Wed Jul 30 11:37:53      0.309   0.409
Wed Jul 30 11:37:54      0.309   0.409
Wed Jul 30 11:37:55      0.309   0.409

o برای نمایش میزان استفاده از حافظه روی یک میزبان دوردست به نام bong با یک برچسب زمانی ساده‌تر:

$ pmdumptext -imu -h bong -f '%H:%M:%S' mem.util
  Metric        kernel  fs_ctl  _dirty  _clean    free    user
   Units             b       b       b       b       b       b
09:32:28         8.98M   0.97M   0.00    3.90M   7.13M  46.13M
09:32:29         8.99M   0.98M   0.00    5.71M   5.39M  46.03M
09:32:30         8.99M   1.07M   0.00    5.81M   4.55M  46.69M
09:32:31         9.03M   1.16M   0.00    6.45M   3.48M  47.00M
09:32:32         9.09M   1.18M  20.48K   6.23M   3.29M  47.30M

o برای تخلیه تمامی متریک‌های جمع‌آوری‌شده در یک بایگانی با بازه زمانی ۳۰ ثانیه به یک فایل، جهت پردازش توسط ابزاری دیگر:

$ pminfo -a archive | pmdumptext -t 30s -m -a archive > outfile

$PCP_VAR_DIR/pmns/*: فایل‌های پیش‌فرض مشخصات PMNS

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

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

گزینه	توضیحات
appl0	عیب‌یابی تفصیلی برای معیارها، منبع و منطقه زمانی آن‌ها، متادیتا، نرمال‌سازی واحدها، قالب خروجی و غیره.

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

PCPIntro(1)، pmcd(1)، pmchart(1)، pmlogger(1)، pmrep(1)، PMAPI(3)، strftime(3) و environ(7).