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

NAME

6       pmrep - performance metrics reporter
7

SYNOPSIS

9       pmrep  [-CdGHLpruUVxz?]   [-a  archive] [-A align] [-b space-scale] [-c
10       config] [-e derived] [-E lines] [-f format] [-F archive] [-h host]  [-K
11       spec]  [-l delimiter] [-o output] [-O origin] [-P precision] [-q count-
12       scale] [-s samples] [-S  starttime]  [-t  interval]  [-T  endtime]  [-w
13       width] [-y time-scale] [-Z timezone] metricspec [...]
14

DESCRIPTION

16       pmrep is a customizable performance metrics reporting tool.  Any avail‐
17       able performance metric, live or archived, system  and/or  application,
18       can  be  selected  for  reporting  using one of the output alternatives
19       listed below together with applicable formatting options.
20
21       pmrep collects the selected metric values through the facilities of the
22       Performance  Co-Pilot  (PCP),  see  PCPIntro(1).   The  metrics  to  be
23       reported are specified on the command line, in a configuration file, or
24       both.   Metrics can be automatically converted and scaled using the PCP
25       facilities, either by default or by per-metric scaling  specifications.
26       In  addition  to  the  existing metrics, derived metrics can be defined
27       using the arithmetic expressions described in pmRegisterDerived(3).
28
29       Unless directed to another host by the -h option,  pmrep  will  contact
30       the  Performance  Metrics  Collector  Daemon (PMCD, see pmcd(1)) on the
31       local host.
32
33       The -a option causes pmrep to use the specified archive log rather than
34       connecting to a PMCD.  The -a and -h options are mutually exclusive.
35
36       The  -L  option  causes pmrep to use a local context to collect metrics
37       from DSO PMDAs (Performance Metrics Domain Agents, ``plugins'') on  the
38       local host without PMCD.  Only some metrics are available in this mode.
39       The -a, -h, and -L options are mutually exclusive.
40
41       The metrics of interest are named in the metricspec argument(s).  If  a
42       metricspec  specifies  a  non-leaf node in the Performance Metrics Name
43       Space (PMNS), then pmrep will recursively descend the PMNS  and  report
44       on  all leaf nodes (i.e., metrics) for that metricspec.  (Use for exam‐
45       ple pminfo(1) to list all the leaf nodes and their descriptions.)
46
47       A metricspec has three different forms. First, on the command  line  it
48       can  start with a colon (``:'') to indicate a metricset to be read from
49       a pmrep configuration file (see pmrep.conf(5)) which can  then  consist
50       of  any number of metricspecs.  Second, a metricspec starting with non-
51       colon specifies a PMNS node as described above, optionally followed  by
52       metric  formatting  definitions  (applicable only to leaf nodes).  This
53       so-called compact form of a metricspec is defined as follows:
54
55               metric[,label[,instance[,unit/scale[,type[,width]]]]]
56
57       A valid PMNS node (metric) is mandatory.  It can be followed by a  text
58       label  used  by  supporting output targets (such as csv and stdout, see
59       below).  The optional instance definition is  currently  unimplemented.
60       An  optional  unit/scale  is  applicable for dimension-compatible, non-
61       string, and (currently) non-raw  metrics.   (See  below  for  supported
62       unit/scale specifications.)  By default, cumulative counter metrics are
63       converted to rates.  If the optional type field is set to raw then this
64       rate  conversion  is  disabled, unit/scale specification is (currently)
65       ignored and raw values are reported instead.  Finally,  for  supporting
66       output  targets  (currently: stdout) a numeric width can be used to set
67       the width of the output column for this metric.  Too-wide numeric  val‐
68       ues  for output will not be printed (apart from decimal places, numeric
69       values will never be silently truncated).   Too-wide  strings  will  be
70       truncated.
71
72       The  following  metricspec requests the metric kernel.all.sysfork to be
73       reported under the label forks, converting to the default rate  count/s
74       in an 8 wide column.  Although the definitions in this compact form are
75       optional, they must always be provided in the order specified above.
76
77               kernel.all.sysfork,forks,,,,8
78
79       The third form of a metricspec is valid only in pmrep.conf(5).
80
81       Derived metrics are specified like PMNS leaf node metrics.
82
83       Configuration  file  parameters  override  the  corresponding  built-in
84       default  values  (if any).  Command line parameters override the corre‐
85       sponding configuration file parameters (if any).
86

COMMAND LINE OPTIONS

88       The available command line options are:
89
90       -a   Performance metric values are retrieved from the  Performance  Co-
91            Pilot  (PCP) archive log file identified by the base name archive.
92            See also -u.
93
94       --archive-folio
95            Read metric source  archives  from  the  PCP  archive  folio  (see
96            mkaf(1)).
97
98       -A   When  reporting  archived  metrics, force the initial sample to be
99            aligned on the boundary of a natural time unit  align.   Refer  to
100            PCPIntro(1) for a complete description of the syntax for align.
101
102       -b   Unit/scale  for  space  (byte)  metrics,  possible  values include
103            bytes, Kbytes, KB, Mbytes, MB, and so forth up  to  Ebytes.   This
104            option  will not override possible per-metric specifications.  See
105            also pmParseUnitsStr(3).
106
107       -c   Specify the config file to use.  The default is ./pmrep.conf.  See
108            pmrep.conf(5).
109
110       -C   Exit before reporting any values, but after parsing the configura‐
111            tion and metrics and printing possible headers.
112
113       -d   When replaying from an archive, this option requests that the pre‐
114            vailing  real-time  delay  be  applied between samples (see -t) to
115            effect a pause, rather than the default behaviour of replaying  at
116            full speed.
117
118       -e   Specify  derived  performance  metrics.  If  derived starts with a
119            slash (``/'') or with a dot (``.'') it will be  interpreted  as  a
120            derived  metrics  configuration  file, otherwise it will be inter‐
121            preted as comma-separated derived metric expressions.  For details
122            see pmLoadDerivedConfig(3) and pmRegisterDerived(3).
123
124       -E   Repeat the header every lines of output.
125
126       -f   Use  the  format  string for formatting the timestamp.  The format
127            will be used  with  Python's  datetime.strftime  method  which  is
128            mostly the same as that described in strftime(3).  An empty format
129            string (i.e., '') will remove the timestamps from the output.  The
130            default is %H:%M:%S.
131
132       -F   Specify the output archive.  See -o.
133
134       -G   Do not include global metrics in reporting (see pmrep.conf(5)).
135
136       -h   Fetch  performance  metrics  from pmcd(1) on host, rather than the
137            default localhost.
138
139       -H   Do not print any headers.
140
141       -K   When fetching metrics from a local context (see -L), the -K option
142            may  be used to control the DSO PMDAs that should be made accessi‐
143            ble.  The spec  argument  conforms  to  the  syntax  described  in
144            __pmSpecLocalPMDA(3).  More than one -K option may be used.
145
146       -l   Specify  the delimiter that separates each column of csv or stdout
147            output.  The delimiter  may  only  be  a  single  character.   The
148            default  for  stdout  is two spaces (``  '') and comma (``,'') for
149            csv.
150
151       -L   Use a local context to collect metrics from DSO PMDAs on the local
152            host without PMCD.  See also -K.
153
154       -o   Use  output  target  for reporting.  The default target is stdout.
155            The available target alternatives are:
156
157            archive
158              Record metrics into a PCP archive which can  later  be  replayed
159              with  PCP  tools, including pmrep itself. See pcp-archive(5) and
160              PCPIntro(1) for details about PCP archive files.  Requires -F.
161
162            csv
163              Print metrics in CSV format (subject to formatting options).
164
165            stdout
166              Print metrics to stdout (format subject to formatting options).
167
168            zabbix
169              Send metrics to a Zabbix  server.   See  pmrep.conf(5)  for  the
170              needed  Zabbix  configuration  parameters.   This target is cur‐
171              rently experimental.
172
173       -O   When reporting archived metrics, start reporting at origin  within
174            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
175            plete description of the syntax for origin.
176
177       -p   Print timestamps.  By default no timestamps are printed.
178
179       -P   Use precision for numeric non-integer output values.  If the value
180            is  too wide for its column width, precision is reduced one by one
181            until the value fits, or not printed at all if it does  not.   The
182            default is to use 3 decimal places (when applicable).
183
184       -q   Unit/scale  for  count  metrics,  possible  values include count x
185            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
186            10^7.   (These values are currently space-sensitive.)  This option
187            will not override possible per-metric  specifications.   See  also
188            pmParseUnitsStr(3).
189
190       -r   Output  raw  metric  values, do not convert cumulative counters to
191            rates.  This option will override possible  per-metric  specifica‐
192            tions.
193
194       -s   The argument samples defines the number of samples to be retrieved
195            and reported.  If samples is 0 or -s is not specified, pmrep  will
196            sample  and  report  continuously (in real time mode) or until the
197            end of the PCP archive (in archive mode).  See also -T.
198
199       -S   When reporting archived metrics, the report will be restricted  to
200            those  records logged at or after starttime.  Refer to PCPIntro(1)
201            for a complete description of the syntax for starttime.
202
203       -t   The default update interval may be set to something other than the
204            default  1  second.   The  interval  argument  follows  the syntax
205            described in PCPIntro(1), and in  the  simplest  form  may  be  an
206            unsigned  integer  (the  implied  units in this case are seconds).
207            See also the -T option.
208
209       -T   When reporting archived metrics, the report will be restricted  to
210            those  records  logged before or at endtime.  Refer to PCPIntro(1)
211            for a complete description of the syntax for endtime.
212
213            When used to define the runtime before pmrep will exit, if no sam‐
214            ples is given (see -s) then the number of reported samples depends
215            on interval (see -t).  If samples is given then interval  will  be
216            adjusted  to  allow  reporting of samples during runtime.  In case
217            all of -T, -s, and -t are given,  endtime  determines  the  actual
218            time pmrep will run.
219
220       -u   When  reporting  archived  metrics, by default values are reported
221            according to the selected sample interval (-t option), not accord‐
222            ing  to  the actual record interval in an archive.  To this effect
223            PCP interpolates the values to be reported based on the records in
224            the  archive.   With  the  -u  option  uninterpolated reporting is
225            enabled, every recorded value for the selected metrics is reported
226            and the requested sample interval (-t) is ignored.
227
228            So  for  example,  if  a  PCP archive contains recorded values for
229            every 10 seconds and the requested sample interval is 1  hour,  by
230            default pmrep will use an interpolation scheme to compute the val‐
231            ues of the requested metrics from the values recorded in the prox‐
232            imity  of  these requested metrics and values for every 1 hour are
233            reported.  With -u every record every 10 seconds are used as  such
234            (the  reported values are still subject to rate conversion, use -r
235            to disable).
236
237       -U   Omit unit information from of headers.
238
239       -V   Display version number and exit.
240
241       -w   Set the stdout output column width.  Strings will be truncated  to
242            this  width.   The  default width is the shortest that can fit the
243            metric label, the forced minimum is 3.  This option will not over‐
244            ride possible per-metric specifications.
245
246       -x   Print extended header.
247
248       -y   Unit/scale  for time metrics, possible values include nanosec, ns,
249            microsec, us, millisec, and so forth up to hours, hr.  This option
250            will  not  override  possible per-metric specifications.  See also
251            pmParseUnitsStr(3).
252
253       -z   Use the local timezone of the host that is the source of the  per‐
254            formance  metrics,  as  identified  by  either  the  -h  or the -a
255            options.  The default is to use the timezone of the local host.
256
257       -Z   Use timezone when displaying the date and time.   Timezone  is  in
258            the  format  of  the environment variable TZ as described in envi‐
259            ron(7).
260
261       -?   Display usage message and exit.
262

EXAMPLES

264       The following examples use the PCP facilities for collecting the metric
265       values,  no  external  utilities  are  needed.  The examples expect the
266       default configuration file to contain the metricset specifications.
267
268       Display network interface statistics on the local host:
269           $ pmrep network.interface.total.bytes
270
271       Display per-device disk reads and writes from the  host  server1  using
272       two seconds interval and CSV output format:
273           $ pmrep -h server1 -o csv -t 2s disk.dev.read disk.dev.write
274
275       Display  timestamped  vmstat(8)  like  information using MBs instead of
276       bytes and also include the number of in-use inodes:
277           $ pmrep -p -b MB vfs.inodes.count :vmstat
278
279       Display sar -w and sar -W like information at the same  time  from  the
280       PCP archive ./20150921.09.13 showing values recorded between 3 - 5 PM:
281           $ pmrep -a ./20150921.09.13 -S @15:00 -T @17:00 :sar-w :sar-W
282
283       Record  all  389  Directory Server, XFS file system and CPU/disk/memory
284       related metrics every five seconds for the next five minutes to the PCP
285       archive ./a:
286        $ pmrep -o archive -F ./a -t 5s -T 5m ds389 xfs kernel.all.cpu disk mem
287

FILES

289       ./pmrep.conf
290                 Default configuration file.
291

BUGS

293       No command line option can follow metrics.
294
295       Specifying instances is not yet supported.
296

PCP ENVIRONMENT

298       Environment  variables with the prefix PCP_ are used to parametrize the
299       file and directory names used by PCP.  On each installation,  the  file
300       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
301       $PCP_CONF variable may be used to specify an alternative  configuration
302       file, as described in pcp.conf(5).
303

SEE ALSO

305       mkaf(1),  PCPIntro(1), pcp(1), pcp-atop(1), pmcd(1), pmchart(1), pmcol‐
306       lectl(1),  pmdiff(1),  pmdumplog(1),  pmdumptext(1),  pminfo(1),  pmio‐
307       stat(1),   pmlogextract(1),   pmlogsummary(1),  pmprobe(1),  pmstat(1),
308       pmval(1),   sar(1),    __pmSpecLocalPMDA(3),    pmLoadDerivedConfig(3),
309       pmParseUnitsStr(3),  pmRegisterDerived(3), strftime(3), pcp-archive(5),
310       pcp.conf(5), pmns(5), pmrep.conf(5), environ(7) and vmstat(8).
311
312
313
314Performance Co-Pilot                  PCP                             PMREP(1)
Impressum