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 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 log files identified by the archive
52 argument, which is a comma-separated list of names, each of which
53 may be the base name of an archive or the name of a directory con‐
54 taining 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 -n pmnsfile, --namespace=pmnsfile
67 Normally pmprobe operates on the distributed Performance Metrics
68 Name Space (PMNS), however, if the -n option is specified an
69 alternative local PMNS file is loaded from the file pmnsfile.
70 -f, --force
72 When used with -i or -I the set of instances reported will be all
73 of those known at the source of the performance data. By default
74 the set of reported instances are those for which values are cur‐
75 rently available, which may be smaller than the set reported with
76 -f.
77 -I, --external
79 Report the external identifiers for each instance. The literal
80 string PM_IN_NULL is reported for singular metrics.
81 -i, --internal
83 Report the internal identifiers for each instance. The values are
84 in decimal and prefixed by ``?''. As a special case, the literal
85 string PM_IN_NULL is reported for singular metrics.
86 -K spec, --spec-local=spec
88 When using the -L/ option to fetch metrics from a local context,
89 this option controls the DSO PMDAs that should be made accessible.
90 The spec argument conforms to the syntax described in pmSpecLo‐
91 calPMDA(3). More than one -K option may be used.
92 -O time, --origin=time
94 When used in conjunction with an archive source of metrics and the
95 options -f/, the time argument defines a time origin at which the
96 metrics should be fetched from the set of archives. Refer to
97 PCPIntro(1) for a complete description of this option, and the
98 syntax for the time argument.
99 -v, --values
101 Report the value for each instance, as per the formatting rules of
102 pmPrintValue(3). When fetching from a set of archives, only those
103 instances present in the first archive record for a metric will be
104 displayed; see also the -O option. The -v option is mutually
105 exclusive with either the -I or -i options.
106 -V, --verbose
108 This option provides a cryptic summary of the number of messages
109 sent and received across the PMAPI interface.
110 -?, --help
112 Display usage message and exit.
113 --container=container
115 Specify an individual container to be queried.
116 --derived=dmfile
118 The dmfile argument specifies a file that contains derived metric
119 definitions in the format described for pmLoadDerivedConfig(3).
120 This option provides a way to load derived metric definitions that
121 is an alternative to the more generic use of the PCP_DERIVED_CON‐
122 FIG environment variable as described in PCPIntro(1). Using the
123 --derived option and the PCP_DERIVED_CONFIG environment variable
124 to specify the same configuration is a bad idea, so choose one or
125 the other method.
126
128 $ pmprobe disk.dev
129 disk.dev.read 2
130 disk.dev.write 2
131 disk.dev.total 2
132 disk.dev.blkread 2
133 disk.dev.blkwrite 2
134 disk.dev.blktotal 2
135 disk.dev.active 2
136 disk.dev.response 2
137 $ pmprobe -I disk.dev.read disk.dev.write disk.all.total
139 disk.dev.read 2 "sda" "sdb"
140 disk.dev.write 2 "sda" "sdb"
141 disk.all.total 1 PM_IN_NULL
142 $ pmprobe -v pmcd.numagents pmcd.version pmcd.control.timeout
144 pmcd.numagents 1 9
145 pmcd.version 1 "5.0.0"
146 pmcd.control.timeout 1 5
147 $ pmprobe -v disk.dev.total disk.all.total
149 disk.dev.total -1012 Unknown metric name
150 disk.all.total 1 4992466
151
153 $PCP_VAR_DIR/pmns/*
154 default PMNS specification files
155
157 Environment variables with the prefix PCP_ are used to parameterize the
158 file and directory names used by PCP. On each installation, the file
159 /etc/pcp.conf contains the local values for these variables. The
160 $PCP_CONF variable may be used to specify an alternative configuration
161 file, as described in pcp.conf(5).
162 For environment variables affecting PCP tools, see pmGetOptions(3).
164
166 PCPIntro(1), pmcd(1), pmdumplog(1), pminfo(1), PMAPI(3), pmErrStr(3),
167 pmGetOptions(3), pmSpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and
168 PMNS(5).
169Performance Co-Pilot PCP PMPROBE(1)