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       syntax.  This page describes pcp2zabbix specific options and configura‐
27       tion file differences with pmrep.conf(5).  pmrep(1) also lists some us‐
28       age examples of which most are applicable with pcp2zabbix as well.
29
30       Only  the command line options listed on this page are supported, other
31       options available for 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       pcp2zabbix uses a configuration  file  with  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,  precision, precision_force, count_scale, count_scale_force,
46       space_scale, space_scale_force, time_scale, time_scale_force.  The rest
47       of the pmrep.conf options are recognized but ignored for compatibility.
48
49   pcp2zabbix specific options
50       zabbix_server (string)
51           Specify the destination Zabbix server hostname or IP address.  If a
52           host is monitored by a proxy, proxy hostname or IP  address  should
53           be  used  instead.   Corresponding  command line option is -g.  De‐
54           faults to localhost.
55
56       zabbix_port (integer)
57           Specify the port number of server trapper running  on  the  server.
58           Corresponding command line option is -p.  Defaults to 10051.
59
60       zabbix_host (string)
61           Specify  agent  hostname as registered in Zabbix frontend.  Host IP
62           address and DNS name will not work.  Corresponding command line op‐
63           tion is -X.  Defaults to the metrics source host.
64
65       zabbix_interval (string)
66           Indicates  the interval to send metrics to the Zabbix server.  This
67           can be longer than the reporting interval to minimize the  overhead
68           when communicating with the server (as each send creates a new con‐
69           nection).  Follows the time syntax described in PCPIntro(1).   Cor‐
70           responding  command  line  option is -E.  Defaults to the reporting
71           interval.  Zabbix tools send at most 250 metrics at  a  time.   Ig‐
72           nored when reading metrics from PCP archives, in which case metrics
73           will be sent roughly at 250 metric batches.
74
75       zabbix_prefix (string)
76           Specify the prefix for metrics sent to the Zabbix  server.   Corre‐
77           sponding command line option is -x.  Defaults to pcp..
78
79       zabbix_lld (boolean)
80           Specify  whether to enable Zabbix low-level discovery.  Correspond‐
81           ing command line option is -l.  Defaults to no.
82

OPTIONS

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

FILES

345       pcp2zabbix.conf
346            pcp2zabbix configuration file (see -c)
347
348       $PCP_SYSCONF_DIR/pmrep/*.conf
349            system provided default pmrep configuration files
350

PCP ENVIRONMENT

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

SEE ALSO

361       PCPIntro(1),  mkaf(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
362       pcp2influxdb(1), pcp2json(1),  pcp2spark(1),  pcp2xlsx(1),  pcp2xml(1),
363       pmcd(1),  pminfo(1), pmrep(1), pmGetOptions(3), pmLoadDerivedConfig(3),
364       pmParseUnitsStr(3),  pmRegisterDerived(3),   pmSpecLocalPMDA(3),   zbx‐
365       pcp(3), LOGARCHIVE(5), pcp.conf(5), pmrep.conf(5) and PMNS(5).
366
367
368
369Performance Co-Pilot                  PCP                        PCP2ZABBIX(1)
Impressum