1PMPROBE(1)                  General Commands Manual                 PMPROBE(1)
2
3
4

NAME

6       pmprobe - lightweight probe for performance metrics
7

SYNOPSIS

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

DESCRIPTION

14       pmprobe  determines  the  availability  of performance metrics exported
15       through the facilities of the Performance Co-Pilot (PCP).
16
17       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
23       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
27       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
34       Unless  directed to another host by the -h option, pmprobe will contact
35       the Performance Metrics Collector Daemon (PMCD) on the local host.
36
37       The -a option causes pmprobe to  use  the  specified  set  of  archives
38       rather than connecting to a PMCD.
39
40       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
44       The -a, -h and -L options are mutually exclusive.
45

OPTIONS

47       The available command line options are:
48
49       -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
56       -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
66       --container=container
67            Specify an individual container to be queried.
68
69       -d, --version
70            Display version number and exit.
71
72       --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
82       -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
89       -F, --faster
90            Assume given metric names are PMNS leaf nodes.
91
92       -h host, --host=host
93            Connect to pmcd(1) on host, rather than on the default localhost.
94
95       -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
100       -I, --external
101            Report  the  external  identifiers for each instance.  The literal
102            string PM_IN_NULL is reported for singular metrics.
103
104       -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
110       -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
114       -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
119       -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
126       -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
133       -V, --verbose
134            This option provides a cryptic summary of the number  of  messages
135            sent and received across the PMAPI interface.
136
137       -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
142       -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
148       -?, --help
149            Display usage message and exit.
150

EXAMPLES

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
162       $ 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
167       $ 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
172       $ pmprobe -v disk.dev.total disk.all.total
173       disk.dev.total -1012 Unknown metric name
174       disk.all.total 1 4992466
175

FILES

177       $PCP_VAR_DIR/pmns/*
178            default PMNS specification files
179

PCP ENVIRONMENT

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
187       For environment variables affecting PCP tools, see pmGetOptions(3).
188

SEE ALSO

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).
193
194
195
196Performance Co-Pilot                  PCP                           PMPROBE(1)
Impressum