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       syntax.  This page describes pcp2xlsx specific options  and  configura‐
26       tion file differences with pmrep.conf(5).  pmrep(1) also lists some us‐
27       age 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 available for 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  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  rest  of the pmrep.conf options are recognized
46       but ignored for compatibility.
47
48   pcp2xlsx specific options
49       None.
50

OPTIONS

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

FILES

263       pcp2xlsx.conf
264            pcp2xlsx configuration file (see -c)
265
266       $PCP_SYSCONF_DIR/pmrep/*.conf
267            system provided default pmrep configuration files
268

PCP ENVIRONMENT

270       Environment variables with the prefix PCP_ are used to parameterize the
271       file  and  directory names used by PCP.  On each installation, the file
272       /etc/pcp.conf contains the  local  values  for  these  variables.   The
273       $PCP_CONF  variable may be used to specify an alternative configuration
274       file, as described in pcp.conf(5).
275
276       For environment variables affecting PCP tools, see pmGetOptions(3).
277

SEE ALSO

279       PCPIntro(1), mkaf(1),  pcp(1),  pcp2elasticsearch(1),  pcp2graphite(1),
280       pcp2influxdb(1),  pcp2json(1), pcp2spark(1), pcp2xml(1), pcp2zabbix(1),
281       pmcd(1), pminfo(1), pmrep(1), pmGetOptions(3),  pmLoadDerivedConfig(3),
282       pmParseUnitsStr(3),   pmRegisterDerived(3),  pmSpecLocalPMDA(3),  LOGA‐
283       RCHIVE(5), pcp.conf(5), pmrep.conf(5), PMNS(5) and environ(7).
284
285
286
287Performance Co-Pilot                  PCP                          PCP2XLSX(1)
Impressum