نام (NAME)

pmview - فایل پیکربندی و توصیف صحنه سه‌بعدی برای pmview در PCP

توضیحات (DESCRIPTION)

این صفحه راهنما نسخه ۲.۱ قالب فایل پیکربندی pmview (1) را شرح می‌دهد.

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

کنترل‌های زمان، تمامی میزبان‌های مشخص‌شده در خط فرمان و فایل پیکربندی را در فهرست منطقه زمانی فهرست خواهند کرد (ببینید pmtime(1)).

قالب فایل پیکربندی بر پایه یک شبکه دوبعدی (grid) است که می‌تواند شامل انواع میله‌ها (bars)، پشته‌ها (stacks)، پیوندها (links)، لوله‌ها (pipes)، برچسب‌ها (labels) و شبکه‌های دیگر باشد. شبکه‌ها اندازه هر ستون و سطر را برای تطبیق با اندازه بزرگ‌ترین آیتم موجود در آن ستون یا سطر تغییر می‌دهند. یک فایل پیکربندی که تنها شامل یک شیء است نیازی به شبکه ندارد. فایل پیکربندی pmview با یک سرآیند شناسایی در اولین خط غیرتوضیحی آغاز می‌شود:

pmview Version 2.1 [command_line]

گزینه اختیاری command_line در صورتی که فایل پیکربندی توسط ابزار دیگری ایجاد شده باشد، باید خط فرمانی باشد که ابزار با آن اجرا شده است. این ویژگی برای برنامه‌هایی مفید است که قرار است پس از خروج کاربر در حالی که pmview همچنان در حال اجرا بوده است، در ورود بعدی کاربر به سیستم به طور خودکار دوباره راه‌اندازی شوند. باید دقت شود که دستور مشخص‌شده یک مسیر کامل باشد یا در متغیر PATH موجود هنگام ورود به سیستم یافت شود.

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

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

color

رنگ باید یکی از حدود ۲۰ نام رنگ Qt باشد (به کلاس QColor در https://doc.qt.io/qt-5/qcolor.html#predefined-colors مراجعه کنید)، یا یک مقدار رنگ هگزادسیمال HTML (محصور در علامت نقل‌قول، مانند "#ff6347")، یا سه مقدار حقیقی نرمال‌شده real نشان‌دهنده اشباع رنگ‌های قرمز، سبز و آبی باشد. برای مثال، رنگ‌های زیر یکسان هستند:

red
"#ff0000"
1.0 0.0 0.0

int

یک عدد صحیح.

metric

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

برای مثال، برخی از معیارهای مجاز عبارتند از:

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

برای کمک به فرآیند تطبیق نام نمونه‌ها، دو مقایسه دیگر علاوه بر مقایسه رشته‌ای ساده انجام می‌شود. اگر نام نمونه شامل فاصله باشد، تنها کلمه اول در نام نمونه برای تطبیق با نمونه کافی است، با این فرض که کلمه اول یکتا باشد. اگر کلمه اول یکتا نباشد، تنها اولین نمونه منطبق انتخاب خواهد شد. مقایسه دوم زمانی رخ می‌دهد که کلمه اول عددی با صفرهای ابتدایی باشد؛ پیش از مقایسه مجدد کلمه اول، تمام صفرهای ابتدایی نادیده گرفته می‌شوند. این کار اجازه می‌دهد شناسه‌های فرآیند (PID) استفاده‌شده در معیارهای proc بدون مشخص کردن کل نام نمونه به آسانی تطبیق داده شوند. برای مثال، برای مصورسازی زمان کاربر و سیستم در init از این مشخصات معیار استفاده کنید:

proc.psusage.utime[1]	1000
proc.psusage.stime[1]	1000

name

نامی برای یک شیء که ممکن است بعداً در فایل پیکربندی به آن ارجاع داده شود. نام‌ها باید یک کلمه منفرد متشکل از نویسه‌های الفبایی‌عددی، خط زیر (underscore)، خط تیره (dash) و دونقطه باشند. توصیه می‌شود که نام‌ها با خط زیر آغاز نشوند زیرا ممکن است به عنوان کلمه کلیدی تفسیر شوند.

pos

این موقعیت شیء در شبکه (grid) است. نحو تعیین موقعیت به صورت زیر است:

[ [x z] [ [width depth] [alignment] ] ]

x

مختصات افقی (از چپ به راست) شیء، با شروع از 0. مقدار پیش‌فرض x برابر 0 است.

z

مختصات عمودی (از بالا به پایین) شیء، با شروع از 0. مقدار پیش‌فرض z برابر 0 است.

width

تعداد ستون‌های اشغال‌شده توسط شیء. مقدار پیش‌فرض width برابر 1 است.

depth

تعداد سطرهای اشغال‌شده توسط شیء. مقدار پیش‌فرض depth برابر 1 است.

alignment

لبه یا گوشه‌ای که شیء با آن تراز می‌شود. ترازهای ممکن عبارتند از: north، south، east، west، northeast، northwest، southeast، southwest و center. اختصارهایی مانند se و SE نیز پذیرفته می‌شوند. تراز پیش‌فرض center است.

اندازه یک شیء ممکن است نامشخص باشد زیرا تعداد نمونه‌ها برای برخی معیارها بسته به میزبان‌ها و پیکربندی‌های PMDA متفاوت خواهد بود. بنابراین، موقعیت شیء می‌تواند برای مشخص کردن اندازه احتمالی شیء به کار رود تا موقعیت اشیاء مجاور به طور مناسب تنظیم شود.

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

0 5

شیء در موقعیت شبکه 0,5 متمرکز است و ۱ خانه شبکه را اشغال می‌کند.

1 2 north

شیء با لبه شمالی موقعیت 1,2 تراز شده و ۱ خانه شبکه را اشغال می‌کند.

2 2 2 1 east

شیء با لبه شرقی موقعیت 3,2 تراز شده و ۲ خانه شبکه (2,2 و 3,2) را اشغال می‌کند.

string

یک رشته، دنباله‌ای از نویسه‌ها است که در علامت نقل‌قول دوتایی (double quotes) محصور شده‌اند. یک رشته نباید شامل خطوط جدید یا نقل‌قول‌های دوتایی اسکیپ‌شده باشد.

چندین پارامتر وجود دارند که ممکن است بر اندازه، شکل و رنگ اشیاء هنگام نمایش تأثیر بگذارند. دامنه اثر این پارامترها به گونه‌ای است که تنها اشیای تعریف‌شده پس از خود در همان دامنه را تغییر می‌دهند. بنابراین، تنظیمات پارامترها در بالای فایل پیکربندی بر کل صحنه تأثیر می‌گذارند، مگر اینکه بعداً در فایل تغییر یابند. بیشتر این پارامترها منبع (resource) نیز محسوب می‌شوند.

_barLength int

طول ضلع بلوک‌های _bar و _stack. مقدار پیش‌فرض 28 است.

_barHeight int

بیشینه ارتفاع بلوک‌های _bar و _stack. مقدار پیش‌فرض 80 است.

_baseColor color

رنگ صفحات پایه _bar، _grid و _stack. مقدار پیش‌فرض "#262626" (یعنی gray15) است.

_baseHeight int

ارتفاع صفحات پایه _bar، _grid و _stack. مقدار پیش‌فرض 2 است.

_gapWidth int

فاصله میان بلوک‌ها در شیء _bar در محور X. مقدار پیش‌فرض 8 است.

_gapDepth int

فاصله میان بلوک‌ها در شیء _bar در محور Z. مقدار پیش‌فرض 8 است.

_gapLabel int

فاصله بین پایه یک شیء _bar و برچسب‌های معیار یا نمونه. مقدار پیش‌فرض 6 است.

_gridWidth int

حداقل پهنای یک ستون در _grid. مقدار پیش‌فرض 20 است.

_gridDepth int

حداقل عمق یک سطر در _grid. مقدار پیش‌فرض 20 است.

_labelMargin int

حاشیه اطراف یک شیء _label. مقدار پیش‌فرض 5 است.

_labelColor color

رنگ برچسب‌های _label و _bar. مقدار پیش‌فرض سفید (white) است.

_marginWidth int

پهنای اضافی صفحه پایه _bar، _grid و _stack فراتر از اشیاء موجود روی صفحه. مقدار پیش‌فرض 8 است.

_marginDepth int

عمق اضافی صفحه پایه _bar، _grid و _stack فراتر از اشیاء موجود روی صفحه. مقدار پیش‌فرض 8 است.

_pipeLength int

طول کل یک _pipe. مقدار پیش‌فرض برابر با مقدار _barHeight است.

_scale real

مقیاس اعمال‌شده به کل صحنه. این پارامتر نمی‌تواند درون هیچ شیئی استفاده شود و فقط در بالای فایل پیکربندی مجاز است. مقدار پیش‌فرض 1.0 است.

برای ساده‌سازی تعیین رنگ‌ها، می‌توان از _colorList و _colorScale برای تعریف رنگ‌های شیئی که معیارهایی به آن وابسته است (مانند _bar، _stack یا _pipe) استفاده کرد. یک فهرست رنگ می‌تواند درون یک شیء تعریف شود یا اینکه نام‌گذاری شده و در بالای فایل پیکربندی تعریف گردد. سپس می‌توان در چندین شیء به یک فهرست رنگ نام‌گذاری‌شده ارجاع داد:

_colorList name ( color [color...] )

رنگ‌های color را به فهرست رنگ name مرتبط می‌کند. تخصیص رنگ‌ها به بلوک‌ها بستگی به نوع شیء دارد. برای مثال، فهرست رنگی به نام foo دارای یک رنگ یکسان است که سه بار تکرار شده است:

_colorList foo ( red "#ff0000" 1.0 0.0 0.0 )

_colorScale name color ( color real [color real...] )

رنگ‌های color و مقادیر حقیقی real را به فهرست رنگ name مرتبط می‌کند. رنگ اولیه color رنگ پیش‌فرض شیء است. هنگامی که مقدار نرمال‌شده شیء برابر یا بیشتر از هر مقدار real باشد، شیء تغییر رنگ داده و به رنگ‌های دیگر تبدیل می‌شود. بنابراین، هر مقدار real باید بزرگ‌تر از مقدار real پیشین باشد و در محدوده 0.0 تا 1.0 قرار گیرد. این مقیاس رنگ به آرامی از آبی به قرمز تغییر می‌کند:

_colorScale coldToHot blue ( "#7f00ff" 0.3
                             purple 0.6
                             "#ff007f" 0.8
                             red 0.95)

انواع مختلفی از اشیاء وجود دارند که می‌توانند در یک صحنه pmview یافت شوند: _bar، _stack، _pipe، _grid، _link و _label. همچنین _xing وجود دارد که نوع خاصی از _link است. اشیای _bar، _stack و _pipe توسط مقادیر معیارها مدوله می‌شوند، _label یک متن ثابت است، _link و _xing اتصالات متقابل هستند و _grid ظرفی برای اشیاء (از جمله سایر اشیای _grid) است که چیدمان صحنه را کنترل می‌کند. شیء _grid تنها در صورتی مورد نیاز است که دو یا چند شیء در صحنه وجود داشته باشند.

اشیای _bar، _grid و _stack می‌توانند صفحات پایه داشته باشند که نقطه مرجعی برای بلوک‌ها هنگام تغییر ارتفاع فراهم می‌کنند. در صورت فعال بودن _show، می‌توان با دستور زیر یک برچسب روی صفحه پایه شیء اعمال کرد:

_baseLabel name|string

دستور _baseLabel باید درون دامنه شیء مربوطه (_bar، _grid یا _stack) استفاده شود. اولین نویسه‌های «\n» در رشته با یک خط جدید جایگزین می‌شوند. نویسه‌های بعدی «\n» نادیده گرفته خواهند شد.

برای معتبر بودن یک صحنه، باید حداقل یک شیء مدوله‌شونده در آن وجود داشته باشد.

اشیاء به شرح زیر تعریف می‌شوند:

_bar [options] ( [metric-list] [color-list] [label-list] )

شیء _bar نمایانگر مجموعه‌ای از بلوک‌ها است. تعداد بلوک‌ها به تعداد معیارها و نمونه‌های معیارهای اختصاص‌یافته به شیء بستگی دارد. به طور پیش‌فرض، بلوک‌ها با تغییر ارتفاع هر بلوک مدوله می‌شوند. در روش جایگزین، بلوک‌ها می‌توانند با تغییر رنگ، یا هم ارتفاع و هم رنگ مدوله شوند. هر رنگ در color-list به یک معیار اختصاص می‌یابد؛ بنابراین چندین نمونه از یک معیار یکسان دارای رنگ یکسانی خواهند بود. گزینه‌های options که می‌توانند به شیء _bar داده شوند عبارتند از:

_bar _hide _cylinder ( ... )

_metrics ( metric real [string] [metric real [string]...] )

_colorList name
_colorList ( color [color...] )
_colorScale name
_colorScale color ( color real [color real...] )

_metriclabels [_away|_towards] ( name|string [name|string...] )
_instlabels [_away|_towards] ( name|string
[name|string...] )

_grid [pos] [_show|_hide] ( objects )

شیء _grid یک ظرف برای اشیاء، از جمله سایر اشیای _grid، است. سطرها و ستون‌های شیء _grid به اندازه بزرگ‌ترین شیء موجود در آن سطر یا ستون تغییر اندازه می‌دهند. اگر یک شیء چندین سطر و/یا ستون را در بر بگیرد، آن سطرها و ستون‌ها ممکن است برای دربرگرفتن شیء تا حدی تغییر اندازه دهند. با این حال، تغییر اندازه سطرها و ستون‌ها برای اشیایی که چندین سطر و ستون را اشغال می‌کنند، پس از تغییر اندازه اشیایی که تنها یک مربع شبکه را اشغال می‌کنند رخ می‌دهد.

تداخل بین اشیایی که خانه‌های یکسانی را اشغال می‌کنند به عنوان پیام خطا گزارش شده و شیء بعدی نادیده گرفته خواهد شد.

گزینه‌های شیء _grid موقعیت (pos) شیء _grid را در _grid والد کنترل می‌کنند، و مشخص می‌سازند که آیا صفحه پایه _grid نمایش داده شود (_show) یا پنهان باشد (_hide). به طور پیش‌فرض، صفحه پایه پنهان است.

پارامترهای شرح داده‌شده در بالا می‌توانند درون پرانتزهای یک شیء _grid مشخص شوند، با این حال آن‌ها تنها روی اشیای درون آن _grid اعمال می‌شوند، نه روی خود _grid. برای اینکه پارامتری روی یک شیء _grid اعمال شود، باید پیش از اعلان شیء _grid مشخص گردد.

_label [options] string

شیء _label محتوای string را در موقعیت، جهت‌گیری و اندازه مشخص‌شده در options رسم می‌کند:

_link pos [string]

شیء _link یک «لوله» گرد افقی مستقیم یا L-شکل رسم می‌کند که قطر آن برابر با ۸۰٪ مقدار _baseHeight در _grid دربرگیرنده است. ویژگی‌های این شیء توسط گزینه‌ها تعریف می‌شوند:

_pipe pos ( [metric-list] [color-list] [tag] )

شیء _pipe نمایانگر مجموعه‌ای از استوانه‌ها است که روی یکدیگر قرار گرفته و به موازات صفحه پایه جهت‌گیری شده‌اند. قطر یک _pipe برابر با ۸۰٪ مقدار _baseHeight است. تعداد بلوک‌ها بستگی به تعداد نمونه‌های معیار در metric-list دارد. رنگ‌های موجود در color-list به نوبت به هر استوانه در _pipe اختصاص می‌یابند. طول _pipe توسط _pipeLength تعیین می‌شود.

metric-list

فهرست معیارهای _pipe شامل فهرستی از نام‌های معیار و مقادیر نرمال‌سازی است:

_metrics ( metric real [metric real...] )

color-list

فهرست رنگ‌های _pipe می‌تواند یک فهرست رنگ نام‌گذاری‌شده باشد که پیش‌تر تعریف شده است، یا یک فهرست رنگ بی‌نام:

_colorList name
_colorList ( color [color...] )

tag

یک _pipe می‌تواند دارای یک برچسب متنی (tag) برای بلوک پرکننده (بلوک غیرمتحرک در انتهای دیگر لوله) باشد که وقتی نشانگر ماوس روی آن انتهای لوله قرار گیرد در پنجره متنی نمایش داده خواهد شد.

_pipeTag name|string

_stack [options] ( [metric-list] [color-list] [label] )

شیء _stack نمایانگر مجموعه‌ای از بلوک‌ها است که به صورت عمودی روی یکدیگر قرار گرفته‌اند. تعداد بلوک‌ها بستگی به تعداد نمونه‌های معیار در metric-list دارد. رنگ‌های موجود در color-list به هر بلوک در _stack اختصاص می‌یابند. به طور پیش‌فرض، ارتفاع _stack برابر با مجموع ارتفاع هر بلوک خواهد بود. گزینه‌های options که می‌توانند به شیء _stack داده شوند عبارتند از:

_stack 1 1 _north _utilmod ( ... )

_metrics ( metric real [metric real...] )

_colorList name
_colorList ( color [color...] )

_stackLabel name|string

_xing col row columns rows dir1 ... dir4

شیء _xing نوع ویژه‌ای از پیوند است که برای رسم یک جفت پیوند متقاطع به کار می‌رود. برای القای این برداشت بصری که پیوندها به هم وصل نمی‌شوند، یکی از پیوندها به عنوان یک استوانه «شکسته» رسم می‌شود. col و row موقعیت را روی شبکه دربرگیرنده تعریف می‌کنند. columns و rows اندازه کادر احاطه‌کننده (bounding box) را تعیین می‌کنند. نقاط پایانی استوانه‌های متقاطع دقیقاً در مرکز خانه‌های گوشه‌ای کادر احاطه‌کننده قرار می‌گیرند و از چهار استوانه کوچک یا تکه‌لوله (stub) برای اتصال پیرامون کادر احاطه‌کننده به نقاط پایانی روی استوانه‌های متقاطع استفاده می‌شود. چهار مقدار dir جهت‌گیری این تکه‌لوله‌ها را مشخص می‌کنند، که از گوشه بالا سمت چپ _xing شروع شده و در جهت عقربه‌های ساعت پیش می‌روند، به گونه‌ای که تکه‌لوله‌های مربوطه برای اتصال نقطه قطب‌نما به مرکز سلول استفاده می‌شوند (مثال را ببینید).

مثال (EXAMPLE)

این مثال ساده استفاده از پارامترها و انواع مختلف اشیاء را نشان می‌دهد:

pmview Version 2.1
# Use a lighter grey for the base planes
_baseColor "#7f7f7f"
# Define colors for CPU object
_colorList cpu ( blue2 red2 yellow2 cyan2 green2 )
# The top grid object, but hide it from view
_grid _hide (
# Show the current load in a bar object
   _bar 0 0 (
       _baseLabel "Load averages over a\n1, 5 and 15 minute interval"
       _metrics (
		kernel.all.load[1] 1 "1"
		kernel.all.load[5] 1 "5"
		kernel.all.load[15] 1 "15"
	)
	_colorList ( blue blue blue )
    )
# Add a label below the load bars
    _label 0 1 "Load"
# Change the color of the base plane for later objects
    _baseColor "#fba2f5" # pink
# Show the CPU usage over all CPUs in a utilization stack
    _stack 2 0 _south _utilmod (
	_baseLabel "CPU Utilization over all CPUs"
	_metrics (
		kernel.all.cpu.user 1000
		kernel.all.cpu.sys 1000
		kernel.all.cpu.intr 1000
		kernel.all.cpu.wait.total 1000
		kernel.all.cpu.idle 1000
	)
	_colorList cpu
    )
# Add a label below the CPU stack
    _label 2 1 "CPU"
# Create a separate grid for links and pipes
    _marginWidth 1
    _marginDepth 1
    _gridSpace  12
    _grid 0 3 5 4 _hide (
	_pipeLength 12
	_baseHeight 12
	# Add  a pipe and a link with western orientation
	_pipe 0 0 west (
	    _pipeTag "West pipe"
	    _metrics (
		kernel.all.cpu.user 1000
		kernel.all.cpu.sys 1000
		kernel.all.cpu.idle 1000
	    )
	    _colorList cpu
	)
	_link 0 2 west "West link"
	# Add xing
	_xing 1 0 3 3 west east east west
	# Add a link and a pipe with eastern orientation
	_pipe 4 0 east (
	    _pipeTag "East Pipe"
	    _metrics (
		kernel.all.cpu.user 1000
		kernel.all.cpu.sys 1000
		kernel.all.cpu.idle 1000
	    )
	    _colorList cpu
	)
	_link 4 2 east "East link"
    )
)

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

pmview(1).