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

NAME

6       pmval, pmevent - arbitrary performance metrics value dumper
7

SYNOPSIS

9       pmval  [-dgLrvVXz?]   [-a archive] [-A align] [--container=name] [--de‐
10       rived=file] [-f N] [-h host] [-i instances] [-K spec] [-n pmnsfile] [-O
11       offset]  [-p  port]  [-s samples] [-S starttime] [-t interval] [-T end‐
12       time] [-U archive] [-w width] [-x pattern] [-Z timezone] metricname
13
14       pmevent ...
15

DESCRIPTION

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

OPTIONS

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

CAVEATS

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

PCP ENVIRONMENT

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

SEE ALSO

268       PCPIntro(1),    pmcd(1),   pmchart(1),   pmdumplog(1),   pmdumptext(1),
269       pminfo(1), pmlogger(1), pmrep(1), pmtime(1), PMAPI(3), pmStore(3),  pm‐
270       SpecLocalPMDA(3), pcp.conf(5), pcp.env(5) and PMNS(5).
271
272
273
274Performance Co-Pilot                  PCP                             PMVAL(1)
Impressum