DBPMDA(1) General Commands Manual DBPMDA(1)

dbpmda - اشکال‌زدای PMDAهای سامانه Performance Co-Pilot

dbpmda [-D debug] [-efiv?] [-n pmnsfile] [-q timeout] [-U username]

dbpmda یک واسط تعاملی برای بررسی و مدیریت تعاملات میان یک عامل دامنه معیارهای کارایی (PMDA(3)) و دیمن جمع‌آوری معیارهای کارایی (pmcd(1)) است. این ابزار امکان اتصال، مقداردهی اولیه و اجرای آزمایشی PMDAها را جهت سنجش صحت عملکرد آن‌ها فراهم می‌آورد.

dbpmda دستورها را به‌صورت تعاملی از کاربر درخواست می‌کند که بسیاری از آن‌ها واحدهای داده پروتکل (PDUها) را که ممکن است توسط یک فرایند pmcd(1) ارسال شوند، شبیه‌سازی می‌نمایند. پس از اجرای dbpmda، دستور help را برای دریافت فهرستی از دستورهای موجود وارد کنید. بخش مثال‌ها در ادامه، یک نشست کاری با استفاده از dbpmda را برای آزمایش یک PMDA شرح می‌دهد.

به‌منظور ساده‌سازی آزمایش‌های مکرر یک PMDA، فایل .dbpmdarc در دایرکتوری کاری جاری می‌تواند حاوی فهرستی از دستورهایی باشد که هنگام راه‌اندازی توسط dbpmda پیش از درخواست تعاملی دستورها از کاربر اجرا می‌شوند. هنگام پردازش فایل .dbpmdarc، حالت تعاملی و بازتاب دستورها (echoing) فعال شده و سپس در انتهای فایل .dbpmdarc به حالت اولیه بازنشانی می‌شوند (گزینه‌های خط فرمان -i و -e در ادامه را ببینید).

گزینه خط فرمان -f از پردازش فایل .dbpmdarc (در صورت وجود) در زمان راه‌اندازی جلوگیری می‌کند.

اگر سیستم از readline(3) پشتیبانی کند، در صورت دریافت ورودی از یک دستگاه tty از آن برای خواندن دستورها استفاده خواهد شد؛ بنابراین قابلیت‌های تاریخچه و ویرایش خط فرمان در دسترس خواهد بود.

از آنجا که هنگام استفاده از dbpmda (در مقایسه با pmcd(1)) هیچ محدودیت زمانی (timeout) برای یک PMDA وجود ندارد، پس از اتصال فرایند PMDA به dbpmda، می‌توان از یک اشکال‌زدای دیگر مانند gdb(1) روی فرایند PMDA استفاده کرد..SH "گزینه‌ها (OPTIONS)" گزینه‌های موجود برای خط فرمان عبارتند از:

انعکاس ورودی در stdout. این گزینه زمانی مفید است که ورودی از یک فایل تغییر مسیر داده شده باشد.
عدم پردازش فایل .dbpmdarc.
شبیه‌سازی رفتار تعاملی و اعلان برای دستورهای جدید، حتی اگر ورودی استاندارد یک دستگاه tty نباشد.
بارگذاری یک فضای نام سنجه‌های عملکردی (PMNS(5)) جایگزین از فایل pmnsfile.
پروتکل تبادل نسخه بین pmcd و عامل (جدید در PCP 2.0 - معرفی‌شده برای فراهم کردن سازگاری رو به عقب) از این مهلت زمانی استفاده می‌کند تا مشخص کند dbpmda چه مدت باید منتظر بماند پیش از آنکه فرض کند هیچ پاسخی مبنی بر نسخه از طرف عامل ارسال نمی‌شود. اگر این مهلت زمانی به پایان برسد، فرض می‌شود عامل از نوعی است که پروتکل PCP 2.0 را درک نمی‌کند. فاصله مهلت زمانی پیش‌فرض سه ثانیه است، اما گزینه -q امکان تعیین یک مهلت زمانی جایگزین (که باید بزرگ‌تر از صفر باشد) را فراهم می‌کند. واحد زمان ثانیه است.
حساب کاربری که dbpmda تحت آن اجرا می‌شود.
هنگام اجرای dbpmda تحت نظارت valgrind(1) جهت دسته‌بندی و اولویت‌بندی مشکلات در یک DSO PMDA مفید است. اگر گزینه -v استفاده شود، آنگاه dbpmda پیش از خروج dlclose(3) را فراخوانی نخواهد کرد؛ این امر به valgrind(1) اجازه می‌دهد هنگام گزارش‌دهی به جدول نمادهای DSO PMDA دسترسی داشته باشد که اشکال‌زدایی را بسیار ساده‌تر می‌کند.
-?, --help
نمایش پیام راهنمای استفاده و خروج.

در زیر یک نشست dbpmda با استفاده از PMDAی simple آمده است. از یک فایل .dbpmdarc جهت تنظیم گزینه اشکال‌زدایی، باز کردن PMDA و نمایش وضعیت فعلی اشکال‌زدا استفاده شده است:

$ cat .dbpmdarc
debug libpmda
open dso pmda_simple.so simple_init 253
status

هنگامی که dbpmda اجرا می‌شود، دستورهای درون فایل .dbpmdarc ابتدا اجرا می‌شوند:

$ dbpmda
.dbpmdarc> debug libpmda
.dbpmdarc> open dso pmda_simple.so simple_init 253
[Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: Metric 0.0.1(1) matched to indom 253.0(0)
[Fri Sep 19 10:19:55] dbpmda(11651) Debug: pmdaInit: PMDA simple DSO: help file $PCP_PMDAS_DIR/simple/help opened
[Fri Sep 19 10:19:55] dbpmda(11651) Info: name        = simple DSO
[Fri Sep 19 10:19:55] dbpmda(11651) Info: domain      = 253
[Fri Sep 19 10:19:55] dbpmda(11651) Info: num metrics = 4
[Fri Sep 19 10:19:55] dbpmda(11651) Info: num indom   = 1
[Fri Sep 19 10:19:55] dbpmda(11651) Info: direct map  = 1
.dbpmdarc> status
Namespace:              (default)
PMDA:                   ./pmda_simple.so
Connection:             dso
DSO Interface Version:  7
PMDA PMAPI Version:     2
Debug options:          libpmda
Timer:                  off
Getdesc:                off
Getiname:               off
Dump Instance Profile state=INCLUDE, 0 profiles
.dbpmdarc>

برای بررسی فراداده‌های سنجه و دامنه نمونه، می‌توان از دستورهای desc و instance استفاده کرد. سنجه‌ها را می‌توان با نام یا با استفاده از نمادگذاری عددی «نقطه‌دار» جهت مشخص کردن فیلدهای دامنه، خوشه و مورد یک PMID تعیین کرد. دامنه‌های نمونه باید با استفاده از نمادگذاری عددی «نقطه‌دار» جهت تعیین فیلدهای دامنه و سریال مشخص شوند. در صورتی که دستورها بدون هیچ آرگومانی وارد شوند، ساختار نحوی بیشتر آن‌ها نمایش داده خواهد شد:

dbpmda> desc 253.0.0
PMID: 253.0.0
    Data Type: 32-bit unsigned int  InDom: PM_INDOM_NULL 0xffffffff
    Semantics: instant  Units: none
dbpmda> instance
instance indom# [ number | name | "name" ]
dbpmda> instance 253.0
pmInDom: 253.0
[  0] inst: 0 name: "red"
[  1] inst: 1 name: "green"
[  2] inst: 2 name: "blue"

جهت آزمایش مهم‌ترین مؤلفه یک PMDA، یعنی fetch، اغلب تعیین مدت زمانی که طول می‌کشد تا PMDA پاسخ دهد مفید است. پیش از اجرای یک fetch، می‌توان timer را روشن کرد:

dbpmda> timer on
dbpmda> fetch simple.numfetch 253.0.1
PMID(s): 253.0.0 253.0.1
pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 2
  253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
   value 1 1.4012985e-45 0x1
  253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
    inst [0 or ???] value 1 1 1.4012985e-45 0x1
    inst [1 or ???] value 101 1.4153114e-43 0x65
    inst [2 or ???] value 201 2.8166099e-43 0xc9
Timer: 0.003921 seconds
dbpmda> timer off

اگر getdesc روی off تنظیم شده باشد (پیش‌فرض)، ترجمه‌های مقادیر به صورت عدد صحیح، ممیز شناور و مبنای شانزده در ساختار pmResult تخلیه می‌شوند. تنظیم getdesc روی on همچنین باعث واکشی فراداده سنجه (یا pmDesc) می‌شود و این امر موجب می‌شود که در واکشی فوق تنها مقادیر صحیح تخلیه شوند، زیرا فراداده سنجه نوع آن را عدد صحیح ۳۲ بیتی بدون علامت توصیف می‌کند..PP به‌طور مشابه، تنظیم getiname جستجوی نام‌های خارجی نمونه را برای معیارهایی با یک دامنه نمونه مرتبط کنترل می‌کند. هنگامی که off باشد (پیش‌فرض) خروجی مانند بالا خواهد بود. هنگامی که on باشد، «نام‌های» نمونه ??? توسط PMDA به نام‌های نمونه خارجی آن‌ها ترجمه شده و مانند زیر گزارش می‌شوند:

dbpmda> getiname on
dbpmda> fetch simple.color
PMID(s): 253.0.1
pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
  253.0.1 (simple.color): numval: 3 valfmt: 0 vlist[]:
    inst [0 or "red"] value 4
    inst [1 or "green"] value 104
    inst [2 or "blue"] value 204

از آنجا که متاداده معیار برای جستجوی نام نمونه لازم است، تنظیم getiname روی on به‌طور ضمنی getdesc را نیز روی on قرار می‌دهد.

توجه داشته باشید که اگر هر یک از getdesc یا getiname روی on تنظیم شده باشند، هر فراخوانی fetch شامل فراخوانی‌های اضافی روی PMDA خواهد بود. برای یک PMDA در حال توسعه ممکن است این ایده خوبی نباشد، به همین دلیل هر دو تنظیم به‌طور پیش‌فرض off هستند.

همچنین PMDAی simple از عملیات store پشتیبانی می‌کند که می‌توان آن را با دستورهای متعاقب fetch آزمایش کرد:

dbpmda> store simple.numfetch "42"
PMID: 253.0.0
Getting description...
Getting Result Structure...
253.0.0: 2 -> 42
dbpmda> fetch simple.numfetch
PMID(s): 253.0.0
pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
  253.0.0 (simple.numfetch): numval: 1 valfmt: 0 vlist[]:
   value 43

آرگومان مقدار در دستور store باید یک رشته باشد که در علامت نقل‌قول تکی (') یا دوتایی (") قرار می‌گیرد.

یک profile می‌تواند برای هر دامنه نمونه تعیین شود که شامل همه، برخی یا هیچ‌یک از نمونه‌ها باشد:

dbpmda> help profile
profile indom# [ all | none ]
profile indom# [ add | delete ] number
For the instance domain specified, the profile may be changed to
include 'all' instances, no instances, add an instance or delete
an instance.
dbpmda> profile 253.0 none
dbpmda> getdesc on
dbpmda> fetch 253.0.1
PMID(s): 253.0.1
pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
  253.0.1 (simple.color): No values returned!
dbpmda> profile 253.0 add 2
dbpmda> fetch 253.0.1
PMID(s): 253.0.1
pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
  253.0.1 (simple.color): numval: 1 valfmt: 0 vlist[]:
   value 202
dbpmda> profile 253.0 add 0
dbpmda> fetch 253.0.1
PMID(s): 253.0.1
pmResult dump from 0x100078e0 timestamp: 0.000000 11:00:00.000 numpmid: 1
  253.0.1 (simple.color): numval: 2 valfmt: 0 vlist[]:
    inst [0 or ???] value 2
    inst [2 or ???] value 203
dbpmda> status
Namespace:              (default)
PMDA:                   ./pmda_simple.so
Connection:             dso
DSO Interface Version:  7
PMDA PMAPI Version:     2
Debug options:          (none)
Timer:                  off
Getdesc:                off
Getiname:               off
Dump Instance Profile state=INCLUDE, 1 profiles
        Profile [0] indom=1061158913 [253.0] state=EXCLUDE 2 instances
                Instances: [2] [0]
dbpmda> quit

دستور watch (کاربرد: watch filename ) یک پنجره xterm را باز می‌کند که فایل لاگ مشخص‌شده را دنبال (tail) می‌کند. این پنجره زمانی که دیگر نیازی به آن نباشد باید توسط کاربر بسته شود.

دستور wait معادل sleep(1) است و یک آرگومان عدد صحیح تکی (زمان انتظار به ثانیه) می‌گیرد.

معرفی زیردرخت‌های پویا در PMNS و PMDA_INTERFACE_4 در libpcp_pmda منجر به پشتیبانی از دستورهای اضافی در dbpmda جهت به‌کارگیری سرویس‌های پویای PMNS مرتبط شده است. مثال‌های زیر بر اساس PMDAی sample هستند.

$ dbpmda
dbpmda> open pipe /var/lib/pcp/pmdas/sample/pmdasample -d 29
Start pmdasample PMDA: /var/lib/pcp/pmdas/sample/pmdasample -d 29
dbpmda> children sample.secret
Metric: sample.secret
   non-leaf foo
       leaf bar
dbpmda> traverse sample.secret.foo
Metric: sample.secret.foo
   sample.secret.foo.bar.max.redirect
   sample.secret.foo.one
   sample.secret.foo.two
   sample.secret.foo.bar.three
   sample.secret.foo.bar.four
   sample.secret.foo.bar.grunt.five
   sample.secret.foo.bar.grunt.snort.six
   sample.secret.foo.bar.grunt.snort.huff.puff.seven
dbpmda> pmid sample.secret.foo.bar.four
Metric: sample.secret.foo.bar.four
   29.0.1004
dbpmda> name 29.0.1006
PMID: 29.0.1006
   sample.secret.foo.bar.grunt.snort.six
دستور children بخش بعدی نام را برای تمام نوادگان مستقیم یک گره در یک زیردرخت پویا از PMNS بازمی‌گرداند. دستور مرتبط traverse نام‌های کامل معیار را برای تمام گره‌های برگ در PMNS واقع در زیر گره غیربرگ مشخص‌شده در یک زیردرخت پویا از PMNS بازمی‌گرداند.

دستورهای name و pmid ترجمه نام‌های معیار به PMIDها (و برعکس) را برای معیارهای درون یک زیردرخت پویا از PMNS آزمایش می‌کنند.

اگر دستورهای children، traverse، pmid یا name با یک PMDA استفاده شوند که از PMDA_INTERFACE_4 استفاده نمی‌کند یا با نام‌های معیارهای کارایی که بخشی از یک زیردرخت پویا از PMNS نیستند به کار بروند، انتظار می‌رود PMDA خطاهایی (PM_ERR_NAME یا PM_ERR_PMID) را بازگرداند تا نشان دهد که عملیات با خطا مواجه شده است (خارج از یک زیردرخت پویا از PMNS، این pmcd(1) است و نه PMDA که مسئول پیاده‌سازی این توابع می‌باشد).

سازوکارهای احراز هویت کلاینت در PMCS گنجانده شده‌اند و اطلاعاتی را به ازای هر کاربر (و به ازای هر اتصال) فراهم می‌کنند که در دسترس PMDAها قرار می‌گیرد. یک PMDA که از PMDA_INTERFACE_6 یا بالاتر در libpcp_pmda استفاده می‌کند، قادر است از متد «attribute» برای به‌دست آوردن دید به این اتصال‌های احراز هویت‌شده بهره ببرد، با دسترسی به اطلاعاتی شامل شناسه‌های کاربر و گروه، نام کاربری و مواردی از این دست. نیاز به آزمایش و اشکال‌زدایی این رابط منجر به یک دستور جدید در dbpmda شده است. مثال زیر بر پایه PMDAی sample می‌باشد.

$ dbpmda
dbpmda> open pipe pmdasample -D AUTH -l logfile
Start pmdasample PMDA: pmdasample -D AUTH -l logfile
dbpmda> attr "username" "tanya"
Attribute: username=tanya
Success
dbpmda> attr 11 "0"
Attribute: userid=0
Success
dbpmda>

دستور attr ویژگی‌های اتصال (کلیدهای PCP_ATTR_XXXX) و مقادیر آن‌ها را به شیوه‌ای مشابه آنچه PMCD برای اتصال یک کلاینت انجام می‌دهد، به یک PMDA ارسال می‌کند. dbpmda همواره شناسه بافت کلاینت (client context identifier) صفر را ارسال می‌کند، و با اینکه هیچ بررسی اعتباری روی مقادیر انجام نمی‌شود، تنها ویژگی‌های شناخته‌شده قابل تنظیم هستند.

در مثال بالا، گزینه اشکال‌زدایی AUTH برای PMDA تنظیم شده است که از آن در بازخوانی ویژگی (attribute callback) خود استفاده کرده و هر جفت ویژگی و مقدار ارسالی به آن را در logfile خود ثبت می‌نماید.

توجه داشته باشید که تا زمانی که این ویژگی‌ها به PMDA ارائه شوند، بررسی‌های احراز هویت پیش‌تر توسط PMCD انجام شده است؛ بنابراین هیچ اعتبارسنجی دیگری توسط PMDA لازم نیست.

دستور debug یک یا چند گزینه اشکال‌زدایی را که با فاصله خالی یا ویرگول جدا شده‌اند دریافت می‌کند. این دستور می‌تواند برای فعال‌سازی انتخابی خروجی اشکال‌زدایی از ماژول‌های مختلف کتابخانه‌های PCP که PMDA با آن‌ها پیوند (link) خواهد خورد، استفاده شود. اگر پیشوند گزینه یک علامت منفی «-» باشد، گزینه اشکال‌زدایی متناظر غیرفعال می‌شود. گزینه‌ها همان نام‌های اشکال‌زدایی هستند که توسط گزینه -l در pmdbg(1) گزارش می‌شوند و/یا مقادیر عددی معادل و منسوخ‌شده آن‌ها هستند که توسط گزینه‌های -ol در pmdbg(1) گزارش می‌گردند. «گزینه» ویژه none تمام اشکال‌زدایی‌ها را غیرفعال می‌کند و «گزینه» ویژه all تمام گزینه‌های اشکال‌زدایی را فعال می‌نماید..SH "هشدارها (CAVEATS)" نمی‌توان مقداری را در معیارهایی از نوع PM_TYPE_AGGREGATE یا PM_TYPE_EVENT ذخیره کرد.

دستور dbpmda از fork(2) و exec(2) برای اتصال به دیمن‌های PMDA استفاده می‌کند. dbpmda هیچ تلاشی برای تشخیص خاتمه یافتن فرایند دیمن PMDA نمی‌کند، بنابراین ممکن است یک PMDA بدون هیچ اعلانی به‌طور غیرمنتظره‌ای خارج شود. با این حال، هرگونه تلاش بعدی برای ارتباط با PMDA به خطاهایی منجر خواهد شد که نشان می‌دهند PMDA دیگر پاسخ‌گو نیست.

./.dbpmdarc
فهرست دستورهایی که باید در هنگام راه‌اندازی اجرا شوند.

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

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

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

gdb(1), pmcd(1), pmdbg(1), exec(2), fork(2), PMAPI(3), PMDA(3), pcp.conf(5), pcp.env(5) و PMNS(5).

PCP Performance Co-Pilot