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

NAME

6       pcp2xml - pcp-to-xml metrics exporter
7

SYNOPSIS

9       pcp2xml [-CGHIjLnrRvVxXz?]  [-8|-9 limit] [-a archive] [--archive-folio
10       folio] [-A align] [-b|-B space-scale]  [-c  config]  [--container  con‐
11       tainer]  [--daemonize]  [-e derived] [-f format] [-F outfile] [-h host]
12       [-i instances] [-J rank] [-K spec] [-N predicate]  [-O  origin]  [-P|-0
13       precision]  [-q|-Q  count-scale] [-s samples] [-S starttime] [-t inter‐
14       val] [-T endtime] [-y|-Y time-scale] [-Z timezone] metricspec [...]
15

DESCRIPTION

17       pcp2xml is a customizable performance metrics exporter tool from PCP to
18       XML.  Any available performance metric, live or archived, system and/or
19       application, can be selected for exporting using  either  command  line
20       arguments or a configuration file.
21
22       pcp2xml  is a close relative of pmrep(1).  Please refer to pmrep(1) for
23       the  metricspec  description  accepted  on  pcp2xml  command  line  and
24       pmrep.conf(5)  for  description  of the pcp2xml.conf configuration file
25       overall syntax, this page describes pcp2xml 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 pcp2xml 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       pcp2xml  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,  instances,  live_filter,   rank,
43       limit_filter,  limit_filter_force, invert_filter, predicate, omit_flat,
44       precision,     precision_force,     count_scale,     count_scale_force,
45       space_scale, space_scale_force, time_scale, time_scale_force.  The out‐
46       put option is recognized but ignored for pmrep.conf compatibility.
47
48   pcp2xml specific options
49       extended (boolean)
50           Write extended information about  metrics.   Corresponding  command
51           line option is -x.  Default is no.
52
53       everything (boolean)
54           Write  everything  known about metrics, including PCP internal IDs.
55           Corresponding command line option is -X.  Default is no.
56

OPTIONS

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

FILES

306       pcp2xml.conf
307              pcp2xml configuration file (see -c)
308

PCP ENVIRONMENT

310       Environment variables with the prefix PCP_ are used to parameterize the
311       file  and  directory names used by PCP.  On each installation, the file
312       /etc/pcp.conf contains the  local  values  for  these  variables.   The
313       $PCP_CONF  variable may be used to specify an alternative configuration
314       file, as described in pcp.conf(5).
315
316       For environment variables affecting PCP tools, see pmGetOptions(3).
317

SEE ALSO

319       mkaf(1), PCPIntro(1),  pcp(1),  pcp2elasticsearch(1),  pcp2graphite(1),
320       pcp2influxdb(1),   pcp2xlsx(1),   pcp2xml(1),  pcp2zabbix(1),  pmcd(1),
321       pminfo(1),  pmrep(1),  pmGetOptions(3),   pmSpecLocalPMDA(3),   pmLoad‐
322       DerivedConfig(3),   pmParseUnitsStr(3),   pmRegisterDerived(3),   LOGA‐
323       RCHIVE(5), pcp.conf(5), pmns(5), pmrep.conf(5) and environ(7).
324
325
326
327Performance Co-Pilot                  PCP                           PCP2XML(1)
Impressum