pmieconf(5) — Linux manual page

NAME | DESCRIPTION | PMIECONF-PMIE SYNTAX | PMIECONF-PMIE EXAMPLE | PMIECONF-RULES SYNTAX | PMIECONF-RULES EXAMPLE | FILES | SEE ALSO | COLOPHON

PMIECONF(5)                File Formats Manual               PMIECONF(5)

NAME         top

       pmieconf - generalized pmie rules and customizations

DESCRIPTION         top

       The pmieconf file formats are used by the pmieconf(1) tool as a
       way to generalize pmie(1) rule sets such that they can be easily
       configured for different systems and different environments.
       There are two completely different (although closely related)
       file formats discussed here, namely ``pmieconf-rules'' and
       ``pmieconf-pmie''.

       The directory $PCP_VAR_DIR/config/pmieconf contains information
       about all the default system pmie generalized rules and
       variables, including default values for all variables.  These
       files are in the pmieconf-rules format.  Although new pmieconf-
       rules files can be added, the files in this directory should
       never be changed.  Instead, use the pmieconf utility to change
       variable values in the pmie configuration file.

       The pmieconf-pmie format allows site specific customizations of
       the rules contained in pmieconf-rules files and their associated
       variables.  The pmieconf-pmie format is generated by pmieconf and
       should not be edited by hand.  This generated file is in the pmie
       format, with some additional information held at the head of the
       file - thus, the pmieconf-pmie format is a superset of the pmie
       file format (extended to hold customizations to the generalized
       rules, but also containing the actual performance rules for pmie
       to evaluate) which can also be parsed by pmie (all extensions are
       hidden within comments, and are thus meaningless to pmie itself).

       The file $PCP_VAR_DIR/config/pmieconf/config.pmie contains local
       system settings for pmieconf configurable variables.  The
       variable settings in this file replace the default values
       specified in $PCP_VAR_DIR/config/pmieconf/*/*.

PMIECONF-PMIE SYNTAX         top

       All rule customization lines in a valid pmieconf-pmie
       specification are prefixed by ``//'' and are located at the head
       of the file - this allows files containing a pmieconf-pmie
       specification to be successfully parsed by pmie.  A pmieconf-pmie
       must always have the first line in the form:

           // pmieconf-pmie version pmieconf_path

       The version specifies which version of the pmieconf-pmie syntax
       should be used to parse this file.  Currently the only supported
       version is 1.  The pmieconf_path specifies the path to the
       pmieconf-rules files which were used, by pmieconf, to generate
       this file.  This is discussed in the pmieconf(1) man page (see
       the -r option).

       The remainder of the specification consists of one line entries
       for each of the modified variables.  The syntax for each line is:

           // rule_version rule_name rule_variable = value

       The rule_version and rule_name are used to identify the rule with
       which to associate the customization.  These are followed by the
       rule_variable name (i.e. the variable of rule rule_name which has
       been changed) for which the new value is to be used.

       A pmieconf-pmie specification must be terminated with the ``end''
       keyword.  This is used by pmieconf to distinguish where the
       customizations ends, and the actual pmie rule component begins.

PMIECONF-PMIE EXAMPLE         top

       The following example is a valid pmieconf-pmie format file, as
       generated by pmieconf.  In order to make changes by hand which
       are preserved by pmieconf, see the comments contained in the
       generated file (below) as to where such changes should be made.

           // 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) ---

       To see how this all works, you can generate this file as follows:

           # 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
           #

       Then verify that the generated file is a valid pmie configuration
       file using:

           # pmie -C /tmp/pmieconf.out

       This parses the file, and then exits after reporting any syntax
       errors.  Now replace -C with -v (above), and watch pmie do its
       work!

PMIECONF-RULES SYNTAX         top

       A pmieconf-rules specification consists of a number of separate
       data objects which together form a complete rule specification
       (note that a specification may span multiple files and even
       multiple subdirectories).  Each object must have an identifier
       string and a data type, followed by an (optional) list of
       attributes.

       The generic specification of a pmieconf-rules object is thus:

           type identifier [ attribute = value ]* ;

       The set of valid types is: "rule" (rule definition), "string"
       (arbitrary, double-quote enclosed string), "double", "integer",
       "unsigned", "percent" (real number between 0 and 100), "hostlist"
       (space separated list of host names), "instlist" (space separated
       list of metric instance names), and the four pmie action types,
       namely "print", "shell", "alarm", and "syslog".

       Rule names use the ``.'' character to introduce the concept of a
       rule group, e.g. "memory.exhausted" associates this rule with the
       "memory" group.  pmieconf can operate at either the level of rule
       groups or individual rules.  The group name "global" is reserved
       and may not be used with any rule.

       Usually when an object is created it is associated with the
       current rule.  However, if an object's name is preceded by the
       reserved group name "global", then that object is visible to all
       rules.

       The set of valid attributes is: "help" (descriptive text about
       this object), "modify" (value is yes/no, flags whether pmieconf
       should allow changes), "enabled" (value is yes/no, flags whether
       this is on or off - only meaningful for rules and actions),
       "display" (yes/no - flags whether pmieconf should show this
       object), "default" (value determined by type, and is the default
       value for this object), and specific to objects of rule type are
       the "version", "predicate", and "enumerate" attributes.
       "version" and "predicate" are fairly self explanatory
       ("predicate" must equate to a valid pmie rule when expanded), but
       "enumerate" requires further discussion.

       The "enumerate" clause is useful when you wish to generate
       multiple, similar pmie rules from a single predicate.  This is
       most useful for rule definitions wishing to use the "some_inst"
       clause in the pmie language across multiple hosts.  For a rule to
       use these together, it must be certain that the instance list is
       the same on all of the monitored hosts.  This is rarely true, so
       the "enumerate" attribute allows us to generate multiple rules,
       expanded over variables of either type "instlist" or "hostlist".
       These variables make up the value for the "enumerate" attribute -
       which is a space-separated list of "instlist" or "hostlist"
       variable names.

       Objects can be incorporated into other object definitions using
       the $identifier$ syntax.  See the example later for more insight
       into how this is useful.

       When pmieconf is generating the pmie configuration file, it looks
       at each enabled rule with N enabled actions (where N > 0) and
       expands the string:

           // "version" identifier
           delta = $delta$;
           "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;

       The delta, threshold, and action variables are defined globally
       (using the "global" keyword) for all rules, but can, of course,
       be changed at the level of an individual rule or rule group.

PMIECONF-RULES EXAMPLE         top

       The following is an example of a single pmieconf-rules
       specification, showing a number of different aspects of the
       language discussed above.  The example defines a rule
       ("memory.exhausted") and a string ("rule").

           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;

       Note that for the above rule to be complete, "threshold" and
       "pct" would also need to be defined - for the full expression of
       this rule, refer to
       $PCP_VAR_DIR/config/pmieconf/memory/exhausted.

FILES         top

       $PCP_VAR_DIR/config/pmieconf/*/*
              generalized system resource monitoring rules
       $PCP_VAR_DIR/config/pmieconf/config.pmie
              default super-user settings for system resource monitoring
              rules
       $HOME/.pcp/pmie/config.pmie
              default user settings for system resource monitoring rules

SEE ALSO         top

       pmie(1) and pmieconf(1).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to pcp@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot               PCP                       PMIECONF(5)

Pages that refer to this page: pcpintro(1)pmieconf(1)