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

NAME

6       pcp2xml - pcp-to-xml metrics exporter
7

SYNOPSIS

9       pcp2xml  [-5CGHIjLmnrRvVxXz?]   [-4  action] [-8|-9 limit] [-a archive]
10       [-A align] [--archive-folio  folio]  [-b|-B  space-scale]  [-c  config]
11       [--container container] [--daemonize] [-e derived] [-f format] [-F out‐
12       file] [-h host] [-i instances] [-J rank] [-K spec] [-N  predicate]  [-O
13       origin]  [-P|-0  precision] [-q|-Q count-scale] [-s samples] [-S start‐
14       time] [-t interval] [-T endtime] [-y|-Y time-scale] [-Z timezone]  met‐
15       ricspec [...]
16

DESCRIPTION

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

CONFIGURATION FILE

40       pcp2xml  uses  a  configuration  file  with  syntax  described  in  pm‐
41       rep.conf(5).   The  following  options are common with pmrep.conf: ver‐
42       sion, source, speclocal, derived, header, globals,  samples,  interval,
43       type,  type_prefer, ignore_incompat, names_change, instances, live_fil‐
44       ter, rank, limit_filter, limit_filter_force, invert_filter,  predicate,
45       omit_flat,  include_labels,  precision,  precision_force,  count_scale,
46       count_scale_force,    space_scale,    space_scale_force,    time_scale,
47       time_scale_force.   The  rest  of the pmrep.conf options are recognized
48       but ignored for compatibility.
49
50   pcp2xml specific options
51       extended (boolean)
52           Write extended information about  metrics.   Corresponding  command
53           line option is -x.  Defaults to no.
54
55       everything (boolean)
56           Write  everything  known about metrics, including PCP internal IDs.
57           Labels are, however, omitted for  backward  compatibility.   Enable
58           include_labels to include them as well.  Corresponding command line
59           option is -X.  Defaults to no.
60

OPTIONS

62       The available command line options are:
63
64       -0 precision, --precision-force=precision
65            Like -P but this option will override per-metric specifications.
66
67       -4 action, --names-change=action
68            Specify which action to take on receiving a  metric  names  change
69            event  during  sampling.  These events occur when a PMDA discovers
70            new metrics sometime after starting up, and informs running client
71            tools  like  pcp2xml.  Valid values for action are update (refresh
72            metrics being sampled), ignore (do nothing -  the  default  behav‐
73            iour) and abort (exit the program if such an event occurs).
74
75       -5, --ignore-unknown
76            Silently ignore any metric name that cannot be resolved.  At least
77            one metric must be found for the tool to start.
78
79       -8 limit, --limit-filter=limit
80            Limit results to instances with values above/below limit.  A posi‐
81            tive  integer  will  include instances with values at or above the
82            limit in reporting.  A negative  integer  will  include  instances
83            with  values  at or below the limit in reporting.  A value of zero
84            performs no limit filtering.  This option will not override possi‐
85            ble per-metric specifications.  See also -J and -N.
86
87       -9 limit, --limit-filter-force=limit
88            Like -8 but this option will override per-metric specifications.
89
90       -a archive, --archive=archive
91            Performance  metric  values  are retrieved from the set of Perfor‐
92            mance Co-Pilot (PCP) archive log files identified by  the  archive
93            argument,  which is a comma-separated list of names, each of which
94            may be the base name of an archive or the name of a directory con‐
95            taining one or more archives.
96
97       -A align, --align=align
98            Force  the initial sample to be aligned on the boundary of a natu‐
99            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
100            tion of the syntax for align.
101
102       --archive-folio=folio
103            Read  metric source archives from the PCP archive folio created by
104            tools like pmchart(1) or, less often, manually with mkaf(1).
105
106       -b scale, --space-scale=scale
107            Unit/scale for  space  (byte)  metrics,  possible  values  include
108            bytes, Kbytes, KB, Mbytes, MB, and so forth.  This option will not
109            override possible per-metric specifications.  See  also  pmParseU‐
110            nitsStr(3).
111
112       -B scale, --space-scale-force=scale
113            Like -b but this option will override per-metric specifications.
114
115       -c config, --config=config
116            Specify  the config file or directory to use.  In case config is a
117            directory all files in it ending .conf will be included.  The  de‐
118            fault  is the first found of: ./pcp2xml.conf, $HOME/.pcp2xml.conf,
119            $HOME/pcp/pcp2xml.conf,  and  $PCP_SYSCONF_DIR/pcp2xml.conf.   For
120            details, see the above section and pmrep.conf(5).
121
122       --container=container
123            Fetch performance metrics from the specified container, either lo‐
124            cal or remote (see -h).
125
126       -C, --check
127            Exit before reporting any values, but after parsing the configura‐
128            tion and metrics and printing possible headers.
129
130       --daemonize
131            Daemonize on startup.
132
133       -e derived, --derived=derived
134            Specify  derived  performance  metrics.   If derived starts with a
135            slash (``/'') or with a dot (``.'') it will be  interpreted  as  a
136            PCP  derived  metrics configuration file, otherwise it will be in‐
137            terpreted as comma- or semicolon-separated derived metric  expres‐
138            sions.   For  complete  description of derived metrics and PCP de‐
139            rived metrics configuration files see  pmLoadDerivedConfig(3)  and
140            pmRegisterDerived(3).  Alternatively, using pmrep.conf(5) configu‐
141            ration syntax allows defining derived metrics as part  of  metric‐
142            sets.
143
144       -G, --no-globals
145            Do not include global metrics in reporting (see pmrep.conf(5)).
146
147       -f format, --timestamp-format=format
148            Use  the  format  string for formatting the timestamp.  The format
149            will be used  with  Python's  datetime.strftime  method  which  is
150            mostly  the same as that described in strftime(3).  The default is
151            %Y-%m-%d %H:%M:%S.
152
153       -F outfile, --output-file=outfile
154            Specify the output file outfile.
155
156       -h host, --host=host
157            Fetch performance metrics from pmcd(1) on host, rather  than  from
158            the default localhost.
159
160       -H, --no-header
161            Do not print any headers.
162
163       -i instances, --instances=instances
164            Retrieve  and  report only the specified metric instances.  By de‐
165            fault all instances, present and future, are reported.
166
167            Refer to pmrep(1) for complete description of this option.
168
169       -I, --ignore-incompat
170            Ignore incompatible  metrics.   By  default  incompatible  metrics
171            (that  is,  their  type is unsupported or they cannot be scaled as
172            requested) will cause pcp2xml to terminate with an error  message.
173            With  this  option  all  incompatible metrics are silently omitted
174            from reporting.  This may be  especially  useful  when  requesting
175            non-leaf nodes of the PMNS tree for reporting.
176
177       -j, --live-filter
178            Perform  instance live filtering.  This allows capturing all named
179            instances even if processes are restarted at  some  point  (unlike
180            without  live  filtering).   Performing live filtering over a huge
181            number of instances will add some internal overhead so  a  bit  of
182            user caution is advised.  See also -n.
183
184       -J rank, --rank=rank
185            Limit  results  to  highest/lowest  ranked instances of set-valued
186            metrics.  A positive integer will include highest valued instances
187            in  reporting.   A negative integer will include lowest valued in‐
188            stances in reporting.  A value of zero performs no ranking.  Rank‐
189            ing does not imply sorting, see -6.  See also -8.
190
191       -K spec, --spec-local=spec
192            When fetching metrics from a local context (see -L), the -K option
193            may be used to control the DSO PMDAs that should be made  accessi‐
194            ble.   The  spec  argument conforms to the syntax described in pm‐
195            SpecLocalPMDA(3).  More than one -K option may be used.
196
197       -L, --local-PMDA
198            Use a local context to collect metrics from DSO PMDAs on the local
199            host without PMCD.  See also -K.
200
201       -m, --include-labels
202            Include PCP metric labels in the output.
203
204       -n, --invert-filter
205            Perform  ranking  before live filtering.  By default instance live
206            filtering (when requested, see -j) happens before instance ranking
207            (when  requested, see -J).  With this option the logic is inverted
208            and ranking happens before live filtering.
209
210       -N predicate, --predicate=predicate
211            Specify a comma-separated list of predicate filter reference  met‐
212            rics.   By  default ranking (see -J) happens for each metric indi‐
213            vidually.  With predicates, ranking is done only for the specified
214            predicate  metrics.   When  reporting, rest of the metrics sharing
215            the same instance domain (see PCPIntro(1)) as the  predicate  will
216            include  only  the  highest/lowest ranking instances of the corre‐
217            sponding predicate.  Ranking does not imply sorting, see -6.
218
219            So for example, using proc.memory.rss  (resident  memory  size  of
220            process) as the predicate metric together with proc.io.total_bytes
221            and mem.util.used as metrics to be reported,  only  the  processes
222            using  most/least (as per -J) memory will be included when report‐
223            ing total bytes written by processes.  Since  mem.util.used  is  a
224            single-valued metric (thus not sharing the same instance domain as
225            the process related metrics), it will be reported as usual.
226
227       -O origin, --origin=origin
228            When reporting archived metrics, start reporting at origin  within
229            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
230            plete description of the syntax for origin.
231
232       -P precision, --precision=precision
233            Use precision for numeric non-integer output values.  The  default
234            is  to  use  3 decimal places (when applicable).  This option will
235            not override possible per-metric specifications.
236
237       -q scale, --count-scale=scale
238            Unit/scale for count metrics,  possible  values  include  count  x
239            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
240            10^7.  (These values are currently space-sensitive.)  This  option
241            will  not  override  possible per-metric specifications.  See also
242            pmParseUnitsStr(3).
243
244       -Q scale, --count-scale-force=scale
245            Like -q but this option will override per-metric specifications.
246
247       -r, --raw
248            Output raw metric values, do not convert  cumulative  counters  to
249            rates.   This  option will override possible per-metric specifica‐
250            tions.
251
252       -R, --raw-prefer
253            Like -r but this option will not  override  per-metric  specifica‐
254            tions.
255
256       -s samples, --samples=samples
257            The samples argument defines the number of samples to be retrieved
258            and reported.  If samples is 0 or -s  is  not  specified,  pcp2xml
259            will  sample  and report continuously (in real time mode) or until
260            the end of the set of PCP archives (in archive  mode).   See  also
261            -T.
262
263       -S starttime, --start=starttime
264            When  reporting archived metrics, the report will be restricted to
265            those records logged at or after starttime.  Refer to  PCPIntro(1)
266            for a complete description of the syntax for starttime.
267
268       -t interval, --interval=interval
269            Set  the  reporting interval to something other than the default 1
270            second.  The interval argument follows  the  syntax  described  in
271            PCPIntro(1),  and  in the simplest form may be an unsigned integer
272            (the implied units in this case are seconds).  See also the -T op‐
273            tion.
274
275       -T endtime, --finish=endtime
276            When  reporting archived metrics, the report will be restricted to
277            those records logged before or at endtime.  Refer  to  PCPIntro(1)
278            for a complete description of the syntax for endtime.
279
280            When  used  to  define the runtime before pcp2xml will exit, if no
281            samples is given (see -s) then the number of reported samples  de‐
282            pends  on  interval  (see  -t).  If samples is given then interval
283            will be adjusted to allow reporting of samples during runtime.  In
284            case  all  of -T, -s, and -t are given, endtime determines the ac‐
285            tual time pcp2xml will run.
286
287       -v, --omit-flat
288            Report only set-valued metrics with instances (e.g. disk.dev.read)
289            and  omit  single-valued  ``flat'' metrics without instances (e.g.
290            kernel.all.sysfork).  See -i and -I.
291
292       -V, --version
293            Display version number and exit.
294
295       -x, --with-extended
296            Write extended information.
297
298       -X, --with-everything
299            Write everything known about metrics, including PCP internal  IDs.
300            Labels are, however, omitted for backward compatibility, use -m to
301            include them as well.
302
303       -y scale, --time-scale=scale
304            Unit/scale for time metrics, possible values include nanosec,  ns,
305            microsec, us, millisec, ms, and so forth up to hour, hr.  This op‐
306            tion will not override possible  per-metric  specifications.   See
307            also pmParseUnitsStr(3).
308
309       -Y scale, --time-scale-force=scale
310            Like -y but this option will override per-metric specifications.
311
312       -z, --hostzone
313            Use  the local timezone of the host that is the source of the per‐
314            formance metrics, as identified by either the -h  or  the  -a  op‐
315            tions.  The default is to use the timezone of the local host.
316
317       -Z timezone, --timezone=timezone
318            Use  timezone for the date and time.  Timezone is in the format of
319            the environment variable TZ as described in environ(7).  Note that
320            when  including  a  timezone string in output, ISO 8601 -style UTC
321            offsets are used (so something like -Z EST+5 will become UTC-5).
322
323       -?, --help
324            Display usage message and exit.
325

FILES

327       pcp2xml.conf
328            pcp2xml configuration file (see -c)
329
330       $PCP_SYSCONF_DIR/pmrep/*.conf
331            system provided default pmrep configuration files
332

PCP ENVIRONMENT

334       Environment variables with the prefix PCP_ are used to parameterize the
335       file  and  directory names used by PCP.  On each installation, the file
336       /etc/pcp.conf contains the  local  values  for  these  variables.   The
337       $PCP_CONF  variable may be used to specify an alternative configuration
338       file, as described in pcp.conf(5).
339
340       For environment variables affecting PCP tools, see pmGetOptions(3).
341

SEE ALSO

343       PCPIntro(1), mkaf(1),  pcp(1),  pcp2elasticsearch(1),  pcp2graphite(1),
344       pcp2influxdb(1), pcp2json(1), pcp2spark(1), pcp2xlsx(1), pcp2zabbix(1),
345       pmcd(1), pminfo(1), pmrep(1), pmGetOptions(3),  pmLoadDerivedConfig(3),
346       pmParseUnitsStr(3),   pmRegisterDerived(3),  pmSpecLocalPMDA(3),  LOGA‐
347       RCHIVE(5), pcp.conf(5), pmrep.conf(5), PMNS(5) and environ(7).
348
349
350
351Performance Co-Pilot                  PCP                           PCP2XML(1)
Impressum