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

NAME

6       pcp2json - pcp-to-json metrics exporter
7

SYNOPSIS

9       pcp2json  [-5CEGHIjLmnrRvVxXz?]  [-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).  Refer to  pmrep(1)  for  the
24       metricspec  description  accepted  on  pcp2json  command line.  See pm‐
25       rep.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 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       pcp2json uses a configuration file with overall 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 output option is recognized but ignored for pm‐
48       rep.conf compatibility.
49
50   pcp2json specific options
51       extended (boolean)
52           Write extended information about  metrics.   Corresponding  command
53           line option is -x.  Default is no.
54
55       everything (boolean)
56           Write  everything  known about metrics, including PCP internal IDs.
57           Labels are, however, omitted for backward  compatibility,  use  in‐
58           clude_labels  yes  to  include them as well.  Corresponding command
59           line option is -X.  Default is no.
60
61       exact_types (boolean)
62           Write numbers as number data types,  not  as  strings,  potentially
63           losing  some  precision.   Corresponding command line option is -E.
64           Default is no.
65

OPTIONS

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

FILES

334       pcp2json.conf
335            pcp2json configuration file (see -c)
336

PCP ENVIRONMENT

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

SEE ALSO

347       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
348       pcp2influxdb(1), pcp2spark(1), pcp2xlsx(1), pcp2xml(1),  pcp2zabbix(1),
349       pmcd(1),  pminfo(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3), pm‐
350       LoadDerivedConfig(3), pmParseUnitsStr(3),  pmRegisterDerived(3),  LOGA‐
351       RCHIVE(5), pcp.conf(5), PMNS(5), pmrep.conf(5) and environ(7).
352
353
354
355Performance Co-Pilot                  PCP                          PCP2JSON(1)
Impressum