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

NAME

6       pmval, pmevent - arbitrary performance metrics value dumper
7

SYNOPSIS

9       pmval [-dgLrvz] [-A align] [-a archive] [-f N] [-h host] [-i instances]
10       [-K spec] [-n pmnsfile] [-O offset] [-p port] [-S starttime]  [-s  sam‐
11       ples]  [-T  endtime] [-t interval] [-U archive] [-w width] [-x pattern]
12       [-Z timezone] 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 other options which control the source, timing and  layout  of  the
48       information reported by pmval are as follows:
49
50       -a   Performance  metric  values  are retrieved from the set of Perfor‐
51            mance Co-Pilot (PCP) archive logs identified. The  argument  is  a
52            comma-separated  list of names, each of which may be the base name
53            of an archive or the name of a directory containing  one  or  more
54            archives. See also -U.
55
56       -d   When  replaying  from a set of archives, this option requests that
57            the prevailing real-time delay be applied between samples (see -t)
58            to  effect a pause, rather than the default behaviour of replaying
59            at full speed.
60
61       -f   Numbers are reported in ``fixed point'' notation, rather than  the
62            default scientific notation.  Each number will be up to the column
63            width determined by the default heuristics, else the -w option  if
64            specified,  and include N digits after the decimal point.  So, the
65            options -f 3 -w 8 would produce numbers of the form  9999.999.   A
66            value  of  zero  for  N omits the decimal point and any fractional
67            digits.
68
69       -g   Start pmval as the slave of a new pmtime(1) process for replay  of
70            archived  performance  data  using  the  pmtime(1)  graphical user
71            interface.
72
73       -h   Current performance metric values are retrieved from the nominated
74            host machine.
75
76       -i   instances  is  a  list of one or more instance names for the nomi‐
77            nated performance metric - just these instances will be  retrieved
78            and  reported  (the default is to report all instances).  The list
79            must be a single argument, with elements of the list separated  by
80            commas and/or white space.
81
82            The  instance  name  may  be  quoted with single (') or double (")
83            quotes for those cases where  the  instance  name  contains  white
84            space or commas.
85
86            Multiple  -i options are allowed as an alternative way of specify‐
87            ing more than one instance of interest.
88
89            As an example, the following are all equivalent:
90
91                 $ pmval -i "'1 minute','5 minute'" kernel.all.load
92                 $ pmval -i '"1 minute","5 minute"' kernel.all.load
93                 $ pmval -i "'1 minute' '5 minute'" kernel.all.load
94                 $ pmval -i "'1 minute'" -i "'5 minute'" kernel.all.load
95                 $ pmval 'localhost:kernel.all.load["1 minute","5 minute"]'
96
97
98       -K   When fetching metrics from a local context, the -K option  may  be
99            used to control the DSO PMDAs that should be made accessible.  The
100            spec argument conforms to the syntax  described  in  pmSpecLocalP‐
101            MDA(3).  More than one -K option may be used.
102
103       -n   Normally  pmval  operates  on the default Performance Metrics Name
104            Space (PMNS), however if the -n option is specified an alternative
105            namespace is loaded from the file pmnsfile.
106
107       -p   Attach  pmval  to  an  existing  pmtime(1)  time  control  process
108            instance via the IPC channel  identified  by  the  port  argument.
109            This   option   is   normally  only  used  by  other  tools,  e.g.
110            pmchart(1), when they launch pmval with synchronized time control.
111
112       -r   Print raw values for cumulative counter metrics.  Normally cumula‐
113            tive  counter  metrics  are converted to rates.  For example, disk
114            transfers are reported as number of disk transfers per second dur‐
115            ing  the  preceding  sample interval, rather than the raw value of
116            number of disk transfers since the machine  was  booted.   If  you
117            specify this option, the raw metric values are printed.
118
119       -s   The argument samples defines the number of samples to be retrieved
120            and reported.  If samples is 0 or -s is not specified, pmval  will
121            sample  and  report  continuously (in real time mode) or until the
122            end of the set of PCP archives (in archive mode).
123
124       -t   The default update interval may be set to something other than the
125            default  1  second.   The  interval  argument  follows  the syntax
126            described in PCPIntro(1), and in  the  simplest  form  may  be  an
127            unsigned integer (the implied units in this case are seconds).
128
129       -U   Performance  metric  values  are retrieved from the set of Perfor‐
130            mance Co-Pilot (PCP) archive logs identified. The  argument  is  a
131            comma-separated  list of names, each of which may be the base name
132            of an archive or the name of a directory containing  one  or  more
133            archives.   However, unlike -a every recorded value in the archive
134            for the selected metric and instances is reported (so no  interpo‐
135            lation  mode,  and the sample interval (-t option) is ignored. See
136            also -a.
137
138            At most one of the options -a and -U may be specified.
139
140       -w   Set the width of each column of output to be  width  columns.   If
141            not  specified  columns are wide enough to accommodate the largest
142            value of the type being printed.
143
144       -x   The given pattern is sent to the performance metric  domain  agent
145            for  the  requested  metricname  before  any values are requested.
146            This serves two purposes.  Firstly, it provides  a  mechanism  for
147            server-side  event  filtering  that is customisable for individual
148            event streams.   In  addition,  some  performance  metrics  domain
149            agents  also use the PMCD store mechanism to provide a basic secu‐
150            rity model (e.g. for sensitive log files, only a client host  with
151            pmStore(3) access would be able to access the event stream).
152
153            As pattern may be processed by regcomp(3) it should be a non-empty
154            string.  Use . (dot) for a “match all” pattern.
155
156       -Z   By default, pmval reports the time of day according to  the  local
157            timezone  on the system where pmval is run.  The -Z option changes
158            the timezone to timezone in the format of the environment variable
159            TZ as described in environ(7).
160
161       -z   Change  the  reporting  timezone to the local timezone at the host
162            that is the source of the performance metrics, as  identified  via
163            either the metricname or the -h or -a or -U options.
164
165       The  following  symbols  may  occasionally appear, in place of a metric
166       value, in pmval output:  A question mark symbol (?)  indicates  that  a
167       value  is no longer available for that metric instance.  An exclamation
168       mark (!)  indicates that a 64-bit counter wrapped during the sample.
169
170       The output from pmval is directed to standard output.
171

FILES

173       $PCP_VAR_DIR/pmns/*
174                 default PMNS specification files
175

PCP ENVIRONMENT

177       Environment variables with the prefix PCP_ are used to parameterize the
178       file  and  directory names used by PCP.  On each installation, the file
179       /etc/pcp.conf contains the  local  values  for  these  variables.   The
180       $PCP_CONF  variable may be used to specify an alternative configuration
181       file, as described in pcp.conf(5).
182

SEE ALSO

184       PCPIntro(1),   pmcd(1),   pmchart(1),   pmdumplog(1),    pmdumptext(1),
185       pminfo(1),  pmlogger(1),  pmrep(1),  pmtime(1),  PMAPI(3),  pmStore(3),
186       pmSpecLocalPMDA(3), pcp.conf(5) and pcp.env(5).
187

DIAGNOSTICS

189       All are generated on standard  error  and  are  intended  to  be  self-
190       explanatory.
191

CAVEATS

193       By  default,  pmval attempts to display non-integer numeric values in a
194       way that does not distort the inherent precision (rarely  more  than  4
195       significant digits), and tries to maintain a tabular format in the out‐
196       put.  These goals are sometimes in conflict.
197
198       In the absence of the -f option (described above), the following  table
199       describes  the  formats used for different ranges of numeric values for
200       any metric that is of type PM_TYPE_FLOAT or PM_TYPE_DOUBLE, or any met‐
201       ric  that  has  the semantics of a counter (for which pmval reports the
202       rate converted value):
203
204                         ┌──────────┬──────────────────────┐
205                         │ Format   │     Value Range      │
206                         ├──────────┼──────────────────────┤
207                         │        ! │ No values available  │
208                         │9.999E-99 │ < 0.1                │
209                         │   0.0    │ 0                    │
210                         │   9.9999 │ > 0 and <= 0.9999    │
211                         │   9.999  │ > 0.9999 and < 9.999 │
212                         │  99.99   │ > 9.999 and < 99.99  │
213                         │ 999.9    │ > 99.99 and < 999.9  │
214                         │9999.     │ > 999.9 and < 9999   │
215                         │9.999E+99 │ > 9999               │
216                         └──────────┴──────────────────────┘
217
218
219Performance Co-Pilot                  PCP                             PMVAL(1)
Impressum