1PMDAPROC(1)                 General Commands Manual                PMDAPROC(1)
2
3
4

NAME

6       pmdaproc - process performance metrics domain agent (PMDA)
7

SYNOPSIS

9       $PCP_PMDAS_DIR/proc/pmdaproc [-AL] [-d domain] [-l logfile] [-r cgroup]
10       [-U username]
11

DESCRIPTION

13       pmdaproc is a Performance Metrics Domain Agent  (PMDA)  which  extracts
14       performance  metrics  describing  the state of the individual processes
15       running on a Linux system.
16
17       The proc PMDA exports metrics that measure the  memory,  processor  and
18       other resource use of each process, as well as summary information col‐
19       lated across all of the running processes.  The PMDA  uses  credentials
20       passed  from the PMAPI(3) monitoring tool identifying the user request‐
21       ing the information, to ensure that only values the user is allowed  to
22       access  are  returned  by the PMDA.  This involves the PMDA temporarily
23       changing its effective user and group identifiers for the  duration  of
24       requests  for  instances  and  values.  In other words, system calls to
25       extract information are performed as the user originating  the  request
26       and not as a privileged user.  The mechanisms available for transfer of
27       user credentials are described further in the PCPIntro(1) page.
28
29       A brief description of the pmdaproc command line options follows:
30
31       -A   Disables use of the credentials provided by  PMAPI  client  tools,
32            and simply runs everything under the "root" account.
33
34       -L   Changes the per-process instance domain used by most procproc met‐
35            rics to include threads as well.
36
37       -d   It is absolutely crucial that the performance metrics domain  num‐
38            ber  specified  here  is  unique  and consistent.  That is, domain
39            should be different for every PMDA on the one host, and  the  same
40            domain number should be used for the same PMDA on all hosts.
41
42       -l   Location  of  the log file.  By default, a log file named proc.log
43            is written in the current directory of pmcd(1)  when  pmdaproc  is
44            started,  i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be cre‐
45            ated or is not writable, output is written to the  standard  error
46            instead.
47
48       -r   Restrict the set of processes exported in the per-process instance
49            domain to only those processes that are contained by the specified
50            cgroup resource container.  This option provides an optional finer
51            granularity to the monitoring, and can also be used to reduce  the
52            resources  consumed  by pmdaproc during requests for instances and
53            values.
54
55       -U   User account under which to run the agent.   The  default  is  the
56            privileged  "root"  account,  with  seteuid  (2)  and  setegid (2)
57            switching for accessing most information.
58

HOTPROC OVERVIEW

60       The pmdaproc Performance Metrics Domain Agent (PMDA) includes an  addi‐
61       tional  set of per-process metrics with an instance domain of processes
62       restricted to an "interesting" or "hot" set.  Unlike the stock  metrics
63       exported  by  the proc PMDA, which have an instance domain equal to the
64       current processes, hot metrics have an instance domain which is a  sub‐
65       set  of  this.  This hotproc instance domain is determined by a config‐
66       urable predicate evaluated over some refresh interval.
67
68       As well as the equivalent per-process proc metrics, hotproc provides  a
69       cpuburn  metric which specifies the CPU utilization of the process over
70       the refresh interval, total metrics which  indicate  how  much  of  the
71       available  CPU  time the "interesting" processes account for, predicate
72       metrics which show the values of the  reserved  variables  (see  below)
73       that  are  being used in the hotproc predicate, and control metrics for
74       controlling the agent.
75

HOTPROC CONFIGURATION

77       The configuration file consists of one predicate used to determine if a
78       process should be in the interesting set or not.
79
80       An  example configuration file may be found at $PCP_PMDAS_DIR/proc/sam‐
81       plehotproc.conf
82
83       This   file   with    any    modifications    can    be    copied    to
84       $PCP_PMDAS_DIR/proc/hotproc.conf in order to configure the hot metrics.
85       The pmstore(1) and pmStore(3) interfaces can be used as well (described
86       below).
87
88       The  predicate  is  described  using the language specified below.  The
89       symbols are based on those used by the C(1) and awk(1) languages.
90
91       Boolean Connectives
92              && (and), || (or), !  (not), () (precedence overriding)
93
94       Number comparators
95              < , <= , > , >= , == , !=
96
97       String comparators
98              == , !=
99
100       String/Pattern comparators
101              ~ (string matches pattern) , !~ (string does not match pattern)
102
103       Reserved variables
104              uid (user id; type integer) uname (user name; type string),  gid
105              (group  id; type integer) gname (group name; type string), fname
106              (process file name; type string), psargs (process file name with
107              args; type string), cpuburn (cpu utilization; type float), iode‐
108              mand (I/O demand - Kbytes read/written per second; type  float),
109              ctxswitch  (number  of context switches per second; type float),
110              syscalls (number of system calls per second; type float), virtu‐
111              alsize (virtual size in Kbytes; type float), residentsize (resi‐
112              dent size in Kbytes; type float), iowait  (blocked  and  raw  io
113              wait  in  secs/sec;  type float), schedwait (time waiting in run
114              queue in secs/sec; type float).
115
116       Literal values
117              1234  (positive  integer),  0.35  (positive   float),   "foobar"
118              (string;  delimited  by "), /[fF](o)+bar/ (pattern; delimited by
119              /), true (boolean), false (boolean)
120
121       Comments
122              #this is a comment (from # to the end of the line).
123
124       Examples
125                cpuburn > 0.2 # cpu utilization of more than 20%
126                cpuburn > 0.2 && uname == "root"
127                cpuburn > 0.2 && (uname == "root" || uname == "hot")
128                psargs ~ /pmda/ && cpuburn > 0.4
129
130
131       The hotproc.predicate metrics may be used to see what the values of the
132       reserved  variables  are  that  were  used by the predicate at the last
133       refresh.  They do not cover the reserved variables  which  are  already
134       exported  elsewhere. A hotproc.predicate metric may not have a value if
135       it is not referenced in the configuration predicate.
136
137

DYNAMIC CONFIGURATION

139       The  hot  metrics  can  also  be  configured  at  runtime  through  the
140       pmstore(1) interface (and, implicitly, the pmStore(3) API)
141
142       Examples
143                pmstore hotproc.control.config 'fname == "mingetty"'
144                pmstore hotproc.control.config 'uid == 0'
145
146       To force the config file to be reloaded:
147                pmstore hotproc.control.reload_config "1"
148

INSTALLATION

150       The  proc  PMDA  is installed and available by default.  If you want to
151       undo the installation, do the following as root:
152
153            # cd $PCP_PMDAS_DIR/proc
154            # ./Remove
155
156       If you want to establish access to the names, help text and values  for
157       the proc performance metrics once more, after removal, do the following
158       as root:
159
160            # cd $PCP_PMDAS_DIR/proc
161            # ./Install
162
163       pmdaproc is launched by pmcd(1) and should never be executed  directly.
164       The  Install  and  Remove  scripts  notify  pmcd(1)  when  the agent is
165       installed or removed.
166

FILES

168       $PCP_PMCDCONF_PATH
169                 command line options used to launch pmdaproc
170       $PCP_PMDAS_DIR/proc/help
171                 default help text file for the proc metrics
172       $PCP_PMDAS_DIR/proc/Install
173                 installation script for the pmdaproc agent
174       $PCP_PMDAS_DIR/proc/Remove
175                 undo installation script for the pmdaproc agent
176       $PCP_LOG_DIR/pmcd/proc.log
177                 default log file for error  messages  and  other  information
178                 from pmdaproc
179       $PCP_PMDAS_DIR/proc/samplehotproc.conf
180                 simple sample hotproc configuration
181       $PCP_PMDAS_DIR/proc/hotproc.conf
182                 default hotproc configuration file
183

PCP ENVIRONMENT

185       Environment variables with the prefix PCP_ are used to parameterize the
186       file and directory names used by PCP.  On each installation,  the  file
187       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
188       $PCP_CONF variable may be used to specify an alternative  configuration
189       file, as described in pcp.conf(5).
190

SEE ALSO

192       PCPIntro(1),  pmcd(1),  pmstore(1),  seteuid(2),  setegid(2), PMAPI(3),
193       pcp.conf(5) and pcp.env(5).
194
195
196
197Performance Co-Pilot                  PCP                          PMDAPROC(1)
Impressum