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
27       programmed on different CPUs and  supports  round-robin  assignment  of
28       uncore counters needed for some AMD chips.
29
30       The   PMDA   also   counts   for  events  exposed  in  the  kernel  via
31       /sys/bus/event_source/devices directory. The PMU device  name  and  the
32       event  name must be mentioned in the configuration file. Otherwise, the
33       metric won't be available to monitor through this PMDA.
34
35       The PMDA configures the counters to count events in both user and  ker‐
36       nel mode.  This means that the hardware counters are unavailable to use
37       by normal unprivileged user applications when they are in  use  by  the
38       PMDA.  The PMDA provides a mechanism to temporarily disable the system-
39       wide counters in order to allow normal users to  be  able  to  use  the
40       counters if they wish.  See perfalloc(1) for details.
41
42       Note   that  pmdaperfevent  is  affected  by  the  value  of  the  ker‐
43       nel.perf_event_paranoid setting, which can be adjusted by sysctl(8).
44
45       A brief description of the pmdaperfevent command line options follows:
46
47       -d   It is absolutely crucial that the performance metrics domain  num‐
48            ber  specified  here  is  unique  and consistent.  That is, domain
49            should be different for every PMDA on the one host, and  the  same
50            domain number should be used for the same PMDA on all hosts.
51
52       -l   Location  of  the  log  file.   By  default, a log file named per‐
53            fevent.log is written in the current  directory  of  pmcd(1)  when
54            pmdaperfevent  is  started,  i.e.   $PCP_LOG_DIR/pmcd.  If the log
55            file cannot be created or is not writable, output  is  written  to
56            the standard error instead.
57
58       -U   User  account  under  which  to run the agent.  The default is the
59            privileged "root" account.
60
61       -i   listen on given port number for connection from pmcd(1)
62
63       -p   communicate with pmcd(1) via stdin/stdout
64
65       -u   expect pmcd(1) to connect on given unix domain socket
66
67       -6   expect pmcd(1) to connect on given ipv6 port (number or name)
68

INSTALLATION

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

FILES

86       $PCP_PMCDCONF_PATH
87                 command line options used to launch pmdaperfevent
88       $PCP_PMDAS_DIR/perfevent/perfevent.conf
89                 default   configuration   file   for   the  PMDA.   See  per‐
90                 fevent.conf(5) for detailed information.
91       $PCP_PMDAS_DIR/perfevent/help
92                 default help text file for the perfevent metrics
93       $PCP_PMDAS_DIR/perfevent/Install
94                 installation script for the pmdaperfevent agent
95       $PCP_PMDAS_DIR/perfevent/Remove
96                 undo installation script for the pmdaperfevent agent
97       $PCP_LOG_DIR/pmcd/perfevent.log
98                 default log file for error  messages  and  other  information
99                 from pmdaperfevent
100

UPGRADING

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

BUGS

109       Each  event  is  placed  in  its own group and there is no way to group
110       related events together so they are  guaranteed  to  be  simultaneously
111       active.   A workaround for this is to ensure that the number of config‐
112       ured events is less than or equal to the number of  available  hardware
113       counters.   This  means that the events will not be time-multiplexed by
114       the kernel and will be simultaneously active.
115

PCP ENVIRONMENT

117       Environment variables with the prefix PCP_ are used to parameterize the
118       file  and  directory names used by PCP.  On each installation, the file
119       /etc/pcp.conf contains the  local  values  for  these  variables.   The
120       $PCP_CONF  variable may be used to specify an alternative configuration
121       file, as described in pcp.conf(5).
122

SEE ALSO

124       perfalloc(1), perfevent.conf(5), PCPIntro(1), pmcd(1), pmlogrewrite(1),
125       PMAPI(3), pcp.conf(5), pcp.env(5) and sysctl(8).
126
127
128
129Performance Co-Pilot                  PCP                     PMDAPERFEVENT(1)
Impressum