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

NAME

6       pmprobe - lightweight probe for performance metrics
7

SYNOPSIS

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

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

OPTIONS

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
38       The -a option causes pmprobe to  use  the  specified  set  of  archives
39       rather than connecting to a PMCD.
40
41       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
46       The available command line options are:
47
48       -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
55       -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
65       -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
70       -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
77       -I, --external
78            Report  the  external  identifiers for each instance.  The literal
79            string PM_IN_NULL is reported for singular metrics.
80
81       -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
86       -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
92       -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
99       -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
106       -V, --verbose
107            This  option  provides a cryptic summary of the number of messages
108            sent and received across the PMAPI interface.
109
110       -?, --help
111            Display usage message and exit.
112
113       --container=container
114            Specify an individual container to be queried.
115
116       --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

EXAMPLES

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
137       $ 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
142       $ 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
147       $ pmprobe -v disk.dev.total disk.all.total
148       disk.dev.total -1012 Unknown metric name
149       disk.all.total 1 4992466
150

FILES

152       $PCP_VAR_DIR/pmns/*
153                 default PMNS specification files
154

PCP ENVIRONMENT

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

SEE ALSO

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).
168
169
170
171Performance Co-Pilot                  PCP                           PMPROBE(1)
Impressum