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).  Please refer to pmrep(1)
24       for  the  metricspec  description accepted on pcp2graphite command line
25       and pmrep.conf(5) for description of the  pcp2graphite.conf  configura‐
26       tion  file  overall  syntax,  this page describes pcp2graphite specific
27       options  and  configuration  file   differences   with   pmrep.conf(5).
28       pmrep(1)  also  lists  some usage examples of which most are applicable
29       with 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
36       options  override  the  corresponding  environment  variables (if any).
37       Command line options  override  the  corresponding  configuration  file
38       options (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
82            (refresh  metrics being sampled), ignore (do nothing - the default
83            behaviour) 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 argument
103            archive, 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 to use.  The default is  the  first  found
127            of:         ./pcp2graphite.conf,         $HOME/.pcp2graphite.conf,
128            $HOME/pcp/pcp2graphite.conf,                                   and
129            $PCP_SYSCONF_DIR/pcp2graphite.conf.   For  details,  see the above
130            section and pmrep.conf(5).
131
132       --container=container
133            Fetch performance metrics from  the  specified  container,  either
134            local or remote (see -h).
135
136       -C, --check
137            Exit before reporting any values, but after parsing the configura‐
138            tion and metrics and printing possible headers.
139
140       --daemonize
141            Daemonize on startup.
142
143       -e derived, --derived=derived
144            Specify derived performance metrics.  If  derived  starts  with  a
145            slash  (``/'')  or  with a dot (``.'') it will be interpreted as a
146            derived metrics configuration file, otherwise it  will  be  inter‐
147            preted  as  comma-  or  semicolon-separated derived metric expres‐
148            sions.  For details  see  pmLoadDerivedConfig(3)  and  pmRegister‐
149            Derived(3).
150
151       -E port, --text-port=port
152            Graphite  server  plaintext  port.  Using this option disables the
153            pickle protocol.
154
155       -g server, --graphite-host=server
156            Graphite server to send the metrics to.
157
158       -G, --no-globals
159            Do not include global metrics in reporting (see pmrep.conf(5)).
160
161       -h host, --host=host
162            Fetch performance metrics from pmcd(1) on host, rather  than  from
163            the default localhost.
164
165       -H, --no-header
166            Do not print any headers.
167
168       -i instances, --instances=instances
169            Report  only  the  listed  instances  from  current  instances (if
170            present, see also -j).  By  default  all  instances,  present  and
171            future,  are  reported.   This is a global option that is used for
172            all metrics unless a metric-specific instance definition  is  pro‐
173            vided  as part of a metricspec.  By default single-valued ``flat''
174            metrics without multiple instances are still  reported  as  usual,
175            use  -v to change this.  Please refer to pmrep(1) for more details
176            on this option.
177
178       -I, --ignore-incompat
179            Ignore incompatible  metrics.   By  default  incompatible  metrics
180            (that  is,  their  type is unsupported or they cannot be scaled as
181            requested) will cause pcp2graphite to terminate with an error mes‐
182            sage.   With  this  option  all  incompatible metrics are silently
183            omitted from  reporting.   This  may  be  especially  useful  when
184            requesting non-leaf nodes of the PMNS tree for reporting.
185
186       -j, --live-filter
187            Perform  instance  live filtering.  This allows capturing all fil‐
188            tered instances even if processes  are  restarted  at  some  point
189            (unlike without live filtering).  Performing live filtering over a
190            huge amount of instances will add some internal overhead so a  bit
191            of user caution is advised.  See also -n.
192
193       -J rank, --rank=rank
194            Limit  results to highest/lowest rank instances of set-valued met‐
195            rics.  A positive integer will include highest valued instances in
196            reporting.    A   negative  integer  will  include  lowest  valued
197            instances in reporting.  A value of zero performs no ranking.  See
198            also -8.
199
200       -K spec, --spec-local=spec
201            When fetching metrics from a local context (see -L), the -K option
202            may be used to control the DSO PMDAs that should be made  accessi‐
203            ble.   The  spec  argument  conforms  to  the  syntax described in
204            pmSpecLocalPMDA(3).  More than one -K option may be used.
205
206       -L, --local-PMDA
207            Use a local context to collect metrics from DSO PMDAs on the local
208            host without PMCD.  See also -K.
209
210       -n, --invert-filter
211            Perform  ranking  before live filtering.  By default instance live
212            filtering (when requested, see -j) happens before instance ranking
213            (when  requested, see -J).  With this option the logic is inverted
214            and ranking happens before live filtering.
215
216       -N predicate, --predicate=predicate
217            Specify a comma-separated list of predicate filter reference  met‐
218            rics.   By  default ranking (see -J) happens for each metric indi‐
219            vidually.  With predicates, ranking is done only for the specified
220            predicate  metrics.   When  reporting, rest of the metrics sharing
221            the same instance domain (see PCPIntro(1)) as the  predicate  will
222            include  only  the  highest/lowest ranking instances of the corre‐
223            sponding predicate.
224
225            So for example, using proc.memory.rss  (resident  memory  size  of
226            process) as the predicate metric together with proc.io.total_bytes
227            and mem.util.used as metrics to be reported,  only  the  processes
228            using  most/least (as per -J) memory will be included when report‐
229            ing total bytes written by processes.  Since  mem.util.used  is  a
230            single-valued metric (thus not sharing the same instance domain as
231            the process-related metrics), it will be reported as usual.
232
233       -O origin, --origin=origin
234            When reporting archived metrics, start reporting at origin  within
235            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
236            plete description of the syntax for origin.
237
238       -p port, --pickle-port=port
239            Graphite server pickle port.  Using this option enables the pickle
240            protocol.
241
242       -P precision, --precision=precision
243            Use  precision for numeric non-integer output values.  The default
244            is to use 3 decimal places (when applicable).   This  option  will
245            not override possible per-metric specifications.
246
247       -q scale, --count-scale=scale
248            Unit/scale  for  count  metrics,  possible  values include count x
249            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
250            10^7.   (These values are currently space-sensitive.)  This option
251            will not override possible per-metric  specifications.   See  also
252            pmParseUnitsStr(3).
253
254       -Q scale, --count-scale-force=scale
255            Like -q but this option will override per-metric specifications.
256
257       -r, --raw
258            Output  raw  metric  values, do not convert cumulative counters to
259            rates.  This option will override possible  per-metric  specifica‐
260            tions.
261
262       -R, --raw-prefer
263            Like  -r  but  this option will not override per-metric specifica‐
264            tions.
265
266       -s samples, --samples=samples
267            The argument samples defines the number of samples to be retrieved
268            and   reported.    If  samples  is  0  or  -s  is  not  specified,
269            pcp2graphite will sample and report  continuously  (in  real  time
270            mode)  or  until  the  end  of the set of PCP archives (in archive
271            mode).  See also -T.
272
273       -S starttime, --start=starttime
274            When reporting archived metrics, the report will be restricted  to
275            those  records logged at or after starttime.  Refer to PCPIntro(1)
276            for a complete description of the syntax for starttime.
277
278       -t interval, --interval=interval
279            The default update interval may be set to something other than the
280            default  1  second.   The  interval  argument  follows  the syntax
281            described in PCPIntro(1), and in  the  simplest  form  may  be  an
282            unsigned  integer  (the  implied  units in this case are seconds).
283            See also the -T option.
284
285       -T endtime, --finish=endtime
286            When reporting archived metrics, the report will be restricted  to
287            those  records  logged before or at endtime.  Refer to PCPIntro(1)
288            for a complete description of the syntax for endtime.
289
290            When used to define the runtime before pcp2graphite will exit,  if
291            no  samples  is given (see -s) then the number of reported samples
292            depends on interval (see -t).  If samples is given  then  interval
293            will be adjusted to allow reporting of samples during runtime.  In
294            case all of -T, -s, and  -t  are  given,  endtime  determines  the
295            actual time pcp2graphite will run.
296
297       -v, --omit-flat
298            Omit  single-valued ``flat'' metrics from reporting, only consider
299            set-valued  metrics  (i.e.,  metrics  with  multiple  values)  for
300            reporting.  See -i and -I.
301
302       -V, --version
303            Display version number and exit.
304
305       -x prefix, --prefix=prefix
306            Metrics prefix for measurements sent to the server.
307
308       -X protocol, --pickle-protocol=protocol
309            Pickle protocol version number.
310
311       -y scale, --time-scale=scale
312            Unit/scale  for time metrics, possible values include nanosec, ns,
313            microsec, us, millisec, ms, and so forth up  to  hour,  hr.   This
314            option  will not override possible per-metric specifications.  See
315            also pmParseUnitsStr(3).
316
317       -Y scale, --time-scale-force=scale
318            Like -y but this option will override per-metric specifications.
319
320       -?, --help
321            Display usage message and exit.
322

FILES

324       pcp2graphite.conf
325              pcp2graphite 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),  pcp2influxdb(1),
338       pcp2json(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) and pmrep.conf(5).
342
343
344
345Performance Co-Pilot                  PCP                      PCP2GRAPHITE(1)
Impressum