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 spec]
10 [-n pmnsfile] [-O time] [-Z timezone] [metricname ...]
11
13 pmprobe determines the availability of performance metrics exported
14 through the facilities of the Performance Co-Pilot (PCP).
15 The metrics of interest are named in the metricname arguments. If met‐
17 ricname is a non-leaf node in the Performance Metrics Name Space
18 (pmns(5)), then pmprobe will recursively descend the PMNS and report on
19 all leaf nodes. If no metricname argument is given, the root of the
20 namespace is used.
21 This recursive expansion of the PMNS can be inhibited by the -F (go
23 faster) option, which reduces the number of roundtrips to pmcd(1) when
24 the metricname arguments are known to be leaf nodes ahead of time.
25 The output format is spartan and intended for use in wrapper scripts
27 creating configuration files for other PCP tools. By default, there is
28 one line of output per metric, with the metric name followed by a count
29 of the number of available values. Error conditions are encoded as a
30 negative value count (as per the PMAPI(3) protocols, but may be decoded
31 using pmerr(1)) and followed by a textual description of the error.
32 Unless directed to another host by the -h option, pmprobe will contact
34 the Performance Metrics Collector Daemon (PMCD) on the local host.
35 The -a option causes pmprobe to use the specified set of archives
37 rather than connecting to a PMCD. The argument is a comma-separated
38 list of names, each of which may be the base name of an archive or the
39 name of a directory containing one or more archives. The -a and -h
40 options are mutually exclusive.
41 The -b/--batch option may be used to define the maximum size of the
43 group of metrics to be fetched in a single request for the -v/--values
44 option. This batching is also applied to the pmLookupName(3) request
45 that pmprobe calls with the list of leaf metric names, to avoid exceed‐
46 ing the maximum PDU length supported by pmcd(1) for client requests.
47 This can be important for pmlogconf(1), which uses pmprobe to enumerate
48 the set of metrics to be logged by pmlogger(1). The default value for
49 batchsize is 128. This option is useful to avoid limitations on PDU
50 request sizes and also to stagger fetches, which may otherwise timeout
51 if pmcd(1) or a PMDA is slow to respond, particularly if a large number
52 of metrics are probed.
53 The -L option causes pmprobe to use a local context to collect metrics
55 from PMDAs on the local host without PMCD. Only some metrics are
56 available in this mode. The -a, -h and -L options are mutually exclu‐
57 sive.
58 Normally pmprobe operates on the distributed Performance Metrics Name
60 Space (PMNS), however, if the -n option is specified an alternative
61 local PMNS file is loaded from the file pmnsfile.
62 Other options control the output of additional information when one or
64 more values is available.
65 -f When used with -i or -I the set of instances reported will be all
67 of those known at the source of the performance data. By default
68 the set of reported instances are those for which values are cur‐
69 rently available, which may be smaller than the set reported with
70 -f.
71 -I Report the external identifiers for each instance. The literal
73 string PM_IN_NULL is reported for singular metrics.
74 -i Report the internal identifiers for each instance. The values are
76 in decimal and prefixed by ``?''. As a special case, the literal
77 string PM_IN_NULL is reported for singular metrics.
78 -K When using the -L option to fetch metrics from a local context,
80 the -K option may be used to control the DSO PMDAs that should be
81 made accessible. The spec argument conforms to the syntax
82 described in pmSpecLocalPMDA(3). More than one -K option may be
83 used.
84 -O When used in conjunction with an archive source of metrics and the
86 -v option the time argument defines a time origin at which the
87 metrics should be fetched from the archive(s). Refer to PCPIn‐
88 tro(1) for a complete description of this option, and the syntax
89 for the time argument.
90 -v Report the value for each instance, as per the formatting rules of
92 pmPrintValue(3). When fetching from a set of archives, only those
93 instances present in the first archive record for a metric will be
94 displayed; see also the -O option.
95 The -v option is mutually exclusive with either the -I or -i options.
97 The -V option provides a cryptic summary of the number of messages sent
99 and received across the PMAPI interface.
100
102 $ pmprobe disk.dev
103 disk.dev.read 2
104 disk.dev.write 2
105 disk.dev.total 2
106 disk.dev.blkread 2
107 disk.dev.blkwrite 2
108 disk.dev.blktotal 2
109 disk.dev.active 2
110 disk.dev.response 2
111 $ pmprobe -I disk.dev.read disk.dev.write disk.all.total
113 disk.dev.read 2 "dks0d1" "dks0d2"
114 disk.dev.write 2 "dks0d1" "dks0d2"
115 disk.all.total 1 PM_IN_NULL
116 $ pmprobe -v pmcd.numagents pmcd.version pmcd.control.timeout
118 pmcd.numagents 1 9
119 pmcd.version 1 "2.0 beta-1"
120 pmcd.control.timeout 1 5
121 $ pmprobe -v disk.dev.total disk.all.total
123 disk.dev.total -1012 Unknown metric name
124 disk.all.total 1 4992466
125
127 $PCP_VAR_DIR/pmns/*
128 default PMNS specification files
129
131 Environment variables with the prefix PCP_ are used to parameterize the
132 file and directory names used by PCP. On each installation, the file
133 /etc/pcp.conf contains the local values for these variables. The
134 $PCP_CONF variable may be used to specify an alternative configuration
135 file, as described in pcp.conf(5).
136
138 PCPIntro(1), pmcd(1), pmdumplog(1), pminfo(1), PMAPI(3), pmErrStr(3),
139 pmSpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and pmns(5).
140Performance Co-Pilot PCP PMPROBE(1)