1PMPROBE(1) General Commands Manual PMPROBE(1)
2
6 pmprobe - lightweight probe for performance metrics
7
9 pmprobe [-fFIiLVvz?] [-a archive] [-b batchsize] [-h hostname] [-K
10 spec] [-n pmnsfile] [-O time] [-Z timezone] [--container=name]
11 [--derived=file] [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
35 Unless directed to another host by the -h option, pmprobe will contact
36 the Performance Metrics Collector Daemon (PMCD) on the local host.
37 The -a option causes pmprobe to use the specified set of archives
39 rather than connecting to a PMCD.
40 The -L option causes pmprobe to use a local context to collect metrics
42 from PMDAs on the local host without PMCD. Only some metrics are
43 available in this mode. The -a, -h and -L options are mutually exclu‐
44 sive.
45 The available command line options are:
47 -a archive, --archive=archive
49 Performance metric values are retrieved from the set of Perfor‐
50 mance Co-Pilot (PCP) archive log files identified by the archive
51 argument, which is a comma-separated list of names, each of which
52 may be the base name of an archive or the name of a directory con‐
53 taining one or more archives.
54 -b, --batch
56 This option may be used to define the maximum number of metrics to
57 be fetched in a single request for the -v option and any pmLookup‐
58 Name(3) request that pmprobe calls with a list of leaf metric
59 names. The default value for batchsize is 128. This option is
60 useful to avoid limitations on PDU request sizes and also to stag‐
61 ger fetches, which may otherwise timeout if pmcd(1) or a PMDA is
62 slow to respond, particularly if a large number of metrics are
63 probed.
64 -n pmnsfile, --namespace=pmnsfile
66 Normally pmprobe operates on the distributed Performance Metrics
67 Name Space (PMNS), however, if the -n option is specified an
68 alternative local PMNS file is loaded from the file pmnsfile.
69 -f, --force
71 When used with -i or -I the set of instances reported will be all
72 of those known at the source of the performance data. By default
73 the set of reported instances are those for which values are cur‐
74 rently available, which may be smaller than the set reported with
75 -f.
76 -I, --external
78 Report the external identifiers for each instance. The literal
79 string PM_IN_NULL is reported for singular metrics.
80 -i, --internal
82 Report the internal identifiers for each instance. The values are
83 in decimal and prefixed by ``?''. As a special case, the literal
84 string PM_IN_NULL is reported for singular metrics.
85 -K spec, --spec-local=spec
87 When using the -L/ option to fetch metrics from a local context,
88 this option controls the DSO PMDAs that should be made accessible.
89 The spec argument conforms to the syntax described in pmSpecLo‐
90 calPMDA(3). More than one -K option may be used.
91 -O time, --origin=time
93 When used in conjunction with an archive source of metrics and the
94 options -f/, the time argument defines a time origin at which the
95 metrics should be fetched from the set of archives. Refer to
96 PCPIntro(1) for a complete description of this option, and the
97 syntax for the time argument.
98 -v, --values
100 Report the value for each instance, as per the formatting rules of
101 pmPrintValue(3). When fetching from a set of archives, only those
102 instances present in the first archive record for a metric will be
103 displayed; see also the -O option. The -v option is mutually
104 exclusive with either the -I or -i options.
105 -V, --verbose
107 This option provides a cryptic summary of the number of messages
108 sent and received across the PMAPI interface.
109 -?, --help
111 Display usage message and exit.
112 --container=container
114 Specify an individual container to be queried.
115 --derived=dmfile
117 The dmfile argument specifies a file that contains derived metric
118 definitions in the format described for pmLoadDerivedConfig(3).
119 This option provides a way to load derived metric definitions that
120 is an alternative to the more generic use of the PCP_DERIVED_CON‐
121 FIG environment variable as described in PCPIntro(1). Using the
122 --derived option and the PCP_DERIVED_CONFIG environment variable
123 to specify the same configuration is a bad idea, so choose one or
124 the other method.
125
127 $ pmprobe disk.dev
128 disk.dev.read 2
129 disk.dev.write 2
130 disk.dev.total 2
131 disk.dev.blkread 2
132 disk.dev.blkwrite 2
133 disk.dev.blktotal 2
134 disk.dev.active 2
135 disk.dev.response 2
136 $ pmprobe -I disk.dev.read disk.dev.write disk.all.total
138 disk.dev.read 2 "sda" "sdb"
139 disk.dev.write 2 "sda" "sdb"
140 disk.all.total 1 PM_IN_NULL
141 $ pmprobe -v pmcd.numagents pmcd.version pmcd.control.timeout
143 pmcd.numagents 1 9
144 pmcd.version 1 "5.0.0"
145 pmcd.control.timeout 1 5
146 $ pmprobe -v disk.dev.total disk.all.total
148 disk.dev.total -1012 Unknown metric name
149 disk.all.total 1 4992466
150
152 $PCP_VAR_DIR/pmns/*
153 default PMNS specification files
154
156 Environment variables with the prefix PCP_ are used to parameterize the
157 file and directory names used by PCP. On each installation, the file
158 /etc/pcp.conf contains the local values for these variables. The
159 $PCP_CONF variable may be used to specify an alternative configuration
160 file, as described in pcp.conf(5).
161 For environment variables affecting PCP tools, see pmGetOptions(3).
163
165 PCPIntro(1), pmcd(1), pmdumplog(1), pminfo(1), PMAPI(3), pmErrStr(3),
166 pmGetOptions(3), pmSpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and
167 PMNS(5).
168Performance Co-Pilot PCP PMPROBE(1)