1PMDAPAPI(1) General Commands Manual PMDAPAPI(1)
2
6 pmdapapi - papi performance metrics domain agent (PMDA)
7
9 $PCP_PMDAS_DIR/pmdapapi [-d domain] [-l logfile]
10
12 pmdapapi is a papi Performance Metrics Domain Agent (PMDA) which
13 exposes hardware performance counters via the library Performance API
14 (PAPI).
15 The metrics exported by the papi PMDA report values gathered from the
17 hardware counters and metrics available, as reported by papi. Cur‐
18 rently, only root users may access such metrics.
19 A brief description of the pmdapapi command line options follows:
21 -d It is absolutely crucial that the performance metrics domain num‐
23 ber specified here is unique and consistent. That is, domain
24 should be different for every PMDA on the one host, and the same
25 domain number should be used for the same PMDA on all hosts.
26 -l Location of the log file. By default, a log file named papi.log
28 is written in the current directory of pmcd(1) when pmdapapi is
29 started, i.e. $PCP_LOG_DIR/pmcd. If the log file cannot be cre‐
30 ated or is not writable, output is written to the standard error
31 instead.
32 Performance counters are activated automatically as they are fetched
34 cyclically (such as via pmval(1) or pmlogger(1)). This automatic acti‐
35 vation is temporary, and lasts only a number of seconds governed by the
36 papi.control.auto_enable control value (default 120). In the case
37 automatic activation is undesirable, one may disable it by setting the
38 papi.control.auto_enable metric to 0.
39 Alternately, the pmstore(1) command can be used to permanently enable
41 tracking particular metrics, or stop them on demand. Using the
42 papi.control.enable and papi.control.disable metrics, one may set the
43 metrics you wish to track using a space or comma separated list. Writ‐
44 ing to the papi.control.reset metric disables all counters immediately.
45 This may be useful if the system performance counters are needed for
46 another profiling task.
47 # pmstore papi.control.enable "TOT_CYC TOT_INS"
49 papi.control.enable old value="" new value="TOT_CYC TOT_INS"
50 # pmval papi.system.TOT_CYC
52 8.371E+04
53 # pmval papi.system.TOT_INS
54 2.712E+04
55 # pmstore papi.control.disable "TOT_CYC,TOT_INS"
56 papi.control.disable old value="" new value="TOT_CYC,TOT_INS"
57 Fetching the papi.control.status metric provides an overview of all
59 active counters.
60 By default, PAPI multiplexing, which allows support for collecting more
62 metrics than supported by the hardware concurrently, is enabled. One
63 may modify the papi.control.multiplex metric to disable multiplexing by
64 setting it to 0.
65 Where possible, pmdapapi will expose available native perf and uncore
67 events on the current hardware. It is not possible to count some
68 native metrics and preset metrics concurrently.
69 # true -- automatically-enabled counters
71 # pmval -s3 papi.system.perf.BRANCH.LOADS
72 metric: papi.system.perf.BRANCH.LOADS
73 host: HOSTNAME
74 semantics: cumulative counter (converting to rate)
75 units: count (converting to count / sec)
76 samples: 3
77 interval: 1.00 sec
78 7530.
79 7539.
80 7543.
81 # pmval -s3 papi.system.perf.BRANCH.MISSES
83 metric: papi.system.perf.BRANCH.MISSES
84 host: HOSTNAME
85 semantics: cumulative counter (converting to rate)
86 units: count (converting to count / sec)
87 samples: 3
88 interval: 1.00 sec
89 696.8
90 590.8
91 651.8
92 # true -- quick overview
94 # pminfo -f papi.control.status
95 papi.control.status
96 value "Papi is running, has multiplexing enabled, perf.BRANCH.MISSES(114): 8960, perf.BRANCH.LOADS(110): 158400"
97 # true -- optional instant disable
99 # pmstore papi.control.disable "perf.BRANCH.LOADS,perf.BRANCH.MISSES"
100 papi.control.disable old value="" new value="perf.BRANCH.LOADS,perf.BRANCH.MISSES"
101
103 If you want access to the names, help text and values for the papi per‐
104 formance metrics, do the following as root:
105 # cd $PCP_PMDAS_DIR/papi
107 # ./Install
108 If you want to undo the installation (and remove both PMDAs), do the
110 following as root:
111 # cd $PCP_PMDAS_DIR/papi
113 # ./Remove
114 pmdapapi is launched by pmcd(1) and should never be executed directly.
116 The Install and Remove scripts notify pmcd(1) when the agent is
117 installed or removed.
118
120 $PCP_PMCDCONF_PATH
121 command line options used to launch pmdapapi
122 $PCP_PMDAS_DIR/papi/help
123 default help text file for the papi metrics
124 $PCP_PMDAS_DIR/papi/Install
125 installation script for the pmdapapi agent
126 $PCP_PMDAS_DIR/papi/Remove
127 undo installation script for the pmdapapi agent
128 $PCP_LOG_DIR/pmcd/sample.log
129 default log file for error messages and other information
130 from pmdapapi
131
133 Environment variables with the prefix PCP_ are used to parameterize the
134 file and directory names used by PCP. On each installation, the file
135 /etc/pcp.conf contains the local values for these variables. The
136 $PCP_CONF variable may be used to specify an alternative configuration
137 file, as described in pcp.conf(5).
138
140 PCPIntro(1), pmcd(1), pcp.conf(5) and pcp.env(5).
141Performance Co-Pilot PCP PMDAPAPI(1)