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  syntax.   This  page  describes pcp2graphite specific options and
27       configuration file differences with pmrep.conf(5).  pmrep(1) also lists
28       some  usage  examples of which most are applicable with pcp2graphite as
29       well.
30
31       Only the command line options listed on this page are supported,  other
32       options available for 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 syntax described in pm‐
42       rep.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 rest
48       of the pmrep.conf options are recognized but ignored for compatibility.
49
50   pcp2graphite specific options
51       graphite_host (string)
52           Specify the destination Graphite server  hostname  or  IP  address.
53           Corresponding command line option is -g.  Defaults to localhost.
54
55       graphite_port (integer)
56           Specify  the  port  number  of  the  Graphite  server (plaintext or
57           pickle).  Corresponding command line options are -p  and  -E.   De‐
58           faults to 2004.
59
60       pickle (boolean)
61           Specify  whether to use the pickle protocol.  Corresponding command
62           line options are -p and -E.  Defaults to yes.
63
64       pickle_protocol (integer)
65           Specify the pickle protocol version.   Corresponding  command  line
66           option is -X.  Defaults to 0.
67
68       prefix (string)
69           Specify  the  prefix for metrics sent to the server.  Corresponding
70           command line option is -x.  Defaults to pcp..
71

OPTIONS

73       The available command line options are:
74
75       -0 precision, --precision-force=precision
76            Like -P but this option will override per-metric specifications.
77
78       -4 action, --names-change=action
79            Specify which action to take on receiving a  metric  names  change
80            event  during  sampling.  These events occur when a PMDA discovers
81            new metrics sometime after starting up, and informs running client
82            tools  like pcp2graphite.  Valid values for action are update (re‐
83            fresh metrics being sampled), ignore (do nothing - the default be‐
84            haviour) and abort (exit the program if such an event occurs).
85
86       -5, --ignore-unknown
87            Silently ignore any metric name that cannot be resolved.  At least
88            one metric must be found for the tool to start.
89
90       -8 limit, --limit-filter=limit
91            Limit results to instances with values above/below limit.  A posi‐
92            tive  integer  will  include instances with values at or above the
93            limit in reporting.  A negative  integer  will  include  instances
94            with  values  at or below the limit in reporting.  A value of zero
95            performs no limit filtering.  This option will not override possi‐
96            ble per-metric specifications.  See also -J and -N.
97
98       -9 limit, --limit-filter-force=limit
99            Like -8 but this option will override per-metric specifications.
100
101       -a archive, --archive=archive
102            Performance  metric  values  are retrieved from the set of Perfor‐
103            mance Co-Pilot (PCP) archive log files identified by  the  archive
104            argument,  which is a comma-separated list of names, each of which
105            may be the base name of an archive or the name of a directory con‐
106            taining one or more archives.
107
108       -A align, --align=align
109            Force  the initial sample to be aligned on the boundary of a natu‐
110            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
111            tion of the syntax for align.
112
113       --archive-folio=folio
114            Read  metric source archives from the PCP archive folio created by
115            tools like pmchart(1) or, less often, manually with mkaf(1).
116
117       -b scale, --space-scale=scale
118            Unit/scale for  space  (byte)  metrics,  possible  values  include
119            bytes, Kbytes, KB, Mbytes, MB, and so forth.  This option will not
120            override possible per-metric specifications.  See  also  pmParseU‐
121            nitsStr(3).
122
123       -B scale, --space-scale-force=scale
124            Like -b but this option will override per-metric specifications.
125
126       -c config, --config=config
127            Specify  the config file or directory to use.  In case config is a
128            directory all files in it ending .conf will be included.  The  de‐
129            fault    is    the    first    found    of:   ./pcp2graphite.conf,
130            $HOME/.pcp2graphite.conf,     $HOME/pcp/pcp2graphite.conf,     and
131            $PCP_SYSCONF_DIR/pcp2graphite.conf.   For  details,  see the above
132            section and pmrep.conf(5).
133
134       --container=container
135            Fetch performance metrics from the specified container, either lo‐
136            cal or remote (see -h).
137
138       -C, --check
139            Exit before reporting any values, but after parsing the configura‐
140            tion and metrics and printing possible headers.
141
142       --daemonize
143            Daemonize on startup.
144
145       -e derived, --derived=derived
146            Specify derived performance metrics.  If  derived  starts  with  a
147            slash  (``/'')  or  with a dot (``.'') it will be interpreted as a
148            PCP derived metrics configuration file, otherwise it will  be  in‐
149            terpreted  as comma- or semicolon-separated derived metric expres‐
150            sions.  For complete description of derived metrics  and  PCP  de‐
151            rived  metrics  configuration files see pmLoadDerivedConfig(3) and
152            pmRegisterDerived(3).  Alternatively, using pmrep.conf(5) configu‐
153            ration  syntax  allows defining derived metrics as part of metric‐
154            sets.
155
156       -E port, --text-port=port
157            Graphite server plaintext port.  Using this  option  disables  the
158            pickle protocol.
159
160       -g server, --graphite-host=server
161            Destination Graphite server hostname or IP address.
162
163       -G, --no-globals
164            Do not include global metrics in reporting (see pmrep.conf(5)).
165
166       -h host, --host=host
167            Fetch  performance  metrics from pmcd(1) on host, rather than from
168            the default localhost.
169
170       -H, --no-header
171            Do not print any headers.
172
173       -i instances, --instances=instances
174            Retrieve and report only the specified metric instances.   By  de‐
175            fault all instances, present and future, are reported.
176
177            Refer to pmrep(1) for complete description of this option.
178
179       -I, --ignore-incompat
180            Ignore  incompatible  metrics.   By  default  incompatible metrics
181            (that is, their type is unsupported or they cannot  be  scaled  as
182            requested) will cause pcp2graphite to terminate with an error mes‐
183            sage.  With this option  all  incompatible  metrics  are  silently
184            omitted  from  reporting.   This may be especially useful when re‐
185            questing non-leaf nodes of the PMNS tree for reporting.
186
187       -j, --live-filter
188            Perform instance live filtering.  This allows capturing all  named
189            instances  even  if  processes are restarted at some point (unlike
190            without live filtering).  Performing live filtering  over  a  huge
191            number  of  instances  will add some internal overhead so a bit of
192            user caution is advised.  See also -n.
193
194       -J rank, --rank=rank
195            Limit results to highest/lowest  ranked  instances  of  set-valued
196            metrics.  A positive integer will include highest valued instances
197            in reporting.  A negative integer will include lowest  valued  in‐
198            stances in reporting.  A value of zero performs no ranking.  Rank‐
199            ing does not imply sorting, see -6.  See also -8.
200
201       -K spec, --spec-local=spec
202            When fetching metrics from a local context (see -L), the -K option
203            may  be used to control the DSO PMDAs that should be made accessi‐
204            ble.  The spec argument conforms to the syntax  described  in  pm‐
205            SpecLocalPMDA(3).  More than one -K option may be used.
206
207       -L, --local-PMDA
208            Use a local context to collect metrics from DSO PMDAs on the local
209            host without PMCD.  See also -K.
210
211       -n, --invert-filter
212            Perform ranking before live filtering.  By default  instance  live
213            filtering (when requested, see -j) happens before instance ranking
214            (when requested, see -J).  With this option the logic is  inverted
215            and ranking happens before live filtering.
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 port, --pickle-port=port
240            Graphite server pickle port.  Using this option enables the pickle
241            protocol.
242
243       -P precision, --precision=precision
244            Use precision for numeric non-integer output values.  The  default
245            is  to  use  3 decimal places (when applicable).  This option will
246            not override possible per-metric specifications.
247
248       -q scale, --count-scale=scale
249            Unit/scale for count metrics,  possible  values  include  count  x
250            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
251            10^7.  (These values are currently space-sensitive.)  This  option
252            will  not  override  possible per-metric specifications.  See also
253            pmParseUnitsStr(3).
254
255       -Q scale, --count-scale-force=scale
256            Like -q but this option will override per-metric specifications.
257
258       -r, --raw
259            Output raw metric values, do not convert  cumulative  counters  to
260            rates.   This  option will override possible per-metric specifica‐
261            tions.
262
263       -R, --raw-prefer
264            Like -r but this option will not  override  per-metric  specifica‐
265            tions.
266
267       -s samples, --samples=samples
268            The samples argument defines the number of samples to be retrieved
269            and  reported.   If  samples  is  0  or  -s  is   not   specified,
270            pcp2graphite  will  sample  and  report continuously (in real time
271            mode) or until the end of the set  of  PCP  archives  (in  archive
272            mode).  See also -T.
273
274       -S starttime, --start=starttime
275            When  reporting archived metrics, the report will be restricted to
276            those records logged at or after starttime.  Refer to  PCPIntro(1)
277            for a complete description of the syntax for starttime.
278
279       -t interval, --interval=interval
280            Set  the  reporting interval to something other than the default 1
281            second.  The interval argument follows  the  syntax  described  in
282            PCPIntro(1),  and  in the simplest form may be an unsigned integer
283            (the implied units in this case are seconds).  See also the -T op‐
284            tion.
285
286       -T endtime, --finish=endtime
287            When  reporting archived metrics, the report will be restricted to
288            those records logged before or at endtime.  Refer  to  PCPIntro(1)
289            for a complete description of the syntax for endtime.
290
291            When  used to define the runtime before pcp2graphite will exit, if
292            no samples is given (see -s) then the number of  reported  samples
293            depends  on  interval (see -t).  If samples is given then interval
294            will be adjusted to allow reporting of samples during runtime.  In
295            case  all  of -T, -s, and -t are given, endtime determines the ac‐
296            tual time pcp2graphite will run.
297
298       -v, --omit-flat
299            Report only set-valued metrics with instances (e.g. disk.dev.read)
300            and  omit  single-valued  ``flat'' metrics without instances (e.g.
301            kernel.all.sysfork).  See -i and -I.
302
303       -V, --version
304            Display version number and exit.
305
306       -x prefix, --prefix=prefix
307            Metrics prefix for measurements sent to the server.
308
309       -X protocol, --pickle-protocol=protocol
310            Pickle protocol version number.
311
312       -y scale, --time-scale=scale
313            Unit/scale for time metrics, possible values include nanosec,  ns,
314            microsec, us, millisec, ms, and so forth up to hour, hr.  This op‐
315            tion will not override possible  per-metric  specifications.   See
316            also pmParseUnitsStr(3).
317
318       -Y scale, --time-scale-force=scale
319            Like -y but this option will override per-metric specifications.
320
321       -?, --help
322            Display usage message and exit.
323

FILES

325       pcp2graphite.conf
326            pcp2graphite configuration file (see -c)
327
328       $PCP_SYSCONF_DIR/pmrep/*.conf
329            system provided default pmrep configuration files
330

PCP ENVIRONMENT

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

SEE ALSO

341       PCPIntro(1),  mkaf(1),  pcp(1),  pcp2elasticsearch(1), pcp2influxdb(1),
342       pcp2json(1),  pcp2spark(1),  pcp2xlsx(1),  pcp2xml(1),   pcp2zabbix(1),
343       pmcd(1),  pminfo(1), pmrep(1), pmGetOptions(3), pmLoadDerivedConfig(3),
344       pmParseUnitsStr(3),  pmRegisterDerived(3),  pmSpecLocalPMDA(3),   LOGA‐
345       RCHIVE(5), pcp.conf(5), pmrep.conf(5) and PMNS(5).
346
347
348
349Performance Co-Pilot                  PCP                      PCP2GRAPHITE(1)
Impressum