'\" t
.\"
.\" Copyright (c) 2013-2016,2020 Red Hat.
.\" 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 PMLOGCONF 1 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmlogconf\f1 \- ایجاد یا ویرایش فایل پیکربندی pmlogger
.SH "خلاصه دستور (SYNOPSIS)"
\f3pmlogconf\f1
[\f3\-cqrvV?\f1]
[\f3\-d\f2 groupsdir\f1]
[\f3\-D\f1 \f2debug\f1]
[\f3\-g\f2 grouptag\f1]
[\f3\-h\f2 host\f1]
[\f3\-s\f2 groupfile\f1]
\f2configfile\f1
.SH "توضیحات (DESCRIPTION)"
دستور
.B pmlogconf
می‌تواند برای ایجاد و تغییر یک فایل پیکربندی عمومی برای بایگان‌کننده PCP، یعنی
.BR pmlogger (1)
به کار رود.
.PP
اگر
.I configfile
وجود نداشته باشد،
.B pmlogconf
یک فایل پیکربندی عمومی با مجموعه‌ای پیش‌فرض از سنجه‌های فعال و بازه‌های ثبت وقایع ایجاد خواهد کرد.
.PP
پس از ایجاد،
.I configfile
می‌تواند همراه با گزینه
.B \-c
در
.BR pmlogger (1)
برای انتخاب سنجه‌های کارایی و تعیین بازه‌های ثبت وقایع برای یک آرشیو PCP استفاده شود.
.PP
اگر
.I configfile
از قبل وجود داشته باشد،
.B pmlogconf
از کاربر درخواست ورودی می‌کند تا گروه‌هایی از سنجه‌های کارایی مرتبط را فعال یا غیرفعال کند و بازه ثبت وقایع را برای هر گروه فعال‌شده کنترل نماید.
.PP
انتخاب گروه نیازمند یک پاسخ ساده
.B y
(بله)
یا
.B n
(خیر) به اعلان
.BR "Log this group?"
است.
.PP
پاسخ‌های دیگر در این مرحله می‌توانند برای انتخاب توابع کنترلی بیشتر به شرح زیر استفاده شوند:
.IP \fBm\fP 10n
گزارش نام سنجه‌های موجود در گروه فعلی.
.IP \fBq\fP 10n
پایان دادن به انتخاب گروه (خروج) و اعمال نکردن تغییرات بیشتر در این گروه یا هر یک از گروه‌های بعدی.
.IP \fB/\fIpattern\fP 10n
عدم اعمال تغییر در این گروه، اما جستجو برای گروهی حاوی
.I pattern
در توضیحات گروه یا نام سنجه‌های وابسته.
.PP
یک بازه ثبت وقایع با پاسخ دادن به اعلان
.B "Logging interval?"
توسط کلیدواژه‌های
.B once
یا
.B default
یا یک مشخصه بازه زمانی معتبر در
.BR pmlogger (1)
به فرم ``\c
.B every
.IR "N timeunits" ''
یا صرفاً ``\c
.I "N timeunits" ''
(کلمه
.B every
اختیاری است) مشخص می‌شود؛ که در آن
.I N
یک عدد صحیح بدون علامت است و
.I timeunits
یکی از کلیدواژه‌های
.BR msec ،
.BR millisecond ،
.BR sec ،
.BR second ،
.BR min ،
.BR minute ،
.BR hour
یا شکل جمع یکی از این کلیدواژه‌ها است.
.PP
هنگام اجرا از طریق فرآیندهای خودکارِ راه‌اندازی ثبت وقایع، گزینه
.B \-c
برای نشان دادن این که
.I pmlogconf
در حالت ایجاد خودکار (auto-create) است و هیچ گفتگوی تعاملی صورت نمی‌گیرد، استفاده می‌شود.
فایل خروجی
.I configfile
دارای یک پیام توضیحی اضافی و برچسب زمانی است که این موضوع را نشان می‌دهد، تا بتوان آن را شناسایی کرده و متعاقباً با استفاده مجدد از
.B \-c
به‌روزرسانی نمود.
این گزینه برای استفاده تعاملی از این ابزار مناسب نیست.
.PP
گزینه
.B \-q
گفتگوی مربوط به بازه ثبت وقایع را متوقف می‌کند و بازه فعلی را از
.I configfile
حفظ می‌نماید.
.PP
خروجی پرجزئیات‌تر را می‌توان با گزینه
.B \-v
فعال کرد..SH "فایل‌های گروه راه‌اندازی (SETUP GROUP FILES)"
هنگامی که یک
.I configfile
اولیه ایجاد می‌شود، مشخصات پیش‌فرض از مجموعه‌ای از فایل‌های گروه در زیر
.I groupsdir
مشخص‌شده با گزینهٔ
.B \-d
به‌دست می‌آیند (مقدار پیش‌فرض
.I groupsdir
برابر با
.B $PCP_VAR_DIR/config/pmlogconf
است که در اکثر موارد درست می‌باشد، بنابراین گزینهٔ
.B \-d
در عمل به‌ندرت استفاده می‌شود).
.PP
ساختار دایرکتوری در زیر
.I groupsdir
دلخواه است، چرا که تمام فایل‌های عادی با پیمایش بازگشتی پیدا شده و مورد بررسی قرار می‌گیرند؛ از این رو محصولات جانبی و توسعه‌دهندگان PMDA می‌توانند با افزودن دایرکتوری‌ها و/یا فایل‌های گروه جدید در زیر
.IR groupsdir ،
پیش‌فرض‌های دردسترس برای
.B pmlogconf
را به‌سادگی گسترش دهند.
.PP
این فایل‌های گروه به روش‌های زیر پردازش می‌شوند:
.IP \(bu 3n
هنگامی که یک
.I configfile
جدید ایجاد می‌شود، تمام فایل‌های گروه پردازش می‌شوند.
.IP \(bu 3n
هر زمان که
.B pmlogconf
با یک
.I configfile
موجود اجرا شود،
.I groupsdir
پیمایش می‌شود تا بررسی شود آیا گروه جدیدی تعریف شده است که باید برای گنجانده شدن در
.I configfile
در نظر گرفته شود یا خیر.
.IP \(bu 3n
هنگامی که
.B pmlogconf
گروهی را در
.I configfile
پردازش می‌کند که فعال است، فهرست معیارهای (metrics) مرتبط با آن گروه از فایل گروه گرفته می‌شود (و جایگزین هر فهرست قبلی از معیارهای مرتبط با این گروه در
.I configfile
می‌گردد).
.IP \(bu 3n
هنگامی که هر یک از گزینه‌های خط فرمان
.B \-r
(پویش مجدد یا reprobe) یا
.B \-c
(ایجاد خودکار یا auto-create) مشخص شوند، تمام گروه‌ها (نه فقط گروه‌های تازه کشف‌شده) مجدداً پردازش می‌شوند تا بررسی شود که آیا باید برای گنجانده شدن در
.I configfile
در نظر گرفته شوند یا خیر.
.IP \(bu 3n
اگر گروهی در
.I configfile
یافت شود اما گروه متناظر با آن در زیر
.I groupsdir
وجود نداشته باشد (مانند حالتی که یک گروه با ارتقای PCP منسوخ می‌شود)، نحوهٔ برخورد با آن گروه به حالتی بستگی دارد که
.I pmlogconf
در آن اجرا می‌شود. با
.B \-c
گروه متناظر از
.I configfile
حذف می‌شود، در غیر این صورت گروه متناظر در
.I configfile
بدون تغییر باقی می‌ماند. در هر دو حالت یک هشدار صادر می‌شود.
.PP
هر فایل گروه ساختاری به شرح زیر دارد:
.IP \(bu 3n
خط نخست باید شامل
.B #pmlogconf-setup 2.0
باشد.
.IP \(bu 3n
سایر خطوطی که با
.B #
آغاز می‌شوند به‌عنوان توضیح (comment) در نظر گرفته می‌شوند.
.IP \(bu 3n
خط‌های خالی نادیده گرفته می‌شوند.
.IP \(bu 3n
یک یا چند خط که با کلمهٔ کلیدی
.B ident
آغاز می‌شوند، برای ارائهٔ توضیحات خوانا برای انسان دربارهٔ گروه استفاده می‌شوند.
.IP \(bu 3n
خط‌های غیرخالی که با فاصله (white space) آغاز می‌شوند، معیارهای مرتبط با این گروه را مشخص می‌کنند، هر خط یک معیار. هر مشخصهٔ معیار از قواعد پیکربندی
.BR pmlogger (1)
پیروی می‌کند، یعنی یا نام یک گرهٔ غیربرگ در PMNS (به‌معنای تمام نام‌های فرزند در PMNS) است، یا نام یک گرهٔ برگ در PMNS که می‌تواند اختیاری با یک یا چند نام نمونه محصور در ``['' و ``]'' همراه باشد.
.IP \(bu 3n
یک خط کنترلی که با یکی از کلمات کلیدی
.B probe
یا
.B force
آغاز می‌شود باید وجود داشته باشد.
.IP \(bu 3n
یک خط کنترلی اختیاری برای بازهٔ ثبت وقایع با کلمهٔ کلیدی
.B delta
آغاز می‌شود که در ادامهٔ آن یکی از مشخصه‌های بازهٔ
.BR pmlogger (1)
که در بالا توصیف شد می‌آید.
.IP \(bu 3n
خط‌های کنترلی اختیاری معیارهای اشتقاقی با کلمهٔ کلیدی
.B define
آغاز می‌شوند و قالب زیر را دارند:
.RS 3n
.br
.ti +5n
\fBdefine\fR \fIname\fR \fIexpr\fR
.br
که در آن
.I name
نام یک معیار اشتقاقی و
.I expr
عبارت معیار اشتقاقی است. برای توضیحات نحوی و معنایی
.I name
و
.IR expr
به
.BR pmRegisterDerived (3)
مراجعه کنید.
پس از تعریف،
.I name
می‌تواند به‌عنوان
.I metric
در یک خط کنترلی بعدی
.B probe
استفاده شود که امکان بیان شروط پیچیده‌تر را برای گنجاندن مشروط معیارها در
.I configfile
فراهم می‌آورد.
.PP
توجه داشته باشید که
.I name
باید در
.B تمام
فایل‌های گروه یکتا باشد و با نام‌های موجود در PMNS تداخل نداشته باشد. بنابراین هنگام ایجاد فایل‌های گروه ممکن است نیاز به اتخاذ یک قرارداد نام‌گذاری مناسب باشد.
.RE
.IP \(bu 3n
خطوط کنترلی
.B probe
دارای این قالب هستند:
.RS 3n
.br
.ti +5n
\fBprobe\fR \fImetric\fR [\fIcondition\fR [\fIstate_rule\fR] ]
.br
که در آن
.I metric
نام یک معیار PCP است (باید یک گرهٔ برگ در PMNS باشد، هیچ مشخصهٔ نمونه‌ای مجاز نیست، و نباید یک معیار اشتقاقی باشد مگر آنکه در یک خط کنترلی قبلی
.B define
ذکر شده باشد) و
.I condition
اختیاری، کلمهٔ کلیدی
.B exists
است (در صورتی درست است که
.I metric
وجود داشته باشد، یعنی در PMNS تعریف شده باشد) یا کلمهٔ کلیدی
.B values
است (در صورتی درست است که
.I metric
در PMNS وجود داشته باشد و دارای یک یا چند مقدار فعلی باشد) یا عبارتی به فرم
.br
.ti +5n
\fIop\fR \fIval\fR
که در آن
.I op
یکی از عملگرهای
.BR awk (1)
است (\fB==\fR، \fB!=\fR، \fB>\fR، \fB>=\fR، \fB<\fR، \fB<=\fR،
\fB~\fR (تطابق عبارت باقاعده) یا
\fB!~\fR (نفی تطابق عبارت باقاعده))
و
.I val
یک مقدار است (توالی دلخواهی از نویسه‌ها به‌جز فاصله)، و
.I condition
در صورتی درست است که نمونه‌ای از
.I metric
وجود داشته باشد که عبارت را درست کند..PP
اگر
.I condition
مشخص نشده باشد، پیش‌فرض
.BR exists
است.
.PP
هنگامی که یک
.I condition
صریح ارائه شود، ممکن است یک
.I state_rule
اختیاری نیز به شکل زیر وجود داشته باشد:
.br
.ti +5n
\fB?\fR \fItrue_state\fR \fB:\fR \fIfalse_state\fR
که در آن
.I true_state
(در صورتی که
.I condition
درست باشد اعمال می‌شود) و
.I false_state
(در صورتی که
.I condition
نادرست باشد اعمال می‌شود) هر دو از کلمات کلیدی زیر انتخاب می‌شوند:
.B include
(گنجاندن و فعال‌سازی گروه و معیارهای مرتبط در
.IR configfile )،
.B available
(گنجاندن و غیرفعال‌سازی گروه در
.I configfile
\- اقدام کاربر با
.BR y ،
همان‌طور که در بالا در حالتی که
.I configfile
از پیش موجود باشد شرح داده شد، برای فعال‌سازی گروه و افزودن معیارهای مرتبط به
.IR configfile
مورد نیاز است)
یا
.B exclude
(گروه برای گنجانده شدن در
.IR configfile
در نظر گرفته نمی‌شود).
.PP
قانون
.I state_rule
پیش‌فرض عبارت است از:
.br
.ti +5n
.ft B
? available : exclude
.ft R
.RE
.IP \(bu 3n
خطوط کنترلی
.B force
با کلمه کلیدی
.B force
آغاز می‌شوند و به دنبال آن یکی از وضعیت‌های تعریف‌شده در بالا می‌آید، بنابراین یکی از اقدامات
.BR include ،
.B exclude
یا
.B available
بدون قید و شرط بر روی گروه اعمال می‌گردد.
.PP
کاوش (probing) تنها زمانی انجام می‌شود که یک گروه جدید به
.I configfile
اضافه شود یا زمانی که گزینه خط فرمان
.B \-r
مشخص شده باشد. ارزیابی شرایط کاوش از طریق برقراری ارتباط با
.BR pmcd (1)
روی
.I hostname
(پیش‌فرض :local) صورت می‌گیرد.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های خط فرمان موجود عبارتند از:
.TP 5
\fB\-c\fR
فعال‌سازی حالت غیرتعاملی و ساخت خودکار (auto-create).
.TP
\fB\-d\fR \fIgroupsdir\fR, \fB\-\-groups\fR=\fIgroupsdir\fR
مسیر دایرکتوری \fIgroupsdir\fP را مشخص می‌کند.
.TP
\fB\-g\fR \fIgrouptag\fR, \fB\-\-group\fR=\fIgrouptag\fR
پرس‌وجوی وضعیت لاگ‌گیری برای گروه لاگ‌گیری خاص با نام \fIgrouptag\fP.
.TP
\fB\-h\fR \fIhost\fR, \fB\-\-host\fR=\fIhost\fR
منبع معیارهای عملکرد به جای localhost پیش‌فرض،
.BR pmcd (1)
بر روی
.IR host
است.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
حالت بی‌صدا؛ فرونشاندن دیالوگ بازه زمانی لاگ‌گیری.
.TP
\fB\-r\fR, \fB\-\-reprobe\fR
بررسی مجدد تمامی گروه‌ها جهت گنجاندن در \fIconfigfile\fP.
.TP
\fB\-s\fR \fIgroupfile\fR, \fB\-\-setup\fR=\fIgroupfile\fR
گزارش وضعیت لاگ‌گیری پیش‌فرض برای گروه لاگ‌گیری درون \fIgroupfile\fP.
این خروجی معادل خروجی تولیدشده توسط اسکریپت شل از رده خارج
.B pmlogconf-setup
در نسخه‌های قبلی PCP است.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
فعال‌سازی حالت پرگو (verbose).
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش شماره نسخه و خروج.
.TP
\fB\-?\fR, \fB\-\-help\fR
نمایش پیام راهنمای استفاده و خروج..SH "مثال‌ها (EXAMPLES)"
فایل گروهیِ زیر بیشتر عناصر نحویِ پشتیبانی‌شده را نمایش می‌دهد.
.PP
.ft CR
.nf
#pmlogconf-setup 2.0
ident   Example group file
ident   ... more description
delta   1 minute
probe   sample.secret.foo.one values ? include : exclude
        sample.secret.foo.one
        sample.secret.foo.bar   # non-leaf in the PMNS
        sample.colour [ red green ]
.fi
.ft
.PP
در مثال زیر (بک‌اسلش‌ها برای خوانایی بیشتر اضافه شده‌اند، عبارت
.B define
کاملاً در یک خط قرار دارد)، اگر معیار \f(CRmumble.foo\fP شناخته‌شده باشد و حداقل یک نمونه (و مقدار) داشته باشد، یا اگر معیار \f(CRmumble.bar\fP شناخته‌شده باشد و حداقل یک نمونه (و مقدار) داشته باشد، معیارهای
\f(CRmumble\fP
در
.I configfile
گنجانده خواهند شد:
.PP
.ft CR
.nf
#pmlogconf-setup 2.0
ident   Derived metric example with alternation
define  mumble.check = \e
            (defined(mumble.foo) ? count(mumble.foo) : 0) + \e
            (defined(mumble.bar) ? count(mumble.bar) : 0)
probe   mumble.check > 0 ? include : exclude
        mumble
.fi
.ft
.PP
مثال زیر از یک معیار مشتق‌شده برای دسترسی به یک نمونهٔ خاص از معیار در یک سطر کنترلی
.B probe
استفاده می‌کند.
.PP
.ft CR
.nf
#pmlogconf-setup 2.0
ident   Derived metric example using a single metric instance
define  fumble_log = fumble.control[verbose_log]
probe   fumble_log > 0 ? include : exclude
        fumble.detailed
.fi
.ft
.SH "مهاجرت (MIGRATION)"
نسخهٔ فعلی
.B pmlogconf
(2.0)
در مقایسه با نسخه‌های پیشین، از قالب کمی متفاوتی برای
.I configfile
پشتیبانی می‌کند. اگر یک
.I configfile
نسخهٔ قدیمی به
.B pmlogconf
ارائه شود، به قالب جدید تبدیل خواهد شد.
.SH "محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند \fBPCP_\fP برای مقداردهی و پارامتریک‌سازی نام فایل‌ها و دایرکتوری‌های مورد استفاده توسط PCP به کار می‌روند.
در هر نصب، فایل \fI/etc/pcp.conf\fP حاوی مقادیر محلی برای این متغیرها است.
متغیر \fB$PCP_CONF\fP ممکن است برای تعیین یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در \fBpcp.conf\fP(5) توضیح داده شده است.
.PP
.B pmlogconf
به دلایل کارایی و برای جلوگیری از گنجانده شدن معیارهای مشتق‌شده در
.IR configfile ،
هرگونه متغیر محیطی
.B $PCP_DERIVED_CONFIG
را با یک رشتهٔ خالی بازنویسی می‌کند.
.PP
.B pmlogconf
هنگام کاوش و ایجاد فایل‌های پیکربندی جدید
.B pmlogger
متغیر محیطی
.B $PMCD_WAIT_TIMEOUT
را رعایت می‌کند.
در صورت عدم تنظیم این متغیر در محیط، از مقدار پیش‌فرض ۱۰ ثانیه برای مهلت زمانی استفاده می‌شود..SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینهٔ
.B \-D
یا
.B \-\-debug
خروجی داده‌های تشخیصی اضافی را روی
.I stderr
فعال می‌کند تا به تفکیک و ارزیابی مشکلات کمک کند، اگرچه این اطلاعات گاهی مبهم است و در وهله اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی.
.I debug
فهرستی از گزینه‌های اشکال‌زدایی جداشده با کاما است؛ از
.BR pmdbg (1)
به همراه گزینهٔ
.B \-l
برای به‌دست آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و معنی آن‌ها استفاده کنید.
.SH "گزینه‌های اشکال‌زدایی (DEBUGGING OPTIONS)"
گزینهٔ
.B \-D
یا
.B \-\-debug
خروجی داده‌های تشخیصی اضافی را روی
.I stderr
فعال می‌کند تا به تفکیک و ارزیابی مشکلات کمک کند، اگرچه این اطلاعات گاهی مبهم است و در وهله اول برای راهنمایی توسعه‌دهندگان در نظر گرفته شده تا کاربران نهایی.
.I debug
فهرستی از گزینه‌های اشکال‌زدایی جداشده با کاما است؛ از
.BR pmdbg (1)
به همراه گزینهٔ
.B \-l
برای به‌دست آوردن فهرستی از گزینه‌های اشکال‌زدایی موجود و معنی آن‌ها استفاده کنید.
.PP
گزینه‌های اشکال‌زدایی مختص
.B pmlogconf
به شرح زیر هستند:
.TS
box;
lf(B) | lf(B)
lf(B) | lf(R) .
گزینه	توضیحات
_
appl0	عملیات‌های فایل گروه
_
appl1	عملیات‌های کاوش متریک
_
appl2	تخلیهٔ کامل و پرجزئیات ساختارهای دادهٔ گروهی داخلی
.TE
.SH "همچنین ببینید (SEE ALSO)"
.BR pmcd (1)،
.BR pmlogger (1)،
.BR PMAPI (3)،
.BR pmRegisterDerived (3)،
.BR pcp.conf (5)
و
.BR pcp.env (5).

.\" control lines for scripts/man-spell
.\" +ok+ false_state groupfile groupsdir
.\" +ok+ grouptag ident op state_rule true_state val