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

NAME

6       pcp2xml - pcp-to-xml metrics exporter
7

SYNOPSIS

9       pcp2xml [-5CGHIjLnrRvVxXz?]  [-4 action] [-8|-9 limit] [-a archive] [-A
10       align] [--archive-folio folio] [-b|-B space-scale] [-c config]  [--con‐
11       tainer  container]  [--daemonize] [-e derived] [-f format] [-F outfile]
12       [-h host] [-i instances] [-J rank] [-K spec] [-N predicate] [-O origin]
13       [-P|-0  precision]  [-q|-Q count-scale] [-s samples] [-S starttime] [-t
14       interval] [-T endtime]  [-y|-Y  time-scale]  [-Z  timezone]  metricspec
15       [...]
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).  Please refer to pmrep(1)  for
24       the  metricspec  description  accepted  on  pcp2xml  command  line  and
25       pmrep.conf(5) for description of the  pcp2xml.conf  configuration  file
26       overall  syntax,  this page describes pcp2xml specific options and con‐
27       figuration file differences with pmrep.conf(5).   pmrep(1)  also  lists
28       some usage 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 recognized by 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
35       options override the  corresponding  environment  variables  (if  any).
36       Command  line  options  override  the  corresponding configuration file
37       options (if any).
38

CONFIGURATION FILE

40       pcp2xml uses a configuration file  with  overall  syntax  described  in
41       pmrep.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,  precision, precision_force, count_scale, count_scale_force,
46       space_scale, space_scale_force, time_scale, time_scale_force.  The out‐
47       put option is recognized but ignored for pmrep.conf compatibility.
48
49   pcp2xml specific options
50       extended (boolean)
51           Write  extended  information  about metrics.  Corresponding command
52           line option is -x.  Default is no.
53
54       everything (boolean)
55           Write everything known about metrics, including PCP  internal  IDs.
56           Corresponding command line option is -X.  Default is no.
57

OPTIONS

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

FILES

319       pcp2xml.conf
320              pcp2xml configuration file (see -c)
321

PCP ENVIRONMENT

323       Environment variables with the prefix PCP_ are used to parameterize the
324       file and directory names used by PCP.  On each installation,  the  file
325       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
326       $PCP_CONF variable may be used to specify an alternative  configuration
327       file, as described in pcp.conf(5).
328
329       For environment variables affecting PCP tools, see pmGetOptions(3).
330

SEE ALSO

332       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
333       pcp2influxdb(1), pcp2json(1), pcp2spark(1), pcp2xlsx(1), pcp2zabbix(1),
334       pmcd(1),   pminfo(1),  pmrep(1),  pmGetOptions(3),  pmSpecLocalPMDA(3),
335       pmLoadDerivedConfig(3), pmParseUnitsStr(3), pmRegisterDerived(3), LOGA‐
336       RCHIVE(5), pcp.conf(5), pmns(5), pmrep.conf(5) and environ(7).
337
338
339
340Performance Co-Pilot                  PCP                           PCP2XML(1)
Impressum