pmdaperfevent(1)

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

NAME

6       pmdaperfevent - hardware performance counter performance metrics domain
7       agent (PMDA)
8

SYNOPSIS

10       $PCP_PMDAS_DIR/perfevent/pmdaperfevent [-d  domain]  [-l  logfile]  [-U
11       username] [-i port] [-p] [-u socket] [-6]
12

DESCRIPTION

14       pmdaperfevent is a Performance Metrics Domain Agent (PMDA) that config‐
15       ures and reads the hardware performance counters using the Linux kernel
16       perf_event API.
17
18       The  perfevent  PMDA  exports metrics for hardware performance counters
19       that are configurable from the Linux kernel perf_event API.   The  PMDA
20       uses the libpfm4 library to access the hardware performance counters so
21       any counters that are supported in libpfm4 should  be  available.  Also
22       included  is the ability to read the Intel RAPL counters via direct MSR
23       access.  The PMDA supports automatically loading different counters for
24       each  hardware  architecture.  A  single  configuration file is used to
25       specify the desired counters for each hardware  performance  monitoring
26       unit (PMU). The configuration file allows different counters to be pro‐
27       grammed on different CPUs and supports round-robin assignment of uncore
28       counters needed for some AMD chips.
29
30       The  PMDA configures the counters to count events in both user and ker‐
31       nel mode.  This means that the hardware counters are unavailable to use
32       by  normal  unprivileged  user applications when they are in use by the
33       PMDA. The PMDA provides a mechanism to temporarily disable the  system-
34       wide  counters  in  order  to  allow normal users to be able to use the
35       counters if they wish. See perfalloc(1) for details.
36
37
38       A brief description of the pmdaperfevent command line options follows:
39
40       -d   It is absolutely crucial that the performance metrics domain  num‐
41            ber  specified  here  is  unique  and consistent.  That is, domain
42            should be different for every PMDA on the one host, and  the  same
43            domain number should be used for the same PMDA on all hosts.
44
45       -l   Location  of  the  log  file.   By  default, a log file named per‐
46            fevent.log is written in the current  directory  of  pmcd(1)  when
47            pmdaperfevent  is  started,  i.e.   $PCP_LOG_DIR/pmcd.  If the log
48            file cannot be created or is not writable, output  is  written  to
49            the standard error instead.
50
51       -U   User  account  under  which  to run the agent.  The default is the
52            privileged "root" account.
53
54       -i   listen on given port number for connection from pmcd(1)
55
56       -p   communicate with pmcd(1) via stdin/stdout
57
58       -u   expect pmcd(1) to connect on given unix domain socket
59
60       -6   expect pmcd(1) to connect on given ipv6 port (number or name)
61

INSTALLATION

63       The perfevent PMDA is not activated by default.  To install  the  PMDA,
64       do the following as root:
65
66            # cd $PCP_PMDAS_DIR/perfevent
67            # ./Install
68
69       If you want to undo the installation, do the following as root:
70
71            # cd $PCP_PMDAS_DIR/perfevent
72            # ./Remove
73
74       pmdaperfevent  is  launched  by  pmcd(1)  and  should never be executed
75       directly.  The Install and Remove scripts notify pmcd(1) when the agent
76       is installed or removed.
77

FILES

79       $PCP_PMCDCONF_PATH
80                 command line options used to launch pmdaperfevent
81       $PCP_PMDAS_DIR/perfevent/perfevent.conf
82                 default   configuration   file   for   the   PMDA.  See  per‐
83                 fevent.conf(5) for detailed information.
84       $PCP_PMDAS_DIR/perfevent/help
85                 default help text file for the perfevent metrics
86       $PCP_PMDAS_DIR/perfevent/Install
87                 installation script for the pmdaperfevent agent
88       $PCP_PMDAS_DIR/perfevent/Remove
89                 undo installation script for the pmdaperfevent agent
90       $PCP_LOG_DIR/pmcd/perfevent.log
91                 default log file for error  messages  and  other  information
92                 from pmdaperfevent
93

UPGRADING

95       Some  metric  names  have  changed starting in version 3.10.8 to better
96       conform to PMNS conventions.  pmlogrewrite(1) can be used to update old
97       archives.   A  helper  utility, $PCP_PMDAS_DIR/perfevent/perfevent-mak‐
98       erewrite.pl will generate a config file that is suitable for  use  with
99       pmlogrewrite(1) to update the metric names in existing archives.
100

BUGS

102       Each  event  is  placed  in  its own group and there is no way to group
103       related events together so they are  guaranteed  to  be  simultaneously
104       active.   A workaround for this is to ensure that the number of config‐
105       ured events is less than or equal to the number of  available  hardware
106       counters.  This  means  that the events will not be time-multiplexed by
107       the kernel and will be simultaneously active.
108

PCP ENVIRONMENT

110       Environment variables with the prefix PCP_ are used to parameterize the
111       file  and  directory names used by PCP.  On each installation, the file
112       /etc/pcp.conf contains the  local  values  for  these  variables.   The
113       $PCP_CONF  variable may be used to specify an alternative configuration
114       file, as described in pcp.conf(5).
115