'\"macro stdmacro .\" .\" Copyright (c) 2000 Silicon Graphics, Inc. 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 DBPMDA 1 "PCP" "Performance Co-Pilot" .SH "نام (NAME)" \f3dbpmda\f1 \- اشکال‌زدای PMDAهای سامانه Performance Co-Pilot .SH "خلاصه دستور (SYNOPSIS)" \f3dbpmda\f1 [\f3\-D\f1 \f2debug\f1] [\f3\-efiv?\f1] [\f3\-n\f1 \f2pmnsfile\f1] [\f3\-q\f1 \f2timeout\f1] [\f3\-U\f1 \f2username\f1] .SH "توضیحات (DESCRIPTION)" .B dbpmda یک واسط تعاملی برای بررسی و مدیریت تعاملات میان یک عامل دامنه معیارهای کارایی .RB ( PMDA (3)) و دیمن جمع‌آوری معیارهای کارایی .RB ( pmcd (1)) است. این ابزار امکان اتصال، مقداردهی اولیه و اجرای آزمایشی PMDAها را جهت سنجش صحت عملکرد آن‌ها فراهم می‌آورد. .PP .B dbpmda دستورها را به‌صورت تعاملی از کاربر درخواست می‌کند که بسیاری از آن‌ها واحدهای داده پروتکل (PDUها) را که ممکن است توسط یک فرایند .BR pmcd (1) ارسال شوند، شبیه‌سازی می‌نمایند. پس از اجرای .BR dbpmda ، دستور .B help را برای دریافت فهرستی از دستورهای موجود وارد کنید. بخش مثال‌ها در ادامه، یک نشست کاری با استفاده از .B dbpmda را برای آزمایش یک PMDA شرح می‌دهد. .PP به‌منظور ساده‌سازی آزمایش‌های مکرر یک PMDA، فایل .I .dbpmdarc در دایرکتوری کاری جاری می‌تواند حاوی فهرستی از دستورهایی باشد که هنگام راه‌اندازی توسط .B dbpmda پیش از درخواست تعاملی دستورها از کاربر اجرا می‌شوند. هنگام پردازش فایل .IR .dbpmdarc ، حالت تعاملی و بازتاب دستورها (echoing) فعال شده و سپس در انتهای فایل .I .dbpmdarc به حالت اولیه بازنشانی می‌شوند (گزینه‌های خط فرمان .B \-i و .B \-e در ادامه را ببینید). .PP گزینه خط فرمان .B \-f از پردازش فایل .I .dbpmdarc (در صورت وجود) در زمان راه‌اندازی جلوگیری می‌کند. .PP اگر سیستم از .BR readline (3) پشتیبانی کند، در صورت دریافت ورودی از یک دستگاه tty از آن برای خواندن دستورها استفاده خواهد شد؛ بنابراین قابلیت‌های تاریخچه و ویرایش خط فرمان در دسترس خواهد بود. .PP از آنجا که هنگام استفاده از .B dbpmda (در مقایسه با .BR pmcd (1)) هیچ محدودیت زمانی (timeout) برای یک PMDA وجود ندارد، پس از اتصال فرایند PMDA به .BR dbpmda ، می‌توان از یک اشکال‌زدای دیگر مانند .BR gdb (1) روی فرایند PMDA استفاده کرد..SH "گزینه‌ها (OPTIONS)" گزینه‌های موجود برای خط فرمان عبارتند از: .TP 5 \f3\-e\f1, \f3\-\-echo\-input\f1 انعکاس ورودی در .BR stdout . این گزینه زمانی مفید است که ورودی از یک فایل تغییر مسیر داده شده باشد. .TP \f3\-f\f1, \f3\-\-norc\f1 عدم پردازش فایل .BR .dbpmdarc . .TP \f3\-i\f1, \f3\-\-interactive\f1 شبیه‌سازی رفتار تعاملی و اعلان برای دستورهای جدید، حتی اگر ورودی استاندارد یک دستگاه tty نباشد. .TP \fB\-n\fR \fIpmnsfile\fR, \fB\-\-namespace\fR=\fIpmnsfile\fR بارگذاری یک فضای نام سنجه‌های عملکردی .RB ( PMNS (5)) جایگزین از فایل .IR pmnsfile . .TP \fB\-q\fR \fItimeout\fR, \fB\-\-creds\-timeout\fR=\fItimeout\fR پروتکل تبادل نسخه بین pmcd و عامل (جدید در PCP 2.0 \- معرفی‌شده برای فراهم کردن سازگاری رو به عقب) از این مهلت زمانی استفاده می‌کند تا مشخص کند \f3dbpmda\f1 چه مدت باید منتظر بماند پیش از آنکه فرض کند هیچ پاسخی مبنی بر نسخه از طرف عامل ارسال نمی‌شود. اگر این مهلت زمانی به پایان برسد، فرض می‌شود عامل از نوعی است که پروتکل PCP 2.0 را درک نمی‌کند. فاصله مهلت زمانی پیش‌فرض سه ثانیه است، اما گزینه .B \-q امکان تعیین یک مهلت زمانی جایگزین (که باید بزرگ‌تر از صفر باشد) را فراهم می‌کند. واحد زمان ثانیه است. .TP \fB\-U\fR \fIusername\fR, \fB\-\-username\fR=\fIusername\fR حساب کاربری که .B dbpmda تحت آن اجرا می‌شود. .TP \fB\-v\fR, \fB\-\-valgrind\fR هنگام اجرای .B dbpmda تحت نظارت .BR valgrind (1) جهت دسته‌بندی و اولویت‌بندی مشکلات در یک DSO PMDA مفید است. اگر گزینه .B \-v استفاده شود، آنگاه .B dbpmda پیش از خروج .BR dlclose (3) را فراخوانی نخواهد کرد؛ این امر به .BR valgrind (1) اجازه می‌دهد هنگام گزارش‌دهی به جدول نمادهای DSO PMDA دسترسی داشته باشد که اشکال‌زدایی را بسیار ساده‌تر می‌کند. .TP \fB\-?\fR, \fB\-\-help\fR نمایش پیام راهنمای استفاده و خروج. .SH "مثال‌ها (EXAMPLES)" در زیر یک نشست .B dbpmda با استفاده از PMDAی .I simple آمده است. از یک فایل .B \.dbpmdarc جهت تنظیم گزینه اشکال‌زدایی، باز کردن PMDA و نمایش وضعیت فعلی اشکال‌زدا استفاده شده است: .PP .nf .ft CR .in +0.5i $ cat .dbpmdarc debug libpmda open dso pmda_simple.so simple_init 253 status .fi .in .PP هنگامی که .B dbpmda اجرا می‌شود، دستورهای درون فایل .B \.dbpmdarc ابتدا اجرا می‌شوند: .PP .nf .ft CR .in +0.5i $ 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> .fi .in .PP برای بررسی فراداده‌های سنجه و دامنه نمونه، می‌توان از دستورهای .B desc و .B instance استفاده کرد. سنجه‌ها را می‌توان با نام یا با استفاده از نمادگذاری عددی «نقطه‌دار» جهت مشخص کردن فیلدهای دامنه، خوشه و مورد یک PMID تعیین کرد. دامنه‌های نمونه باید با استفاده از نمادگذاری عددی «نقطه‌دار» جهت تعیین فیلدهای دامنه و سریال مشخص شوند. در صورتی که دستورها بدون هیچ آرگومانی وارد شوند، ساختار نحوی بیشتر آن‌ها نمایش داده خواهد شد: .PP .nf .ft CR .in +0.5i 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" .fi .in .PP جهت آزمایش مهم‌ترین مؤلفه یک PMDA، یعنی .BR fetch ، اغلب تعیین مدت زمانی که طول می‌کشد تا PMDA پاسخ دهد مفید است. پیش از اجرای یک .BR fetch ، می‌توان .B timer را روشن کرد: .PP .nf .ft CR .in +0.5i 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 .fi .in .PP اگر .B getdesc روی .B off تنظیم شده باشد (پیش‌فرض)، ترجمه‌های مقادیر به صورت عدد صحیح، ممیز شناور و مبنای شانزده در ساختار .I pmResult تخلیه می‌شوند. تنظیم .B getdesc روی .B on همچنین باعث واکشی فراداده سنجه (یا .BR pmDesc ) می‌شود و این امر موجب می‌شود که در واکشی فوق تنها مقادیر صحیح تخلیه شوند، زیرا فراداده سنجه نوع آن را عدد صحیح ۳۲ بیتی بدون علامت توصیف می‌کند..PP به‌طور مشابه، تنظیم .B getiname جستجوی نام‌های خارجی نمونه را برای معیارهایی با یک دامنه نمونه مرتبط کنترل می‌کند. هنگامی که .B off باشد (پیش‌فرض) خروجی مانند بالا خواهد بود. هنگامی که .B on باشد، «نام‌های» نمونه ??? توسط PMDA به نام‌های نمونه خارجی آن‌ها ترجمه شده و مانند زیر گزارش می‌شوند: .PP .nf .ft CR .in +0.5i 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 .fi .in .PP از آنجا که متاداده معیار برای جستجوی نام نمونه لازم است، تنظیم .B getiname روی .B on به‌طور ضمنی .B getdesc را نیز روی .BR on قرار می‌دهد. .PP توجه داشته باشید که اگر هر یک از .B getdesc یا .B getiname روی .B on تنظیم شده باشند، هر فراخوانی .B fetch شامل فراخوانی‌های اضافی روی PMDA خواهد بود. برای یک PMDA در حال توسعه ممکن است این ایده خوبی نباشد، به همین دلیل هر دو تنظیم به‌طور پیش‌فرض .BR off هستند. .PP همچنین PMDAی simple از عملیات .B store پشتیبانی می‌کند که می‌توان آن را با دستورهای متعاقب .B fetch آزمایش کرد: .PP .nf .ft CR .in +0.5i 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 .fi .in .PP آرگومان مقدار در دستور .B store باید یک رشته باشد که در علامت نقل‌قول تکی (') یا دوتایی (") قرار می‌گیرد. .PP یک .B profile می‌تواند برای هر دامنه نمونه تعیین شود که شامل همه، برخی یا هیچ‌یک از نمونه‌ها باشد: .PP .nf .ft CR .in +0.5i 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 .fi .PP دستور .B watch (کاربرد: .B watch .I filename ) یک پنجره xterm را باز می‌کند که فایل لاگ مشخص‌شده را دنبال (tail) می‌کند. این پنجره زمانی که دیگر نیازی به آن نباشد باید توسط کاربر بسته شود. .PP دستور .B wait معادل .BR sleep (1) است و یک آرگومان عدد صحیح تکی (زمان انتظار به ثانیه) می‌گیرد. .PP معرفی زیردرخت‌های پویا در PMNS و PMDA_INTERFACE_4 در .I libpcp_pmda منجر به پشتیبانی از دستورهای اضافی در .B dbpmda جهت به‌کارگیری سرویس‌های پویای PMNS مرتبط شده است. مثال‌های زیر بر اساس PMDAی .I sample هستند. .PP .nf .ft CR .in +0.5i $ 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 .fi .in.PP دستور .B children بخش بعدی نام را برای تمام نوادگان مستقیم یک گره در یک زیردرخت پویا از PMNS بازمی‌گرداند. دستور مرتبط .B traverse نام‌های کامل معیار را برای تمام گره‌های برگ در PMNS واقع در زیر گره غیربرگ مشخص‌شده در یک زیردرخت پویا از PMNS بازمی‌گرداند. .PP دستورهای .B name و .B pmid ترجمه نام‌های معیار به PMIDها (و برعکس) را برای معیارهای درون یک زیردرخت پویا از PMNS آزمایش می‌کنند. .PP اگر دستورهای .BR children ، .BR traverse ، .B pmid یا .B name با یک PMDA استفاده شوند که از PMDA_INTERFACE_4 استفاده .B نمی‌کند یا با نام‌های معیارهای کارایی که بخشی از یک زیردرخت پویا از PMNS نیستند به کار بروند، انتظار می‌رود PMDA خطاهایی (PM_ERR_NAME یا PM_ERR_PMID) را بازگرداند تا نشان دهد که عملیات با خطا مواجه شده است (خارج از یک زیردرخت پویا از PMNS، این .BR pmcd (1) است و نه PMDA که مسئول پیاده‌سازی این توابع می‌باشد). .PP سازوکارهای احراز هویت کلاینت در PMCS گنجانده شده‌اند و اطلاعاتی را به ازای هر کاربر (و به ازای هر اتصال) فراهم می‌کنند که در دسترس PMDAها قرار می‌گیرد. یک PMDA که از PMDA_INTERFACE_6 یا بالاتر در .I libpcp_pmda استفاده می‌کند، قادر است از متد «attribute» برای به‌دست آوردن دید به این اتصال‌های احراز هویت‌شده بهره ببرد، با دسترسی به اطلاعاتی شامل شناسه‌های کاربر و گروه، نام کاربری و مواردی از این دست. نیاز به آزمایش و اشکال‌زدایی این رابط منجر به یک دستور جدید در .B dbpmda شده است. مثال زیر بر پایه PMDAی .I sample می‌باشد. .PP .nf .ft CR .in +0.5i $ 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> .fi .in .PP دستور .B attr ویژگی‌های اتصال (کلیدهای PCP_ATTR_XXXX) و مقادیر آن‌ها را به شیوه‌ای مشابه آنچه PMCD برای اتصال یک کلاینت انجام می‌دهد، به یک PMDA ارسال می‌کند. .B dbpmda همواره شناسه بافت کلاینت (client context identifier) صفر را ارسال می‌کند، و با اینکه هیچ بررسی اعتباری روی مقادیر انجام نمی‌شود، تنها ویژگی‌های شناخته‌شده قابل تنظیم هستند. .PP در مثال بالا، گزینه اشکال‌زدایی .I AUTH برای PMDA تنظیم شده است که از آن در بازخوانی ویژگی (attribute callback) خود استفاده کرده و هر جفت ویژگی و مقدار ارسالی به آن را در .IR logfile خود ثبت می‌نماید. .PP توجه داشته باشید که تا زمانی که این ویژگی‌ها به PMDA ارائه شوند، بررسی‌های احراز هویت پیش‌تر توسط PMCD انجام شده است؛ بنابراین هیچ اعتبارسنجی دیگری توسط PMDA لازم نیست. .PP دستور .B debug یک یا چند گزینه اشکال‌زدایی را که با فاصله خالی یا ویرگول جدا شده‌اند دریافت می‌کند. این دستور می‌تواند برای فعال‌سازی انتخابی خروجی اشکال‌زدایی از ماژول‌های مختلف کتابخانه‌های PCP که PMDA با آن‌ها پیوند (link) خواهد خورد، استفاده شود. اگر پیشوند گزینه یک علامت منفی «\-» باشد، گزینه اشکال‌زدایی متناظر غیرفعال می‌شود. گزینه‌ها همان نام‌های اشکال‌زدایی هستند که توسط گزینه .B \-l در .BR pmdbg (1) گزارش می‌شوند و/یا مقادیر عددی معادل و منسوخ‌شده آن‌ها هستند که توسط گزینه‌های .B \-ol در .BR pmdbg (1) گزارش می‌گردند. «گزینه» ویژه .B none تمام اشکال‌زدایی‌ها را غیرفعال می‌کند و «گزینه» ویژه .B all تمام گزینه‌های اشکال‌زدایی را فعال می‌نماید..SH "هشدارها (CAVEATS)" نمی‌توان مقداری را در معیارهایی از نوع .B PM_TYPE_AGGREGATE یا .BR PM_TYPE_EVENT ذخیره کرد. .PP دستور .B dbpmda از .BR fork (2) و .BR exec (2) برای اتصال به دیمن‌های PMDA استفاده می‌کند. .B dbpmda هیچ تلاشی برای تشخیص خاتمه یافتن فرایند دیمن PMDA نمی‌کند، بنابراین ممکن است یک PMDA بدون هیچ اعلانی به‌طور غیرمنتظره‌ای خارج شود. با این حال، هرگونه تلاش بعدی برای ارتباط با PMDA به خطاهایی منجر خواهد شد که نشان می‌دهند PMDA دیگر پاسخ‌گو نیست. .SH "فایل‌ها (FILES)" .TP 5 .I ./.dbpmdarc فهرست دستورهایی که باید در هنگام راه‌اندازی اجرا شوند. .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 "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)" گزینه .B \-D یا .B \-\-debug خروجی عیب‌یابی‌های بیشتری را در .I stderr فعال می‌کند تا به تفکیک و بررسی مشکلات کمک نماید، هرچند این اطلاعات گاهی مبهم هستند و در درجه اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده‌اند تا کاربران نهایی. .I debug فهرستی از گزینه‌های اشکال‌زدایی است که با کاما از هم جدا شده‌اند؛ از .BR pmdbg (1) همراه با گزینه .B \-l استفاده کنید تا فهرستی از گزینه‌های اشکال‌زدایی موجود و مفهوم آن‌ها را دریافت کنید. .SH "همچنین ببینید (SEE ALSO)" .BR gdb (1), .BR pmcd (1), .BR pmdbg (1), .BR exec (2), .BR fork (2), .BR PMAPI (3), .BR PMDA (3), .BR pcp.conf (5), .BR pcp.env (5) و .BR PMNS (5). .\" control lines for scripts/man-spell .\" +ok+ AUTH Getdesc Getiname PCP_ATTR_XXXX Sep attr dbpmdarc desc .\" +ok+ getdesc getiname libpmda logfile num numfetch .\" +ok+ ol {from -ol} pmda_simple simple_init tanya userid