'\" t
.\"
.\" Copyright (c) 2012,2017 Red Hat.
.\" Copyright (c) 2012 Nathan Scott.  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 PMDABASH 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmdabash\f1 \- عامل دامنه معیارهای کارایی برای ردگیری شل Bourne-Again
.SH "خلاصه دستور (SYNOPSIS)"
\f3$PCP_PMDAS_DIR/bash/pmdabash\f1
[\f3\-C\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-d\f1 \f2domain\f1]
[\f3\-l\f1 \f2logfile\f1]
[\f3\-I\f1 \f2interval\f1]
[\f3\-t\f1 \f2timeout\f1]
[\f3\-U\f1 \f2username\f1]
\f2configfile\f1
.SH "توضیحات (DESCRIPTION)"
.B pmdabash
یک «عامل دامنه معیارهای کارایی» (PMDA) آزمایشی است که رویدادهای «xtrace» را از یک فرایند ردیابی‌شدهٔ
.BR bash (1)
صادر می‌کند.
این شامل اطلاعات اجرای دستوری است که معمولاً با گزینهٔ
.BR "set -x"
شل به خروجی خطای استاندارد ارسال می‌شود.
.PP
معیارهای رویداد صادر شده، هر دستور اجرا شده، نام تابع و شماره خط در اسکریپت و یک برچسب زمان را نمایش می‌دهند.
علاوه بر این، شناسه فرایند (PID) مربوط به شل و فرایند والد آن نیز صادر می‌شود.
.PP
این نیازمند
.B bash
نسخهٔ ۴ یا بالاتر است.
.PP
شرح مختصری از گزینه‌های خط فرمان
.B pmdabash
در ادامه آمده است:
.TP 5
.B \-d
بسیار حیاتی است که شماره دامنهٔ (
.I domain
) معیارهای کارایی مشخص‌شده در اینجا یکتا و سازگار باشد.
به این معنی که
.I domain
باید برای هر PMDA روی یک میزبان متفاوت باشد، و همان شمارهٔ
.I domain
باید برای همان PMDA در تمام میزبان‌ها استفاده شود.
.TP 5
.B \-l
مکان فایل ثبت وقایع (log). به‌طور پیش‌فرض، هنگام راه‌اندازی
.B pmdabash
یک فایل لاگ به نام
.I bash.log
در دایرکتوری جاریِ
.BR pmcd (1)
یعنی
.BR $PCP_LOG_DIR/pmcd
نوشته می‌شود. اگر فایل لاگ نتواند ایجاد شود یا قابل نوشتن نباشد، خروجی به جای آن به خطای استاندارد فرستاده می‌شود.
.TP 5
.B \-s
مدت زمان (بر حسب ثانیه) بین ارزیابی‌های متوالی توصیف‌گر(های) فایل ردگیری شل.
پیش‌فرض ۲ ثانیه است.
.TP 5
.B \-m
حداکثر مقدار حافظهٔ مجاز برای هر صف رویداد (یکی به ازای هر فرایند ردگیری‌شده).
پیش‌فرض ۲ مگابایت است.
.TP 5
.B \-U
حساب کاربری که عامل تحت آن اجرا می‌شود.
پیش‌فرض در نسخه‌های کنونی PCP حساب غیرممتاز "pcp" است،
اما در نسخه‌های قدیمی‌تر از حساب کاربری ریشه ("root") به‌طور پیش‌فرض استفاده می‌شد.
.SH "نصب (INSTALLATION)"
برای اینکه یک میزبان بتواند نام‌ها، متن راهنما و مقادیر معیارهای کارایی bash را صادر کند، دستورات زیر را به عنوان ریشه (root) انجام دهید:
.PP
.ft CR
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/bash
# ./Install
.in
.fi
.ft 1
.PP
به محض اینکه یک اسکریپت شل مجهز شده (بخش «تجهیز کد (INSTRUMENTATION)» در ادامه را ببینید) با فعال بودن ردگیری اجرا شود، مقادیر جدید معیارها ظاهر خواهند شد؛ هیچ پیکربندی بیشتری برای عامل لازم نیست.
.PP
اگر می‌خواهید نصب را لغو کنید، کارهای زیر را به عنوان ریشه (root) انجام دهید:
.PP
.ft CR
.nf
.in +0.5i
# cd $PCP_PMDAS_DIR/bash
# ./Remove
.in
.fi
.ft 1
.PP
برنامهٔ
.B pmdabash
توسط
.BR pmcd (1)
راه‌اندازی می‌شود و هرگز نباید مستقیماً اجرا گردد.
اسکریپت‌های Install و Remove در هنگام نصب یا حذف عامل، به
.BR pmcd (1)
اطلاع می‌دهند.
.SH "تجهیز کد (INSTRUMENTATION)"
به منظور برقراری جریان داده‌های رویداد میان یک اسکریپت
.BR bash (1)
و
.BR pmdabash ،
اسکریپت باید اقدامات زیر را انجام دهد:
.PP
.ft CR
.nf
.in +0.5i
#!/bin/sh
source $PCP_DIR/etc/pcp.env
source $PCP_SHARE_DIR/lib/bashproc.sh

pcp_trace on $@       # enable tracing
echo "awoke, $count"

pcp_trace off         # disable tracing
.in
.fi
.ft 1
.PP
ردگیری می‌تواند به هر تعداد دلخواه توسط اسکریپت فعال و غیرفعال شود.
پس از نصب موفقیت‌آمیز عامل، چندین معیار در دسترس خواهند بود:
.PP
.ft CR
.nf
.in +0.5i
$ pminfo bash
bash.xtrace.numclients
bash.xtrace.maxmem
bash.xtrace.queuemem
bash.xtrace.count
bash.xtrace.records
bash.xtrace.parameters.pid
bash.xtrace.parameters.parent
bash.xtrace.parameters.lineno
bash.xtrace.parameters.function
bash.xtrace.parameters.command
.in
.fi
.ft 1
.PP
هنگامی که یک اسکریپت مجهز در حال اجرا است، می‌توان ایجاد رکوردهای رویداد را با استفاده از دستور
.BR pmevent (1)
به شکل زیر بررسی و تأیید کرد:
.PP
.ft CR
.nf
.in +0.5i
$ pmevent \-t 1 \-x '' bash.xtrace.records
host:      localhost
samples:   all
bash.xtrace.records["4538 ./test-trace.sh 1 2 3"]: 5 event records
  10:00:05.000 --- event record [0] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 43
    bash.xtrace.parameters.command "true"
  10:00:05.000 --- event record [1] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 45
    bash.xtrace.parameters.command "((  count++  ))"
  10:00:05.000 --- event record [2] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 46
    bash.xtrace.parameters.command "echo 'awoke, 3'"
  10:00:05.000 --- event record [3] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 47
    bash.xtrace.parameters.command "tired 2"
  10:00:05.000 --- event record [4] flags 0x19 (point,id,parent) ---
    bash.xtrace.parameters.pid 4538
    bash.xtrace.parameters.parent 4432
    bash.xtrace.parameters.lineno 38
    bash.xtrace.parameters.function "tired"
    bash.xtrace.parameters.command "sleep 2"
.in
.fi
.ft 1
.SH "فایل‌ها (FILES)"
.PD 0
.TP 10
.B $PCP_PMCDCONF_PATH
گزینه‌های خط فرمان مورد استفاده برای راه‌اندازی
.B pmdabash
.TP 10
.B $PCP_PMDAS_DIR/bash/help
فایل پیش‌فرض متن راهنما برای معیارهای bash
.TP 10
.B $PCP_PMDAS_DIR/bash/Install
اسکریپت نصب برای عامل
.B pmdabash
.TP 10
.B $PCP_PMDAS_DIR/bash/Remove
اسکریپت لغو نصب برای
.B pmdabash
.TP 10
.B $PCP_LOG_DIR/pmcd/bash.log
فایل لاگ پیش‌فرض برای پیام‌های خطا و سایر اطلاعات از
.B pmdabash
.PD
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند
.B PCP_
برای پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، فایل
.B /etc/pcp.conf
شامل مقادیر محلی برای این متغیرها است.
متغیر
.B $PCP_CONF
ممکن است برای مشخص کردن یک فایل پیکربندی جایگزین استفاده شود،
همان‌طور که در
.BR pcp.conf (5)
شرح داده شده است.
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینهٔ
.B \-D
یا
.B \-\-debug
خروجی داده‌های تشخیصی اضافی را روی
.I stderr
فعال می‌کند تا به بررسی و اولویت‌بندی مشکلات کمک کند، هرچند این اطلاعات گاهی پیچیده و مبهم است و در درجهٔ اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده است تا کاربران نهایی.
.I debug
یک فهرست جدا شده با کاما از گزینه‌های اشکال‌زدایی است؛ از
.BR pmdbg (1)
با گزینهٔ
.B \-l
برای دریافت فهرستی از گزینه‌های اشکال‌زدایی موجود و معانی آن‌ها استفاده کنید.
.PP
گزینه‌های اشکال‌زدایی ویژهٔ
.B pmdabash
به شرح زیر هستند:
.TS
box;
lf(B) | lf(B)
lf(B) | lf(R) .
گزینه	توضیحات
_
appl0	ثبت وقایع با جزئیات (verbose) برای رویدادهای مورد نظر
.TE
.SH "همچنین ببینید (SEE ALSO)"
.BR bash (1)،
.BR pmevent (1)
و
.BR pmcd (1).

.\" control lines for scripts/man-spell
.\" +ok+ SHell bashproc lineno maxmem numclients pcp_trace queuemem xtrace