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

NAME

6       pcp2xlsx - pcp-to-xlsx metrics exporter
7

SYNOPSIS

9       pcp2xlsx  [-5CGHILmrRvVz?]   [-4 action] [-a archive] [-A align] [--ar‐
10       chive-folio folio] [-b|-B space-scale] [-c  config]  [--container  con‐
11       tainer]  [--daemonize]  [-e derived] [-f format] [-F outfile] [-h host]
12       [-i instances] [-K spec] [-O origin] [-P|-0  precision]  [-q|-Q  count-
13       scale]  [-s  samples]  [-S starttime] [-t interval] [-T endtime] [-y|-Y
14       time-scale] [-Z timezone] metricspec [...]
15

DESCRIPTION

17       pcp2xlsx is a customizable performance metrics exporter tool  from  PCP
18       to  XLSX.   Any  available performance metric, live or archived, system
19       and/or application, can be selected for exporting using either  command
20       line arguments or a configuration file.
21
22       pcp2xlsx  is  a  close relative of pmrep(1).  Refer to pmrep(1) for the
23       metricspec description accepted on  pcp2xlsx  command  line.   See  pm‐
24       rep.conf(5)  for  description  of  the pcp2xlsx.conf configuration file
25       overall syntax.  This page describes pcp2xlsx specific options and con‐
26       figuration  file  differences  with pmrep.conf(5).  pmrep(1) also lists
27       some usage examples of which most are applicable with pcp2xlsx as well.
28
29       Only the command line options listed on this page are supported,  other
30       options recognized by pmrep(1) are not supported.
31
32       Options  via environment values (see pmGetOptions(3)) override the cor‐
33       responding built-in default values (if any).   Configuration  file  op‐
34       tions  override the corresponding environment variables (if any).  Com‐
35       mand line options override the corresponding configuration file options
36       (if any).
37

CONFIGURATION FILE

39       pcp2xlsx uses a configuration file with overall syntax described in pm‐
40       rep.conf(5).  The following options are common  with  pmrep.conf:  ver‐
41       sion,  source,  speclocal, derived, header, globals, samples, interval,
42       type, type_prefer, ignore_incompat, names_change, instances, omit_flat,
43       include_labels,      precision,      precision_force,      count_scale,
44       count_scale_force,    space_scale,    space_scale_force,    time_scale,
45       time_scale_force.   The output option is recognized but ignored for pm‐
46       rep.conf compatibility.
47
48       There are no pcp2xlsx specific options.
49

OPTIONS

51       The available command line options are:
52
53       -0 precision, --precision-force=precision
54            Like -P but this option will override per-metric specifications.
55
56       -4 action, --names-change=action
57            Specify which action to take on receiving a  metric  names  change
58            event  during  sampling.  These events occur when a PMDA discovers
59            new metrics sometime after starting up, and informs running client
60            tools  like pcp2xlsx.  Valid values for action are update (refresh
61            metrics being sampled), ignore (do nothing -  the  default  behav‐
62            iour) and abort (exit the program if such an event happens).
63
64       -5, --ignore-unknown
65            Silently ignore any metric name that cannot be resolved.  At least
66            one metric must be found for the tool to start.
67
68       -a archive, --archive=archive
69            Performance metric values are retrieved from the  set  of  Perfor‐
70            mance  Co-Pilot  (PCP) archive log files identified by the archive
71            argument, which is a comma-separated list of names, each of  which
72            may be the base name of an archive or the name of a directory con‐
73            taining one or more archives.
74
75       -A align, --align=align
76            Force the initial sample to be aligned on the boundary of a  natu‐
77            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
78            tion of the syntax for align.
79
80       --archive-folio=folio
81            Read metric source archives from the PCP archive folio created  by
82            tools like pmchart(1) or, less often, manually with mkaf(1).
83
84       -b scale, --space-scale=scale
85            Unit/scale  for  space  (byte)  metrics,  possible  values include
86            bytes, Kbytes, KB, Mbytes, MB, and so forth.  This option will not
87            override  possible  per-metric specifications.  See also pmParseU‐
88            nitsStr(3).
89
90       -B scale, --space-scale-force=scale
91            Like -b but this option will override per-metric specifications.
92
93       -c config, --config=config
94            Specify the config file or directory to use.  In case config is  a
95            directory  all  files under it ending .conf will be included.  The
96            default    is    the    first    found    of:     ./pcp2xlsx.conf,
97            $HOME/.pcp2xlsx.conf,         $HOME/pcp/pcp2xlsx.conf,         and
98            $PCP_SYSCONF_DIR/pcp2xlsx.conf.  For details, see the  above  sec‐
99            tion and pmrep.conf(5).
100
101       --container=container
102            Fetch performance metrics from the specified container, either lo‐
103            cal or remote (see -h).
104
105       -C, --check
106            Exit before reporting any values, but after parsing the configura‐
107            tion and metrics and printing possible headers.
108
109       --daemonize
110            Daemonize on startup.
111
112       -e derived, --derived=derived
113            Specify  derived  performance  metrics.   If derived starts with a
114            slash (``/'') or with a dot (``.'') it will be  interpreted  as  a
115            derived  metrics  configuration  file, otherwise it will be inter‐
116            preted as comma- or  semicolon-separated  derived  metric  expres‐
117            sions.   For  details  see  pmLoadDerivedConfig(3) and pmRegister‐
118            Derived(3).
119
120       -G, --no-globals
121            Do not include global metrics in reporting (see pmrep.conf(5)).
122
123       -f format, --timestamp-format=format
124            Use the format string for formatting the  timestamp.   The  format
125            will  be  used  with  Python's  datetime.strftime  method which is
126            mostly the same as that described in strftime(3).  The default  is
127            %Y-%m-%d %H:%M:%S.
128
129       -F outfile, --output-file=outfile
130            Specify the output file outfile.
131
132       -h host, --host=host
133            Fetch  performance  metrics from pmcd(1) on host, rather than from
134            the default localhost.
135
136       -H, --no-header
137            Do not print any headers.
138
139       -i instances, --instances=instances
140            Retrieve and report only the specified metric instances from  cur‐
141            rently present metric instances.  By default all current instances
142            are reported.
143
144            Refer to pmrep(1) for complete description of this option.
145
146       -I, --ignore-incompat
147            Ignore incompatible  metrics.   By  default  incompatible  metrics
148            (that  is,  their  type is unsupported or they cannot be scaled as
149            requested) will cause pcp2xlsx to terminate with an error message.
150            With  this  option  all  incompatible metrics are silently omitted
151            from reporting.  This may be  especially  useful  when  requesting
152            non-leaf nodes of the PMNS tree for reporting.
153
154       -K spec, --spec-local=spec
155            When fetching metrics from a local context (see -L), the -K option
156            may be used to control the DSO PMDAs that should be made  accessi‐
157            ble.   The  spec  argument conforms to the syntax described in pm‐
158            SpecLocalPMDA(3).  More than one -K option may be used.
159
160       -L, --local-PMDA
161            Use a local context to collect metrics from DSO PMDAs on the local
162            host without PMCD.  See also -K.
163
164       -m, --include-labels
165            Include metric labels in the output.
166
167       -O origin, --origin=origin
168            When  reporting archived metrics, start reporting at origin within
169            the time window (see -S and -T).  Refer to PCPIntro(1) for a  com‐
170            plete description of the syntax for origin.
171
172       -P precision, --precision=precision
173            Use  precision for numeric non-integer output values.  The default
174            is to use 3 decimal places (when applicable).   This  option  will
175            not override possible per-metric specifications.
176
177       -q scale, --count-scale=scale
178            Unit/scale  for  count  metrics,  possible  values include count x
179            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
180            10^7.   (These values are currently space-sensitive.)  This option
181            will not override possible per-metric  specifications.   See  also
182            pmParseUnitsStr(3).
183
184       -Q scale, --count-scale-force=scale
185            Like -q but this option will override per-metric specifications.
186
187       -r, --raw
188            Output  raw  metric  values, do not convert cumulative counters to
189            rates.  This option will override possible  per-metric  specifica‐
190            tions.
191
192       -R, --raw-prefer
193            Like  -r  but  this option will not override per-metric specifica‐
194            tions.
195
196       -s samples, --samples=samples
197            The samples argument defines the number of samples to be retrieved
198            and  reported.   If  samples is 0 or -s is not specified, pcp2xlsx
199            will sample and report continuously (in real time mode)  or  until
200            the  end  of  the set of PCP archives (in archive mode).  See also
201            -T.
202
203       -S starttime, --start=starttime
204            When reporting archived metrics, the report will be restricted  to
205            those  records logged at or after starttime.  Refer to PCPIntro(1)
206            for a complete description of the syntax for starttime.
207
208       -t interval, --interval=interval
209            Set the reporting interval to something other than the  default  1
210            second.   The  interval  argument  follows the syntax described in
211            PCPIntro(1), and in the simplest form may be an  unsigned  integer
212            (the implied units in this case are seconds).  See also the -T op‐
213            tion.
214
215       -T endtime, --finish=endtime
216            When reporting archived metrics, the report will be restricted  to
217            those  records  logged before or at endtime.  Refer to PCPIntro(1)
218            for a complete description of the syntax for endtime.
219
220            When used to define the runtime before pcp2xlsx will exit,  if  no
221            samples  is given (see -s) then the number of reported samples de‐
222            pends on interval (see -t).  If samples  is  given  then  interval
223            will be adjusted to allow reporting of samples during runtime.  In
224            case all of -T, -s, and -t are given, endtime determines  the  ac‐
225            tual time pcp2xlsx will run.
226
227       -v, --omit-flat
228            Report only set-valued metrics with instances (e.g. disk.dev.read)
229            and omit single-valued ``flat'' metrics  without  instances  (e.g.
230            kernel.all.sysfork).  See -i and -I.
231
232       -V, --version
233            Display version number and exit.
234
235       -y scale, --time-scale=scale
236            Unit/scale  for time metrics, possible values include nanosec, ns,
237            microsec, us, millisec, ms, and so forth up to hour, hr.  This op‐
238            tion  will  not  override possible per-metric specifications.  See
239            also pmParseUnitsStr(3).
240
241       -Y scale, --time-scale-force=scale
242            Like -y but this option will override per-metric specifications.
243
244       -z, --hostzone
245            Use the local timezone of the host that is the source of the  per‐
246            formance  metrics,  as  identified  by either the -h or the -a op‐
247            tions.  The default is to use the timezone of the local host.
248
249       -Z timezone, --timezone=timezone
250            Use timezone for the date and time.  Timezone is in the format  of
251            the environment variable TZ as described in environ(7).  Note that
252            when including a timezone string in output, ISO  8601  -style  UTC
253            offsets are used (so something like -Z EST+5 will become UTC-5).
254
255       -?, --help
256            Display usage message and exit.
257

FILES

259       pcp2xlsx.conf
260            pcp2xlsx configuration file (see -c)
261

PCP ENVIRONMENT

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

SEE ALSO

272       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
273       pcp2influxdb(1), pcp2json(1), pcp2spark(1), pcp2xml(1),  pcp2zabbix(1),
274       pmcd(1),  pminfo(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3), pm‐
275       LoadDerivedConfig(3), pmParseUnitsStr(3),  pmRegisterDerived(3),  LOGA‐
276       RCHIVE(5), pcp.conf(5), PMNS(5), pmrep.conf(5) and environ(7).
277
278
279
280Performance Co-Pilot                  PCP                          PCP2XLSX(1)
Impressum