1PMIECONF(1)                 General Commands Manual                PMIECONF(1)
2
3
4
5
6

NAME

8       pmieconf - display and set configurable pmie rule variables
9

SYNOPSIS

11       pmieconf [-cFv] [-f file] [-r rulepath] [command [args...]]
12

DESCRIPTION

14       pmieconf is a utility for viewing and configuring variables from gener‐
15       alized pmie(1) rules.  The set of generalized rules  is  read  in  from
16       rulepath,  and  the  output  file produced by pmieconf is a valid input
17       file for pmie.
18
19       A brief description of the pmieconf command line options follows:
20
21       -c      When run from automated pmie setup processes,  this  option  is
22               used  to  add  a specific message and timestamp indicating that
23               this is the case.  It is not appropriate when  using  the  tool
24               interactively.
25
26       -f file Any  rule modifications resulting from pmieconf manipulation of
27               variable values will be written to file.  The default value  of
28               file  is dependent on the user ID - for the root user, the file
29               $PCP_VAR_DIR/config/pmieconf/config.pmie  is  used,  for  other
30               users the default is $HOME/.pcp/pmie/config.pmie.
31
32       -F      Forces  the  pmieconf  output  file to be created (or updated),
33               after which pmieconf immediately exits.
34
35       -r rulepath
36               Allows the source of generalized pmie rules  to  be  changed  -
37               rulepath  is  a  colon-delimited list of pmieconf(5) rule files
38               and/or subdirectories.   The  default  value  for  rulepath  is
39               $PCP_VAR_DIR/config/pmieconf.  Use of this option overrides the
40               PMIECONF_PATH environment variable which has  a  similar  func‐
41               tion.
42
43       -v      Verbose mode.  Additional information associated with each rule
44               and its associated variables will be displayed.   This  is  the
45               complete  list  of  variables  which affects any given rule (by
46               default, global variables are not displayed with the rule).
47
48       The pmieconf commands allow information related to  the  various  rules
49       and configurable variables to be displayed or modified.  If no pmieconf
50       commands are presented on the command line, pmieconf prompts  for  com‐
51       mands interactively.
52
53       The pmieconf command language is described here:
54
55       help  [ { . | all | global | <rule> | <group> } [<variable>] ]
56               Without arguments, the help command displays the syntax for all
57               of the available  pmieconf  commands.   With  one  argument,  a
58               description  of  one  or  more of the generalized rules is dis‐
59               played.  With two arguments, a description of a specific  vari‐
60               able  relating  to one or more of the generalized rules is dis‐
61               played.
62
63       rules  [ enabled | disabled ]
64               Display the name and short summary for all of  the  generalized
65               rules found on rulepath.  Each of the rule names can be used in
66               place of the keyword <rule> in this command syntax description.
67               The  enabled and disabled options can be used to filter the set
68               of rules displayed to just those which are enabled or  disabled
69               respectfully.
70
71       groups  Display  the  name of all of the rule groups that were found on
72               rulepath.  Each of the group names can be used in place of  the
73               keyword  <group>  in  this  command  syntax  description, which
74               applies the command to all rules within the rule group.
75
76       status  Display status information relating  to  the  current  pmieconf
77               session,  including  a list of running pmie processes which are
78               currently using file.
79
80       enable  { . | all | <rule> | <group> }
81               Enables the specified rule or group of rules.  An enabled  rule
82               is  one  which  will be included in the pmie configuration file
83               generated by pmieconf.  Any enabled "actions" will be  appended
84               to  the  rule's "predicate", in a manner conforming to the pmie
85               syntax ("actions" can be viewed using the list global  command,
86               described below).
87
88       disable  { . | all | <rule> | <group> }
89               Disables the specified rule or group of rules.  If the rule was
90               previously enabled, it will be removed from the pmie configura‐
91               tion  file generated by pmieconf, and hence no longer evaluated
92               when pmie is restarted (using  pmieconf  does  not  affect  any
93               existing pmie processes using file).
94
95       list  { . | all | global | <rule> | <group> } [<variable>]
96               Display  the  values  for  a specific rule variable; or for all
97               variables of a rule, a rule group, all  rules,  or  the  global
98               variables.
99
100       modify  { . | all | global | <rule> | <group> } <variable> <value>
101               Enable,  disable, or otherwise change the value for one or more
102               rule variables.  This value must be consistent with the type of
103               the  variable,  which  can  be  inferred from the format of the
104               printed value - e.g. strings will be enclosed in double-quotes,
105               percentages  have  the  ``%''  symbol appended, etc.  Note that
106               certain rule variables cannot be modified  through  pmieconf  -
107               "predicate" and "help", for example.
108
109       undo  { . | all | global | <rule> | <group> } [<variable>]
110               Applicable  only  to a variable whose value has been modified -
111               this command simply reverts to the default value for the  given
112               variable.
113
114       quit    Save any changes made to file and then exit pmieconf.
115
116       abort   Exit pmieconf immediately without saving any changes to file.
117
118       Each  of  the commands above can be shortened by simply using the first
119       character of the command name, and also ``?'' for help.
120
121       Use of the all keyword causes the command to be applied to all  of  the
122       rules.   The global keyword refers to those variables which are applied
123       to every rule.  Such  variables  can  be  changed  either  globally  or
124       locally, for example:
125
126         pmieconf> modify global delta "5 minutes"
127         pmieconf> modify memory delta "1 minute"
128
129       causes  all  rules  to now be evaluated once every five minutes, except
130       for rules in the "memory" group which are  to  be  evaluated  once  per
131       minute.
132
133       The ``.'' character is special to pmieconf - it refers to the last suc‐
134       cessfully used value of all, global, <rule> or <group>.
135

EXAMPLES

137       Specify that all of the rules in the "memory" group  should  be  evalu‐
138       ated:
139
140         pmieconf> modify memory enabled yes
141
142       Change  your  mind,  and  revert to using only the "memory" rules which
143       were enabled by default:
144
145         pmieconf> undo memory enabled
146
147       Specify that notification of rules which evaluate  to  true  should  be
148       sent to syslogd(1):
149
150         pmieconf> modify global syslog_action yes
151
152       Specify  that rules in the "per_cpu" group should use a different hold‐
153       off value to other rules:
154
155         pmieconf> help global holdoff
156           rule: global  [generic parameters applied to all rules]
157            var: holdoff
158           help: Once the predicate is true and the action is executed,
159              this variable allows suppression of further action
160              execution until the specified interval has elapsed.
161              A value of zero enables execution of the action if
162              the rule predicate is true at the next sample. Default
163              units are seconds and common units are "second", "sec",
164              "minute", "min" and "hour".
165
166         pmieconf> modify per_cpu holdoff "1 hour"
167
168       Lower the threshold associated with a particular variable for a  speci‐
169       fied rule:
170
171         pmieconf> l cpu.syscall predicate
172           rule: cpu.syscall  [High aggregate system call rate]
173             predicate =
174                  some_host (
175                   ( kernel.all.syscall $hosts$ )
176                     > $threshold$ count/sec * hinv.ncpu $hosts$
177                  )
178
179         pmieconf> m . threshold 7000
180
181         pmieconf> l . threshold
182           rule: cpu.syscall  [High aggregate system call rate]
183                threshold = 7000
184
185

ENVIRONMENT

187       The environment variable PMIECONF_PATH has a similar function to the -r
188       option described above, and if set will be used provided no  -r  option
189       is presented.
190

FILES

192       $PCP_VAR_DIR/config/pmieconf/*/*
193                 generalized system resource monitoring rules
194       $PCP_VAR_DIR/config/pmieconf/config.pmie
195                 default  super-user  settings  for system resource monitoring
196                 rules
197       $HOME/.pcp/pmie/config.pmie
198                 default user settings for system resource monitoring rules
199

PCP ENVIRONMENT

201       Environment variables with the prefix PCP_ are used to parameterize the
202       file  and  directory names used by PCP.  On each installation, the file
203       /etc/pcp.conf contains the  local  values  for  these  variables.   The
204       $PCP_CONF  variable may be used to specify an alternative configuration
205       file, as described in pcp.conf(5).
206

SEE ALSO

208       PCPIntro(1), pmie(1), pmie_check(1) and pmieconf(5).
209
210
211
212Performance Co-Pilot                  PCP                          PMIECONF(1)
Impressum