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

NAME

6       pcp2json - pcp-to-json metrics exporter
7

SYNOPSIS

9       pcp2json  [-5CEGHIjLnrRvVxXz?]   [-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       pcp2json  is  a customizable performance metrics exporter tool from PCP
19       to JSON.  Any available performance metric, live  or  archived,  system
20       and/or  application, can be selected for exporting using either command
21       line arguments or a configuration file.
22
23       pcp2json is a close relative of pmrep(1).  Please refer to pmrep(1) for
24       the  metricspec  description  accepted  on  pcp2json  command  line and
25       pmrep.conf(5) for description of the pcp2json.conf  configuration  file
26       overall  syntax, this page describes pcp2json 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 pcp2json 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       pcp2json 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   pcp2json 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
58       exact_types (boolean)
59           Write  numbers  as  number  data types, not as strings, potentially
60           losing some precision.  Corresponding command line  option  is  -E.
61           Default is no.
62

OPTIONS

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

FILES

324       pcp2json.conf
325              pcp2json configuration file (see -c)
326

PCP ENVIRONMENT

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

SEE ALSO

337       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
338       pcp2influxdb(1), pcp2spark(1), pcp2xlsx(1), pcp2xml(1),  pcp2zabbix(1),
339       pmcd(1),   pminfo(1),  pmrep(1),  pmGetOptions(3),  pmSpecLocalPMDA(3),
340       pmLoadDerivedConfig(3), pmParseUnitsStr(3), pmRegisterDerived(3), LOGA‐
341       RCHIVE(5), pcp.conf(5), pmns(5), pmrep.conf(5) and environ(7).
342
343
344
345Performance Co-Pilot                  PCP                          PCP2JSON(1)
Impressum