1PMPROBE(1) General Commands Manual PMPROBE(1)
2
6 pmprobe - lightweight probe for performance metrics
7
9 pmprobe [-dfFiILvVz?] [-a archive] [-b batchsize] [--container=name]
10 [--derived=file] [-h hostname] [-K spec] [-n pmnsfile] [-O time] [-Z
11 timezone] [metricname ...]
12
14 pmprobe determines the availability of performance metrics exported
15 through the facilities of the Performance Co-Pilot (PCP).
16 The metrics of interest are named in the metricname arguments. If met‐
18 ricname is a non-leaf node in the Performance Metrics Name Space
19 (PMNS(5)), then pmprobe will recursively descend the PMNS and report on
20 all leaf nodes. If no metricname argument is given, the root of the
21 namespace is used.
22 This recursive expansion of the PMNS can be inhibited by the -F (go
24 faster) option, which reduces the number of roundtrips to pmcd(1) when
25 the metricname arguments are known to be leaf nodes ahead of time.
26 The output format is spartan and intended for use in wrapper scripts
28 creating configuration files for other PCP tools. By default, there is
29 one line of output per metric, with the metric name followed by a count
30 of the number of available values. Error conditions are encoded as a
31 negative value count (as per the PMAPI(3) protocols, but may be decoded
32 using pmerr(1)) and followed by a textual description of the error.
33 Unless directed to another host by the -h option, pmprobe will contact
35 the Performance Metrics Collector Daemon (PMCD) on the local host.
36 The -a option causes pmprobe to use the specified set of archives
38 rather than connecting to a PMCD.
39 The -L option causes pmprobe to use a local context to collect metrics
41 from PMDAs on the local host without PMCD. Only some metrics are
42 available in this mode.
43 The -a, -h and -L options are mutually exclusive.
45
47 The available command line options are:
48 -a archive, --archive=archive
50 Performance metric values are retrieved from the set of Perfor‐
51 mance Co-Pilot (PCP) archive files identified by the archive argu‐
52 ment, which is a comma-separated list of names, each of which may
53 be the base name of an archive or the name of a directory contain‐
54 ing one or more archives.
55 -b, --batch
57 This option may be used to define the maximum number of metrics to
58 be fetched in a single request for the -v option and any pmLookup‐
59 Name(3) request that pmprobe calls with a list of leaf metric
60 names. The default value for batchsize is 128. This option is
61 useful to avoid limitations on PDU request sizes and also to stag‐
62 ger fetches, which may otherwise timeout if pmcd(1) or a PMDA is
63 slow to respond, particularly if a large number of metrics are
64 probed.
65 --container=container
67 Specify an individual container to be queried.
68 -d, --version
70 Display version number and exit.
71 --derived=dmfile
73 The dmfile argument specifies a file that contains derived metric
74 definitions in the format described for pmLoadDerivedConfig(3).
75 This option provides a way to load derived metric definitions that
76 is an alternative to the more generic use of the PCP_DERIVED_CON‐
77 FIG environment variable as described in PCPIntro(1). Using the
78 --derived option and the PCP_DERIVED_CONFIG environment variable
79 to specify the same configuration is a bad idea, so choose one or
80 the other method.
81 -f, --force
83 When used with -i or -I the set of instances reported will be all
84 of those known at the source of the performance data. By default
85 the set of reported instances are those for which values are cur‐
86 rently available, which may be smaller than the set reported with
87 -f.
88 -F, --faster
90 Assume given metric names are PMNS leaf nodes.
91 -h host, --host=host
93 Connect to pmcd(1) on host, rather than on the default localhost.
94 -i, --internal
96 Report the internal identifiers for each instance. The values are
97 in decimal and prefixed by ``?''. As a special case, the literal
98 string PM_IN_NULL is reported for singular metrics.
99 -I, --external
101 Report the external identifiers for each instance. The literal
102 string PM_IN_NULL is reported for singular metrics.
103 -K spec, --spec-local=spec
105 When using the -L/ option to fetch metrics from a local context,
106 this option controls the DSO PMDAs that should be made accessible.
107 The spec argument conforms to the syntax described in pmSpecLo‐
108 calPMDA(3). More than one -K option may be used.
109 -L, --local-PMDA
111 Use a local context to collect metrics from DSO PMDAs on the local
112 host without PMCD. See also -K.
113 -n pmnsfile, --namespace=pmnsfile
115 Normally pmprobe operates on the distributed Performance Metrics
116 Name Space (PMNS), however, if the -n option is specified an al‐
117 ternative local PMNS file is loaded from the file pmnsfile.
118 -O time, --origin=time
120 When used in conjunction with an archive source of metrics and the
121 options -f/, the time argument defines a time origin at which the
122 metrics should be fetched from the set of archives. Refer to
123 PCPIntro(1) for a complete description of this option, and the
124 syntax for the time argument.
125 -v, --values
127 Report the value for each instance, as per the formatting rules of
128 pmPrintValue(3). When fetching from a set of archives, only those
129 instances present in the first archive record for a metric will be
130 displayed; see also the -O option. The -v option is mutually ex‐
131 clusive with either the -I or -i options.
132 -V, --verbose
134 This option provides a cryptic summary of the number of messages
135 sent and received across the PMAPI interface.
136 -z, --hostzone
138 Change the reporting timezone to the local timezone at the host
139 that is the source of the performance metrics, as identified via
140 either the -h or -a options.
141 -Z timezone, --timezone=timezone
143 By default, pmprobe reports the time of day according to the local
144 timezone on the system where pmprobe is run. The -Z option
145 changes the timezone to timezone in the format of the environment
146 variable TZ as described in environ(7).
147 -?, --help
149 Display usage message and exit.
150
152 $ pmprobe disk.dev
153 disk.dev.read 2
154 disk.dev.write 2
155 disk.dev.total 2
156 disk.dev.blkread 2
157 disk.dev.blkwrite 2
158 disk.dev.blktotal 2
159 disk.dev.active 2
160 disk.dev.response 2
161 $ pmprobe -I disk.dev.read disk.dev.write disk.all.total
163 disk.dev.read 2 "sda" "sdb"
164 disk.dev.write 2 "sda" "sdb"
165 disk.all.total 1 PM_IN_NULL
166 $ pmprobe -v pmcd.numagents pmcd.version pmcd.control.timeout
168 pmcd.numagents 1 9
169 pmcd.version 1 "5.0.0"
170 pmcd.control.timeout 1 5
171 $ pmprobe -v disk.dev.total disk.all.total
173 disk.dev.total -1012 Unknown metric name
174 disk.all.total 1 4992466
175
177 $PCP_VAR_DIR/pmns/*
178 default PMNS specification files
179
181 Environment variables with the prefix PCP_ are used to parameterize the
182 file and directory names used by PCP. On each installation, the file
183 /etc/pcp.conf contains the local values for these variables. The
184 $PCP_CONF variable may be used to specify an alternative configuration
185 file, as described in pcp.conf(5).
186 For environment variables affecting PCP tools, see pmGetOptions(3).
188
190 PCPIntro(1), pmcd(1), pmdumplog(1), pminfo(1), PMAPI(3), pmErrStr(3),
191 pmGetOptions(3), pmSpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and
192 PMNS(5).
193Performance Co-Pilot PCP PMPROBE(1)