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

NAME

6       pcp2zabbix - pcp-to-zabbix metrics exporter
7

SYNOPSIS

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

DESCRIPTION

18       pcp2zabbix is a customizable performance metrics exporter tool from PCP
19       to Zabbix.  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       pcp2zabbix is a close relative of pmrep(1).  Refer to pmrep(1) for  the
24       metricspec  description  accepted  on pcp2zabbix command line.  See pm‐
25       rep.conf(5) for description of the pcp2zabbix.conf  configuration  file
26       overall  syntax.   This  page describes pcp2zabbix 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 pcp2zabbix as
29       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       pcp2zabbix  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   pcp2zabbix specific options
51       zabbix_server (string)
52           Hostname or IP address of Zabbix server to send the metrics to.  If
53           a host is monitored by a proxy, proxy hostname or IP address should
54           be used instead.  Corresponding command line option is -g.  Default
55           is localhost.
56
57       zabbix_port (integer)
58           Specify  port number of server trapper running on the server.  Cor‐
59           responding command line option is -p.  Default is 10051.
60
61       zabbix_host (string)
62           Specify agent hostname as registered in Zabbix frontend.   Host  IP
63           address and DNS name will not work.  Corresponding command line op‐
64           tion is -X.  Defaults to the metrics source host.
65
66       zabbix_interval (string)
67           Indicates the interval to send the metrics to  the  Zabbix  server.
68           This  can be longer than the generic interval to minimize the over‐
69           head when communicating with the server (as each send creates a new
70           connection).   Follows  the  time  syntax described in PCPIntro(1).
71           Corresponding command line option is -E.  Defaults to  the  generic
72           interval.   Zabbix  tools  send at most 250 metrics at a time.  Ig‐
73           nored when reading metrics from PCP archives, in which case metrics
74           will be sent roughly at 250 metric batches.
75
76       zabbix_prefix (string)
77           Specify  the  prefix for metrics sent to the Zabbix server.  Corre‐
78           sponding command line option is -x.  Default is .pcp.
79
80       zabbix_lld (boolean)
81           Specify whether to enable Zabbix low-level discovery.   Correspond‐
82           ing command line option is -l.  Default is no.
83

OPTIONS

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

FILES

343       pcp2zabbix.conf
344            pcp2zabbix configuration file (see -c)
345

PCP ENVIRONMENT

347       Environment variables with the prefix PCP_ are used to parameterize the
348       file and directory names used by PCP.  On each installation,  the  file
349       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
350       $PCP_CONF variable may be used to specify an alternative  configuration
351       file, as described in pcp.conf(5).
352
353       For environment variables affecting PCP tools, see pmGetOptions(3).
354

SEE ALSO

356       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
357       pcp2influxdb(1), pcp2json(1),  pcp2spark(1),  pcp2xlsx(1),  pcp2xml(1),
358       pmcd(1),  pminfo(1), pmrep(1), pmGetOptions(3), pmSpecLocalPMDA(3), pm‐
359       LoadDerivedConfig(3),  pmParseUnitsStr(3),  pmRegisterDerived(3),  zbx‐
360       pcp(3), LOGARCHIVE(5), pcp.conf(5), PMNS(5) and pmrep.conf(5).
361
362
363
364Performance Co-Pilot                  PCP                        PCP2ZABBIX(1)
Impressum