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

NAME

6       pcp2xlsx - pcp-to-xlsx metrics exporter
7

SYNOPSIS

9       pcp2xlsx  [-5CGHILrRvVz?]   [-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).  Please refer to pmrep(1) for
23       the metricspec  description  accepted  on  pcp2xlsx  command  line  and
24       pmrep.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
34       options  override  the  corresponding  environment  variables (if any).
35       Command line options  override  the  corresponding  configuration  file
36       options (if any).
37

CONFIGURATION FILE

39       pcp2xlsx  uses  a  configuration  file with overall syntax described in
40       pmrep.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       precision,     precision_force,     count_scale,     count_scale_force,
44       space_scale, space_scale_force, time_scale, time_scale_force.  The out‐
45       put option is recognized but ignored for pmrep.conf compatibility.
46
47       There are no pcp2xlsx specific options.
48

OPTIONS

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

FILES

255       pcp2xlsx.conf
256              pcp2xlsx configuration file (see -c)
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       mkaf(1), PCPIntro(1),  pcp(1),  pcp2elasticsearch(1),  pcp2graphite(1),
269       pcp2influxdb(1),  pcp2json(1), pcp2spark(1), pcp2xml(1), pcp2zabbix(1),
270       pmcd(1),  pminfo(1),  pmrep(1),  pmGetOptions(3),   pmSpecLocalPMDA(3),
271       pmLoadDerivedConfig(3), pmParseUnitsStr(3), pmRegisterDerived(3), LOGA‐
272       RCHIVE(5), pcp.conf(5), pmns(5), pmrep.conf(5) and environ(7).
273
274
275
276Performance Co-Pilot                  PCP                          PCP2XLSX(1)
Impressum