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

NAME

6       pcp2graphite - pcp-to-graphite metrics exporter
7

SYNOPSIS

9       pcp2graphite  [-5CGHIjLnrRvV?]   [-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] [-E text-port] [-g
12       server] [-h host] [-i instances] [-J rank] [-K spec] [-N predicate] [-O
13       origin] [-p pickle-port] [-P|-0 precision] [-q|-Q count-scale] [-s sam‐
14       ples] [-S starttime] [-t interval] [-T endtime] [-x prefix] [-X pickle-
15       protocol] [-y|-Y time-scale] metricspec [...]
16

DESCRIPTION

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

CONFIGURATION FILE

41       pcp2graphite uses a configuration file with overall syntax described in
42       pmrep.conf(5).  The following options are common with pmrep.conf:  ver‐
43       sion,  source,  speclocal, derived, header, globals, samples, interval,
44       type, type_prefer, ignore_incompat, names_change, instances,  live_fil‐
45       ter,  rank, limit_filter, limit_filter_force, invert_filter, predicate,
46       omit_flat, precision, precision_force, count_scale,  count_scale_force,
47       space_scale, space_scale_force, time_scale, time_scale_force.  The out‐
48       put option is recognized but ignored for pmrep.conf compatibility.
49
50   pcp2graphite specific options
51       graphite_host (string)
52           Hostname or IP address of Graphite server to send the  metrics  to.
53           Corresponding command line option is -g.  Default is localhost.
54
55       graphite_port (integer)
56           Specify port number of Graphite server (plaintext or pickle).  Cor‐
57           responding command line options are -p and -E.  Default is 2004.
58
59       pickle (boolean)
60           Specify whether to use pickle protocol.  Corresponding command line
61           options are -p and -E.  Default is yes.
62
63       pickle_protocol (integer)
64           Specify pickle protocol version.  Corresponding command line option
65           is -X.  Default is 0.
66
67       prefix (string)
68           Specify the prefix for metrics sent to the  server.   Corresponding
69           command line option is -x.  Default is pcp..
70

OPTIONS

72       The available command line options are:
73
74       -0 precision, --precision-force=precision
75            Like -P but this option will override per-metric specifications.
76
77       -4 action, --names-change=action
78            Specify  which  action  to take on receiving a metric names change
79            event during sampling.  These events occur when a  PMDA  discovers
80            new metrics sometime after starting up, and informs running client
81            tools like pcp2graphite.  Valid values for action are update  (re‐
82            fresh metrics being sampled), ignore (do nothing - the default be‐
83            haviour) and abort (exit the program if such an event happens).
84
85       -5, --ignore-unknown
86            Silently ignore any metric name that cannot be resolved.  At least
87            one metric must be found for the tool to start.
88
89       -8 limit, --limit-filter=limit
90            Limit results to instances with values above/below limit.  A posi‐
91            tive integer will include instances with values at  or  above  the
92            limit  in  reporting.   A  negative integer will include instances
93            with values at or below the limit in reporting.  A value  of  zero
94            performs no limit filtering.  This option will not override possi‐
95            ble per-metric specifications.  See also -J and -N.
96
97       -9 limit, --limit-filter-force=limit
98            Like -8 but this option will override per-metric specifications.
99
100       -a archive, --archive=archive
101            Performance metric values are retrieved from the  set  of  Perfor‐
102            mance  Co-Pilot  (PCP) archive log files identified by the archive
103            argument, which is a comma-separated list of names, each of  which
104            may be the base name of an archive or the name of a directory con‐
105            taining one or more archives.
106
107       -A align, --align=align
108            Force the initial sample to be aligned on the boundary of a  natu‐
109            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
110            tion of the syntax for align.
111
112       --archive-folio=folio
113            Read metric source archives from the PCP archive folio created  by
114            tools like pmchart(1) or, less often, manually with mkaf(1).
115
116       -b scale, --space-scale=scale
117            Unit/scale  for  space  (byte)  metrics,  possible  values include
118            bytes, Kbytes, KB, Mbytes, MB, and so forth.  This option will not
119            override  possible  per-metric specifications.  See also pmParseU‐
120            nitsStr(3).
121
122       -B scale, --space-scale-force=scale
123            Like -b but this option will override per-metric specifications.
124
125       -c config, --config=config
126            Specify the config file or directory to use.  In case config is  a
127            directory  all  files under it ending .conf will be included.  The
128            default   is   the   first    found    of:    ./pcp2graphite.conf,
129            $HOME/.pcp2graphite.conf,     $HOME/pcp/pcp2graphite.conf,     and
130            $PCP_SYSCONF_DIR/pcp2graphite.conf.  For details,  see  the  above
131            section and pmrep.conf(5).
132
133       --container=container
134            Fetch performance metrics from the specified container, either lo‐
135            cal or remote (see -h).
136
137       -C, --check
138            Exit before reporting any values, but after parsing the configura‐
139            tion and metrics and printing possible headers.
140
141       --daemonize
142            Daemonize on startup.
143
144       -e derived, --derived=derived
145            Specify  derived  performance  metrics.   If derived starts with a
146            slash (``/'') or with a dot (``.'') it will be  interpreted  as  a
147            derived  metrics  configuration  file, otherwise it will be inter‐
148            preted as comma- or  semicolon-separated  derived  metric  expres‐
149            sions.   For  details  see  pmLoadDerivedConfig(3) and pmRegister‐
150            Derived(3).
151
152       -E port, --text-port=port
153            Graphite server plaintext port.  Using this  option  disables  the
154            pickle protocol.
155
156       -g server, --graphite-host=server
157            Graphite server to send the metrics to.
158
159       -G, --no-globals
160            Do not include global metrics in reporting (see pmrep.conf(5)).
161
162       -h host, --host=host
163            Fetch  performance  metrics from pmcd(1) on host, rather than from
164            the default localhost.
165
166       -H, --no-header
167            Do not print any headers.
168
169       -i instances, --instances=instances
170            Retrieve and report only the specified metric instances.   By  de‐
171            fault all instances, present and future, are reported.
172
173            Refer to pmrep(1) for complete description of this option.
174
175       -I, --ignore-incompat
176            Ignore  incompatible  metrics.   By  default  incompatible metrics
177            (that is, their type is unsupported or they cannot  be  scaled  as
178            requested) will cause pcp2graphite to terminate with an error mes‐
179            sage.  With this option  all  incompatible  metrics  are  silently
180            omitted  from  reporting.   This may be especially useful when re‐
181            questing non-leaf nodes of the PMNS tree for reporting.
182
183       -j, --live-filter
184            Perform instance live filtering.  This allows capturing all  named
185            instances  even  if  processes are restarted at some point (unlike
186            without live filtering).  Performing live filtering  over  a  huge
187            number  of  instances  will add some internal overhead so a bit of
188            user caution is advised.  See also -n.
189
190       -J rank, --rank=rank
191            Limit results to highest/lowest  ranked  instances  of  set-valued
192            metrics.  A positive integer will include highest valued instances
193            in reporting.  A negative integer will include lowest  valued  in‐
194            stances in reporting.  A value of zero performs no ranking.  Rank‐
195            ing does not imply sorting, see -6.  See also -8.
196
197       -K spec, --spec-local=spec
198            When fetching metrics from a local context (see -L), the -K option
199            may  be used to control the DSO PMDAs that should be made accessi‐
200            ble.  The spec argument conforms to the syntax  described  in  pm‐
201            SpecLocalPMDA(3).  More than one -K option may be used.
202
203       -L, --local-PMDA
204            Use a local context to collect metrics from DSO PMDAs on the local
205            host without PMCD.  See also -K.
206
207       -n, --invert-filter
208            Perform ranking before live filtering.  By default  instance  live
209            filtering (when requested, see -j) happens before instance ranking
210            (when requested, see -J).  With this option the logic is  inverted
211            and ranking happens before live filtering.
212
213       -N predicate, --predicate=predicate
214            Specify  a comma-separated list of predicate filter reference met‐
215            rics.  By default ranking (see -J) happens for each  metric  indi‐
216            vidually.  With predicates, ranking is done only for the specified
217            predicate metrics.  When reporting, rest of  the  metrics  sharing
218            the  same  instance domain (see PCPIntro(1)) as the predicate will
219            include only the highest/lowest ranking instances  of  the  corre‐
220            sponding predicate.  Ranking does not imply sorting, see -6.
221
222            So  for  example,  using  proc.memory.rss (resident memory size of
223            process) as the predicate metric together with proc.io.total_bytes
224            and  mem.util.used  as  metrics to be reported, only the processes
225            using most/least (as per -J) memory will be included when  report‐
226            ing  total  bytes  written by processes.  Since mem.util.used is a
227            single-valued metric (thus not sharing the same instance domain as
228            the process related metrics), it will be reported as usual.
229
230       -O origin, --origin=origin
231            When  reporting archived metrics, start reporting at origin within
232            the time window (see -S and -T).  Refer to PCPIntro(1) for a  com‐
233            plete description of the syntax for origin.
234
235       -p port, --pickle-port=port
236            Graphite server pickle port.  Using this option enables the pickle
237            protocol.
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,
266            pcp2graphite  will  sample  and  report continuously (in real time
267            mode) or until the end of the set  of  PCP  archives  (in  archive
268            mode).  See also -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 pcp2graphite will exit, if
288            no samples is given (see -s) then the number of  reported  samples
289            depends  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 pcp2graphite 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 prefix, --prefix=prefix
303            Metrics prefix for measurements sent to the server.
304
305       -X protocol, --pickle-protocol=protocol
306            Pickle protocol version number.
307
308       -y scale, --time-scale=scale
309            Unit/scale for time metrics, possible values include nanosec,  ns,
310            microsec, us, millisec, ms, and so forth up to hour, hr.  This op‐
311            tion will not override possible  per-metric  specifications.   See
312            also pmParseUnitsStr(3).
313
314       -Y scale, --time-scale-force=scale
315            Like -y but this option will override per-metric specifications.
316
317       -?, --help
318            Display usage message and exit.
319

FILES

321       pcp2graphite.conf
322            pcp2graphite configuration file (see -c)
323

PCP ENVIRONMENT

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

SEE ALSO

334       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2influxdb(1),
335       pcp2json(1),  pcp2spark(1),  pcp2xlsx(1),  pcp2xml(1),   pcp2zabbix(1),
336       pmcd(1),  pminfo(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3), pm‐
337       LoadDerivedConfig(3), pmParseUnitsStr(3),  pmRegisterDerived(3),  LOGA‐
338       RCHIVE(5), pcp.conf(5), PMNS(5) and pmrep.conf(5).
339
340
341
342Performance Co-Pilot                  PCP                      PCP2GRAPHITE(1)
Impressum