'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 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 PMIECONF 5 "PCP" "Performance Co-Pilot"
.SH "نام (NAME)"
\f3pmieconf\f1 \- قواعد تعمیم‌یافته و سفارشی‌سازی‌های pmie
.SH "توضیحات (DESCRIPTION)"
قالب‌های فایل pmieconf توسط ابزار
.BR pmieconf (1)
به عنوان روشی برای تعمیم مجموعه‌قواعد
.BR pmie (1)
استفاده می‌شوند تا بتوان آن‌ها را به‌راحتی برای سیستم‌ها و محیط‌های گوناگون پیکربندی کرد.
در اینجا دو قالب فایل کاملاً متفاوت (اگرچه بسیار مرتبط) مورد بحث قرار می‌گیرند، یعنی «pmieconf-rules» و «pmieconf-pmie».
.PP
دایرکتوری
.B $PCP_VAR_DIR/config/pmieconf
حاوی اطلاعاتی درباره تمام قواعد و متغیرهای تعمیم‌یافته پیش‌فرض سیستم برای
.B pmie
است، از جمله مقادیر پیش‌فرض برای تمام متغیرها.
این فایل‌ها در قالب pmieconf-rules هستند.
اگرچه می‌توان فایل‌های جدید pmieconf-rules را اضافه کرد، اما فایل‌های موجود در این دایرکتوری نباید هرگز تغییر داده شوند.
در عوض، از ابزار
.B pmieconf
برای تغییر مقادیر متغیرها در فایل پیکربندی
.B pmie
استفاده کنید.
.PP
قالب pmieconf-pmie امکان سفارشی‌سازی‌های خاص سیستم را برای قواعد موجود در فایل‌های pmieconf-rules و متغیرهای مرتبط با آن‌ها فراهم می‌کند.
قالب pmieconf-pmie توسط
.B pmieconf
تولید می‌شود و نباید به صورت دستی ویرایش شود.
این فایل تولیدشده در قالب
.B pmie
است، همراه با مقداری اطلاعات اضافی که در ابتدای فایل نگهداری می‌شود \- بنابراین، قالب pmieconf-pmie یک ابرمجموعه از قالب فایل
.B pmie
است (گسترش‌یافته برای نگهداری سفارشی‌سازی‌های قواعد تعمیم‌یافته، اما در عین حال شامل قواعد کارایی واقعی برای ارزیابی توسط
.BR pmie )
که توسط
.B pmie
نیز قابل تجزیه است (تمام افزونه‌ها درون توضیحات پنهان شده‌اند و در نتیجه برای خود
.B pmie
بی‌معنی هستند).
.PP
فایل
.B $PCP_VAR_DIR/config/pmieconf/config.pmie
حاوی تنظیمات محلی سیستم برای متغیرهای قابل‌پیکربندی
.B pmieconf
است.
تنظیمات متغیر در این فایل جایگزین مقادیر پیش‌فرض مشخص‌شده در
.B $PCP_VAR_DIR/config/pmieconf/*/*
می‌شوند.
.SH "ساختار PMIECONF-PMIE (PMIECONF-PMIE SYNTAX)"
تمام خطوط سفارشی‌سازی قواعد در یک مشخصات معتبر pmieconf-pmie با «//» شروع می‌شوند و در ابتدای فایل قرار دارند \- این ویژگی به فایل‌های حاوی مشخصات pmieconf-pmie اجازه می‌دهد تا با موفقیت توسط
.B pmie
تجزیه شوند.
یک فایل pmieconf-pmie باید همیشه خط اولی به شکل زیر داشته باشد:
.sp
.nf
    // pmieconf-pmie \f2version\f1 \f2pmieconf_path\f1
.fi
.sp
مقدار
.I version
مشخص می‌کند که کدام نسخه از ساختار pmieconf-pmie باید برای تجزیه این فایل استفاده شود.
در حال حاضر تنها نسخه پشتیبانی‌شده 1 است.
مقدار
.I pmieconf_path
مسیری را به فایل‌های pmieconf-rules مشخص می‌کند که توسط
.B pmieconf
برای تولید این فایل استفاده شده‌اند. این موضوع در صفحه راهنمای
.BR pmieconf (1)
مورد بحث قرار گرفته است (گزینه
.B \-r
را ببینید).
.PP
بقیه مشخصات شامل ورودی‌های تک‌خطی برای هر یک از متغیرهای تغییریافته است. ساختار هر خط به صورت زیر است:
.sp
.nf
    // \f2rule_version\f1 \f2rule_name\f1 \f2rule_variable\f1 = \f2value\f1
.fi
.sp
پارامترهای
.I rule_version
و
.I rule_name
برای شناسایی قاعده‌ای که سفارشی‌سازی باید با آن مرتبط شود استفاده می‌شوند.
به دنبال این‌ها نام
.I rule_variable
(یعنی متغیر قاعده
.I rule_name
که تغییر کرده است)
می‌آید که مقدار جدید
.I value
باید برای آن اعمال شود.
.PP
یک مشخصات pmieconf-pmie باید با کلمه کلیدی «end» خاتمه یابد.
این کلمه توسط
.B pmieconf
برای تشخیص جایی که سفارشی‌سازی‌ها پایان می‌یابند و مؤلفه قاعده واقعی
.B pmie
آغاز می‌شود، استفاده می‌گردد.
.SH "مثال PMIECONF-PMIE (PMIECONF-PMIE EXAMPLE)"
مثال زیر یک فایل معتبر با قالب pmieconf-pmie است که توسط
.B pmieconf
تولید شده است.
به منظور اعمال تغییرات دستی به گونه‌ای که توسط
.B pmieconf
حفظ شوند، به توضیحات موجود در فایل تولیدشده (در زیر) در مورد محل انجام چنین تغییراتی مراجعه کنید.
.sp
.nf
    // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf
    // 1 memory.exhausted delta = "4 minutes"
    // 1 memory.exhausted enabled = yes
    // 1 memory.exhausted pcplog_action = yes
    // end
    //
    // --- START GENERATED SECTION (do not change this section) ---
    //     generated by pmieconf on:  [DATESTAMP]
    //

    // 1 memory.exhausted
    delta = 4 minutes;
    some_host (
        ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&
        30 %_sample swap.pagesout >= 5
    ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \\
            " %vpgsout/s@%h";

    // --- END GENERATED SECTION (changes below will be preserved) ---
.fi
.sp
.PP
برای مشاهده نحوه عملکرد این فرایند، می‌توانید این فایل را به صورت زیر تولید کنید:
.sp
.nf
    # cat \- | pmieconf \-f /tmp/pmieconf.out \\
        \-r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global
    modify memory.exhausted delta "4 minutes"
    modify memory.exhausted enabled yes
    modify memory.exhausted pcplog_action yes
    ^D
    #
.fi
.sp
سپس با استفاده از دستور زیر بررسی کنید که فایل تولیدشده یک فایل پیکربندی معتبر
.B pmie
است:
.sp
.nf
    # pmie \-C /tmp/pmieconf.out
.fi
.sp
این دستور فایل را تجزیه کرده و پس از گزارش هرگونه خطای نحوی خارج می‌شود.
اکنون \-C را با \-v (در بالا) جایگزین کنید و عملکرد
.B pmie
را مشاهده نمایید!
.SH "ساختار PMIECONF-RULES (PMIECONF-RULES SYNTAX)"
یک مشخصات pmieconf-rules شامل تعدادی شیء داده‌ای مجزا است که با هم یک مشخصات کامل قاعده را تشکیل می‌دهند (توجه داشته باشید که یک مشخصات ممکن است در چندین فایل و حتی چندین زیردایرکتوری گسترده شده باشد).
هر شیء باید یک رشته شناسه
.RI ( identifier )
و یک نوع داده
.RI ( type )
داشته باشد که پس از آن فهرستی (اختیاری) از ویژگی‌ها
.RI ( attribute ها)
قرار می‌گیرد.
.PP
ساختار کلی یک شیء pmieconf-rules به صورت زیر است:
.sp
.nf
    \f2type\f1 \f2identifier\f1 [ \f2attribute\f1 = \f2value\f1 ]* ;
.fi
.sp
مجموعه
.IR type های
معتبر عبارتند از: "rule" (تعریف قاعده)، "string" (رشته دلخواه درون گیومه)، "double"، "integer"، "unsigned"، "percent" (عدد حقیقی بین 0 و 100)، "hostlist" (فهرستی از نام‌های میزبان که با فاصله جدا شده‌اند)، "instlist" (فهرستی از نام‌های نمونه معیار که با فاصله جدا شده‌اند)، و چهار نوع کنش
.BR pmie ،
یعنی "print"، "shell"، "alarm"، و "syslog".
.PP
نام‌های قواعد از نویسه «.» برای معرفی مفهوم گروه قاعده استفاده می‌کنند، به عنوان مثال "memory.exhausted" این قاعده را با گروه "memory" مرتبط می‌کند.
.B pmieconf
می‌تواند در سطح گروه‌های قواعد یا قواعد منفرد عمل کند.
نام گروه "global" رزرو شده است و نباید برای هیچ قاعده‌ای استفاده شود.
.PP
معمولاً هنگامی که یک شیء ایجاد می‌شود، با قاعده فعلی مرتبط است.
با این حال، اگر نام یک شیء با نام گروه رزروشده "global" آغاز شود، آن شیء برای همه قواعد قابل مشاهده خواهد بود.
.PP
مجموعه
.IR attribute های
معتبر عبارتند از: "help" (متن توضیحی درباره این شیء)، "modify" (مقدار \f2value\f1 برابر با yes/no است، و مشخص می‌کند آیا
.B pmieconf
باید اجازه تغییرات را بدهد یا خیر)، "enabled" (مقدار \f2value\f1 برابر با yes/no است، و روشن یا خاموش بودن را مشخص می‌کند \- تنها برای قواعد و کنش‌ها معنادار است)، "display" (مقدار yes/no \- مشخص می‌کند آیا
.B pmieconf
باید این شیء را نمایش دهد یا خیر)، "default" (مقدار \f2value\f1 با توجه به \f2type\f1 تعیین می‌شود و مقدار پیش‌فرض این شیء است)، و ویژگی‌های مختص اشیاء از نوع قاعده شامل "version"، "predicate" و "enumerate".
ویژگی‌های "version" و "predicate" کاملاً واضح هستند ("predicate" در زمان بسط باید با یک قاعده معتبر
.B pmie
مطابقت داشته باشد)، اما "enumerate" نیاز به توضیح بیشتری دارد.
.PP
بند "enumerate" زمانی مفید است که می‌خواهید چندین قاعده مشابه
.B pmie
را از یک گزاره (predicate) واحد تولید کنید.
این قابلیت بیش از همه برای تعاریف قواعدی مفید است که می‌خواهند از بند "some_inst" در زبان
.B pmie
در چندین میزبان استفاده کنند.
برای اینکه یک قاعده بتواند از این‌ها با هم استفاده کند، باید مطمئن بود که فهرست نمونه‌ها در تمام میزبان‌های تحت نظارت یکسان است.
از آنجا که این موضوع به ندرت صادق است، ویژگی "enumerate" به ما اجازه می‌دهد چندین قاعده تولید کنیم که بر روی متغیرهایی از نوع "instlist" یا "hostlist" بسط داده می‌شوند.
این متغیرها مقدار ویژگی "enumerate" را تشکیل می‌دهند \- که فهرستی از نام‌های متغیر "instlist" یا "hostlist" است که با فاصله از هم جدا شده‌اند.
.PP
اشیاء می‌توانند با استفاده از ساختار $\f2identifier\f1$ در تعاریف سایر اشیاء گنجانده شوند. برای درک بهتر کاربرد این مورد، به مثال زیر مراجعه کنید.
.PP
هنگامی که
.B pmieconf
در حال تولید فایل پیکربندی
.B pmie
است، به هر قاعده فعال با N کنش فعال (که در آن N > 0 است) نگاه می‌کند و رشته زیر را بسط می‌دهد:
.sp
.nf
    // "version" \f2identifier\f1
    delta = $delta$;
    "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
.fi
.sp
متغیرهای delta، threshold و action به صورت سراسری (با استفاده از کلمه کلیدی "global") برای همه قواعد تعریف شده‌اند، اما البته می‌توان آن‌ها را در سطح یک قاعده منفرد یا یک گروه قاعده تغییر داد.
.SH "مثال PMIECONF-RULES (PMIECONF-RULES EXAMPLE)"
در ادامه مثالی از یک مشخصات pmieconf-rules آورده شده است که جنبه‌های مختلف زبان مورد بحث در بالا را نشان می‌دهد.
این مثال یک قاعده ("memory.exhausted") و یک رشته ("rule") را تعریف می‌کند.
.sp
.nf
    rule    memory.exhausted
            default = "$rule$"
            predicate =
    "some_host (
        ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&
        $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$
    )"
            enabled = yes
            version = 1
            help    =
    "The system is swapping modified pages out of main memory to the
    swap partitions, and has been doing this on at least pct of the
    last 10 evaluations of this rule.
    There appears to be insufficient main memory to meet the resident
    demands of the current workload.";

    string  rule
            default = "Severe demand for real memory"
            modify  = no
            display = no;
.fi
.sp
توجه داشته باشید برای اینکه قاعده بالا کامل باشد، "threshold" و "pct" نیز باید تعریف شوند \- برای عبارت کامل این قاعده، به
.I $PCP_VAR_DIR/config/pmieconf/memory/exhausted
مراجعه کنید.
.SH "فایل‌ها (FILES)"
.PD 0
.TP 10
.IR $PCP_VAR_DIR/config/pmieconf/ */*
قواعد تعمیم‌یافته نظارت بر منابع سیستم
.TP 10
.I $PCP_VAR_DIR/config/pmieconf/config.pmie
تنظیمات پیش‌فرض کاربر ارشد (superuser) برای قواعد نظارت بر منابع سیستم
.TP 10
.I $HOME/.pcp/pmie/config.pmie
تنظیمات پیش‌فرض کاربر برای قواعد نظارت بر منابع سیستم
.PD
.SH "همچنین ببینید (SEE ALSO)"
.BR pmie (1)
و
.BR pmieconf (1).