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 ex‐
25       tract information are performed as the user originating the request and
26       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.  Only enable
33            this option if you understand the risks  involved,  and  are  sure
34            that  all  remote  accesses will be from benevolent users.  If en‐
35            abled, unauthenticated remote PMAPI clients will be able to access
36            potentially sensitive performance metric values which an unauthen‐
37            ticated PMAPI client usually would  not  be  able  to.   Refer  to
38            CVE-2012-3419 for additional details.
39
40       -L   Changes the per-process instance domain used by most pmdaproc met‐
41            rics to include threads as well.
42
43       -d   It is absolutely crucial that the performance metrics domain  num‐
44            ber  specified  here  is  unique  and consistent.  That is, domain
45            should be different for every PMDA on the one host, and  the  same
46            domain number should be used for the same PMDA on all hosts.
47
48       -l   Location  of  the log file.  By default, a log file named proc.log
49            is written in the current directory of pmcd(1)  when  pmdaproc  is
50            started,  i.e.  $PCP_LOG_DIR/pmcd.  If the log file cannot be cre‐
51            ated or is not writable, output is written to the  standard  error
52            instead.
53
54       -r   Restrict the set of processes exported in the per-process instance
55            domain to only those processes that are contained by the specified
56            cgroup resource container.  This option provides an optional finer
57            granularity to the monitoring, and can also be used to reduce  the
58            resources  consumed  by pmdaproc during requests for instances and
59            values.
60
61       -U   User account under which to run the agent.   The  default  is  the
62            privileged  "root"  account,  with  seteuid  (2)  and  setegid (2)
63            switching for accessing most information.
64

HOTPROC OVERVIEW

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

HOTPROC CONFIGURATION

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

DYNAMIC CONFIGURATION

145       The hot metrics can also be  configured  at  runtime  through  the  pm‐
146       store(1) interface (and, implicitly, the pmStore(3) API)
147
148       Examples
149                pmstore hotproc.control.config 'fname == "mingetty"'
150                pmstore hotproc.control.config 'uid == 0'
151
152       To force the config file to be reloaded:
153                pmstore hotproc.control.reload_config "1"
154

INSTALLATION

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

FILES

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

PCP ENVIRONMENT

191       Environment variables with the prefix PCP_ are used to parameterize the
192       file and directory names used by PCP.  On each installation,  the  file
193       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
194       $PCP_CONF variable may be used to specify an alternative  configuration
195       file, as described in pcp.conf(5).
196

SEE ALSO

198       PCPIntro(1),  pmcd(1),  pmstore(1),  seteuid(2),  setegid(2), PMAPI(3),
199       pcp.conf(5) and pcp.env(5).
200
201
202
203Performance Co-Pilot                  PCP                          PMDAPROC(1)
Impressum