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

NAME

6       pmval, pmevent - arbitrary performance metrics value dumper
7

SYNOPSIS

9       pmval  [-dgLrvVz?]   [-a  archive]  [-A  align]  [-f  N]  [-h host] [-i
10       instances] [-K spec] [-n pmnsfile] [-O offset] [-p port]  [-s  samples]
11       [-S  starttime]  [-t interval] [-T endtime] [-U archive] [-w width] [-x
12       pattern] [-Z timezone] [--container=name] [--derived=file] metricname
13

DESCRIPTION

15       pmval prints current or archived values for the  nominated  performance
16       metric.   The  metric  of interest is named in the metricname argument,
17       subject to instance qualification with the -i flag as described below.
18
19       Unless directed to another host by the -h option, or to a  set  of  ar‐
20       chives by the -a or -U options, pmval will contact the Performance Met‐
21       rics Collector Daemon (PMCD) on the local host to obtain  the  required
22       information.
23
24       The  metricname  argument may also be given in the metric specification
25       syntax, as described in  PCPIntro(1),  where  the  source,  metric  and
26       instance  may  all  be  included  in the metricname, e.g. thathost:ker‐
27       nel.all.load["1 minute"].  When this format is used, none of the -h  or
28       -a or -U options may be specified.
29
30       When  using  the  metric  specification  syntax,  the ``hostname'' @ is
31       treated specially and causes pmval to use a local  context  to  collect
32       metrics  from  PMDAs on the local host without PMCD.  Only some metrics
33       are available in this mode.
34
35       When processing a set of archives, pmval may relinquish its own  timing
36       control,  and operate as a ``slave'' of a pmtime(1) process that uses a
37       GUI dialog to provide timing control.  In  this  case,  either  the  -g
38       option  should  be  used  to  start  pmval  as  the sole slave of a new
39       pmtime(1) instance, or -p should be used to attach pmval to an existing
40       pmtime(1) instance via the IPC channel identified by the port argument.
41
42       The  -S,  -T,  -O and -A options may be used to define a time window to
43       restrict the samples retrieved, set an initial origin within  the  time
44       window,  or  specify a ``natural'' alignment of the sample times; refer
45       to PCPIntro(1) for a complete description of these options.
46
47       The output from pmval is directed to standard  output.   The  following
48       symbols  may  occasionally appear, in place of a metric value, in pmval
49       output:  A question mark symbol (?) indicates that a value is no longer
50       available for that metric instance.  An exclamation mark (!)  indicates
51       that a 64-bit counter wrapped during the sample.
52

OPTIONS

54       The available command line options are:
55
56       -a archive, --archive=archive
57            Performance metric values are retrieved from the  set  of  Perfor‐
58            mance  Co-Pilot  (PCP) archive log files identified by the archive
59            argument, which is a comma-separated list of names, each of  which
60            may be the base name of an archive or the name of a directory con‐
61            taining one or more archives.  See also -U.
62
63       -A align, --align=align
64            Force the initial sample to be aligned on the boundary of a  natu‐
65            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
66            tion of the syntax for align.
67
68       -d, --delay
69            When replaying from an archive, this option requests that the pre‐
70            vailing  real-time  delay  be  applied between samples (see -t) to
71            effect a pause, rather than the default behaviour of replaying  at
72            full speed.
73
74       -f precision, --precision=precision
75            Numbers  are reported in ``fixed point'' notation, rather than the
76            default scientific notation, using precision digits for precision.
77            Each  number  will  be  up  to  the column width determined by the
78            default heuristics, else the -w option if specified,  and  include
79            precision digits after the decimal point.  So, the options -f 3 -w
80            8 would produce numbers of the form 9999.999.  A value of zero for
81            precision omits the decimal point and any fractional digits.
82
83       -g, --guimode
84            Start  pmval as the slave of a new pmtime(1) process for replay of
85            archived performance  data  using  the  pmtime(1)  graphical  user
86            interface.
87
88       -h host, --host=host
89            Fetch  performance  metrics from pmcd(1) on host, rather than from
90            the default localhost.
91
92       -i instances, --instances=instances
93            Specify a list of one or more names of instances for the nominated
94            performance  metric  -  just these instances will be retrieved and
95            reported (the default is to report all instances).  The list  must
96            be  a single argument, with elements of the list separated by com‐
97            mas and/or white space.
98
99            The instance name may be quoted with  single  (')  or  double  (")
100            quotes  for  those  cases  where  the instance name contains white
101            space or commas.
102
103            Multiple -i options are allowed as an alternative way of  specify‐
104            ing more than one instance of interest.
105
106            As an example, the following are all equivalent:
107
108                 $ pmval -i "'1 minute','5 minute'" kernel.all.load
109                 $ pmval -i '"1 minute","5 minute"' kernel.all.load
110                 $ pmval -i "'1 minute' '5 minute'" kernel.all.load
111                 $ pmval -i "'1 minute'" -i "'5 minute'" kernel.all.load
112                 $ pmval 'localhost:kernel.all.load["1 minute","5 minute"]'
113
114
115       -K spec, --spec-local=spec
116            When fetching metrics from a local context (see -L), the -K option
117            may be used to control the DSO PMDAs that should be made  accessi‐
118            ble.   The  spec  argument  conforms  to  the  syntax described in
119            pmSpecLocalPMDA(3).  More than one -K option may be used.
120
121       -L, --local-PMDA
122            Use a local context to collect metrics from DSO PMDAs on the local
123            host without PMCD.  See also -K.
124
125       -n pmnsfile, --namespace=pmnsfile
126            Load  an alternative Performance Metrics Name Space (PMNS(5)) from
127            the file pmnsfile.
128
129       -O origin, --origin=origin
130            When reporting archived metrics, start reporting at origin  within
131            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
132            plete description of the syntax for origin.
133
134       -p port, --guiport=port
135            Attach  pmval  to  an  existing  pmtime(1)  time  control  process
136            instance  via  the  IPC  channel  identified by the port argument.
137            This  option  is  normally  only  used  by   other   tools,   e.g.
138            pmchart(1), when they launch pmval with synchronized time control.
139
140       -r, --raw
141            Print raw values for cumulative counter metrics.  Normally cumula‐
142            tive counter metrics are converted to rates.   For  example,  disk
143            transfers are reported as number of disk transfers per second dur‐
144            ing the preceding sample interval, rather than the  raw  value  of
145            number  of  disk  transfers  since the machine was booted.  If you
146            specify this option, the raw metric values are printed.
147
148       -s samples, --samples=samples
149            The samples argument defines the number of samples to be retrieved
150            and  reported.  If samples is 0 or -s is not specified, pmval will
151            sample and report continuously (in real time mode)  or  until  the
152            end of the set of PCP archives (in archive mode).
153
154       -S starttime, --start=starttime
155            When  reporting archived metrics, the report will be restricted to
156            those records logged at or after starttime.  Refer to  PCPIntro(1)
157            for a complete description of the syntax for starttime.
158
159       -t interval, --interval=interval
160            Set  the  reporting interval to something other than the default 1
161            second.  The interval argument follows  the  syntax  described  in
162            PCPIntro(1),  and  in the simplest form may be an unsigned integer
163            (the implied units in this case are seconds).
164
165       -T endtime, --finish=endtime
166            When reporting archived metrics, the report will be restricted  to
167            those  records  logged before or at endtime.  Refer to PCPIntro(1)
168            for a complete description of the syntax for endtime.
169
170       -U archive, --nointerp=archive
171            Performance metric values are retrieved from the  Performance  Co-
172            Pilot  (PCP)  archive.   The argument is a comma-separated list of
173            names, each of which may be the base name of  an  archive  or  the
174            name  of  a  directory  containing one or more archives.  However,
175            unlike -a every recorded value in the  archive  for  the  selected
176            metric  and  instances  is reported (so no interpolation mode, and
177            the sample interval (-t option) is ignored.  See also -a.
178
179            At most one of the options -a and -U may be specified.
180
181       -v, --verbose
182            Enable verbose mode.
183
184       -V, --version
185            Display version number and exit.
186
187       -w width, --width=width
188            Set the width of each column of output to be  width  columns.   If
189            not  specified  columns are wide enough to accommodate the largest
190            value of the type being printed.
191
192       -x pattern, --filter=pattern
193            The given pattern is sent to the performance metric  domain  agent
194            for  the  requested  metricname  before  any values are requested.
195            This serves two purposes.  Firstly, it provides  a  mechanism  for
196            server-side  event  filtering  that is customisable for individual
197            event streams.   In  addition,  some  performance  metrics  domain
198            agents  also use the PMCD store mechanism to provide a basic secu‐
199            rity model (e.g. for sensitive log files, only a client host  with
200            pmStore(3) access would be able to access the event stream).
201
202            As pattern may be processed by regcomp(3) it should be a non-empty
203            string.  Use . (dot) for a “match all” pattern.
204
205       -z, --hostzone
206            Use the local timezone of the host that is the source of the  per‐
207            formance  metrics, as identified by either the -h or the -a or the
208            -U options.  The default is to use the timezone of the local host.
209
210       -Z timezone, --timezone=timezone
211            Use timezone for the date and time.  Timezone is in the format  of
212            the environment variable TZ as described in environ(7).
213
214       -?, --help
215            Display usage message and exit.
216
217       --container=container
218            Specify an individual container to be queried.
219
220       --derived=file
221            Load derived metric definitions from file.
222

CAVEATS

224       By  default,  pmval attempts to display non-integer numeric values in a
225       way that does not distort the inherent precision (rarely  more  than  4
226       significant digits), and tries to maintain a tabular format in the out‐
227       put.  These goals are sometimes in conflict.
228
229       In the absence of the -f option (described above), the following  table
230       describes  the  formats used for different ranges of numeric values for
231       any metric that is of type PM_TYPE_FLOAT or PM_TYPE_DOUBLE, or any met‐
232       ric  that  has  the semantics of a counter (for which pmval reports the
233       rate converted value):
234
235                         ┌──────────┬──────────────────────┐
236                         │ Format   │     Value Range      │
237                         ├──────────┼──────────────────────┤
238                         │        ! │ No values available  │
239                         │9.999E-99 │ < 0.1                │
240                         │   0.0    │ 0                    │
241                         │   9.9999 │ > 0 and <= 0.9999    │
242                         │   9.999  │ > 0.9999 and < 9.999 │
243                         │  99.99   │ > 9.999 and < 99.99  │
244                         │ 999.9    │ > 99.99 and < 999.9  │
245                         │9999.     │ > 999.9 and < 9999   │
246                         │9.999E+99 │ > 9999               │
247                         └──────────┴──────────────────────┘

DIAGNOSTICS

249       All are generated on standard  error  and  are  intended  to  be  self-
250       explanatory.
251

PCP ENVIRONMENT

253       Environment variables with the prefix PCP_ are used to parameterize the
254       file and directory names used by PCP.  On each installation,  the  file
255       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
256       $PCP_CONF variable may be used to specify an alternative  configuration
257       file, as described in pcp.conf(5).
258
259       For environment variables affecting PCP tools, see pmGetOptions(3).
260

SEE ALSO

262       PCPIntro(1),    pmcd(1),   pmchart(1),   pmdumplog(1),   pmdumptext(1),
263       pminfo(1),  pmlogger(1),  pmrep(1),  pmtime(1),  PMAPI(3),  pmStore(3),
264       pmSpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and PMNS(5).
265
266
267
268Performance Co-Pilot                  PCP                             PMVAL(1)
Impressum