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).  Please refer  to  pmrep(1)
24       for  the metricspec description accepted on pcp2zabbix command line and
25       pmrep.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
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       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
64           option 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.
73           Ignored when reading metrics from PCP archives, in which case  met‐
74           rics 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
95            (refresh  metrics being sampled), ignore (do nothing - the default
96            behaviour) 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 argument
116            archive, 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 to use.  The default is  the  first  found
140            of:  ./pcp2zabbix.conf, $HOME/.pcp2zabbix.conf, $HOME/pcp/pcp2zab‐
141            bix.conf, and $PCP_SYSCONF_DIR/pcp2zabbix.conf.  For details,  see
142            the above section and pmrep.conf(5).
143
144       --container=container
145            Fetch  performance  metrics  from  the specified container, either
146            local 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            derived  metrics  configuration  file, otherwise it will be inter‐
159            preted as comma- or  semicolon-separated  derived  metric  expres‐
160            sions.   For  details  see  pmLoadDerivedConfig(3) and pmRegister‐
161            Derived(3).
162
163       -E interval, --zabbix-interval=interval
164            Specify the interval to send metrics  to  the  server.   See  zab‐
165            bix_interval description above for details.
166
167       -g server, --zabbix-server=server
168            Zabbix server to send the metrics to.
169
170       -G, --no-globals
171            Do not include global metrics in reporting (see pmrep.conf(5)).
172
173       -h host, --host=host
174            Fetch  performance  metrics from pmcd(1) on host, rather than from
175            the default localhost.
176
177       -H, --no-header
178            Do not print any headers.
179
180       -i instances, --instances=instances
181            Report only  the  listed  instances  from  current  instances  (if
182            present,  see  also  -j).   By  default all instances, present and
183            future, are reported.  This is a global option that  is  used  for
184            all  metrics  unless a metric-specific instance definition is pro‐
185            vided as part of a metricspec.  By default single-valued  ``flat''
186            metrics  without  multiple  instances are still reported as usual,
187            use -v to change this.  Please refer to pmrep(1) for more  details
188            on this option.
189
190       -I, --ignore-incompat
191            Ignore  incompatible  metrics.   By  default  incompatible metrics
192            (that is, their type is unsupported or they cannot  be  scaled  as
193            requested)  will  cause pcp2zabbix to terminate with an error mes‐
194            sage.  With this option  all  incompatible  metrics  are  silently
195            omitted  from  reporting.   This  may  be  especially  useful when
196            requesting non-leaf nodes of the PMNS tree for reporting.
197
198       -l, --zabbix-lld
199            Add low-level discovery (LLD) metrics.   This  allows  PCP  metric
200            instance   domains  to  be  sent  to  Zabbix,  so  that  prototype
201            items/triggers/graphs may be automatically constructed by  Zabbix.
202            For   each   PCP   metric   with   an  instance  domain,  the  key
203            pcp.discovery[pcp.met.ric]  is  sent  periodically.   This  symbol
204            should  be  added  to  a  discovery  rule,  and  will  define  the
205            {#PCP.MET.RIC} LLD macro.  This macro can inturn be used to define
206            prototype items/triggers/graphs.  The names are adjusted if -x was
207            given to override the pcp. prefix.
208
209       -j, --live-filter
210            Perform instance live filtering.  This allows capturing  all  fil‐
211            tered instances even if processes are restarted at some point (un‐
212            like without live filtering).  Performing live  filtering  over  a
213            huge  amount of instances will add some internal overhead so a bit
214            of user caution is advised.  See also -n.
215
216       -J rank, --rank=rank
217            Limit results to highest/lowest rank instances of set-valued  met‐
218            rics.  A positive integer will include highest valued instances in
219            reporting.  A negative integer  will  include  lowest  valued  in‐
220            stances  in  reporting.  A value of zero performs no ranking.  See
221            also -8.
222
223       -K spec, --spec-local=spec
224            When fetching metrics from a local context (see -L), the -K option
225            may  be used to control the DSO PMDAs that should be made accessi‐
226            ble.  The spec argument conforms to the syntax  described  in  pm‐
227            SpecLocalPMDA(3).  More than one -K option may be used.
228
229       -L, --local-PMDA
230            Use a local context to collect metrics from DSO PMDAs on the local
231            host without PMCD.  See also -K.
232
233       -n, --invert-filter
234            Perform ranking before live filtering.  By default  instance  live
235            filtering (when requested, see -j) happens before instance ranking
236            (when requested, see -J).  With this option the logic is  inverted
237            and ranking happens before live filtering.
238
239       -N predicate, --predicate=predicate
240            Specify  a comma-separated list of predicate filter reference met‐
241            rics.  By default ranking (see -J) happens for each  metric  indi‐
242            vidually.  With predicates, ranking is done only for the specified
243            predicate metrics.  When reporting, rest of  the  metrics  sharing
244            the  same  instance domain (see PCPIntro(1)) as the predicate will
245            include only the highest/lowest ranking instances  of  the  corre‐
246            sponding predicate.
247
248            So  for  example,  using  proc.memory.rss (resident memory size of
249            process) as the predicate metric together with proc.io.total_bytes
250            and  mem.util.used  as  metrics to be reported, only the processes
251            using most/least (as per -J) memory will be included when  report‐
252            ing  total  bytes  written by processes.  Since mem.util.used is a
253            single-valued metric (thus not sharing the same instance domain as
254            the process-related metrics), it will be reported as usual.
255
256       -O origin, --origin=origin
257            When  reporting archived metrics, start reporting at origin within
258            the time window (see -S and -T).  Refer to PCPIntro(1) for a  com‐
259            plete description of the syntax for origin.
260
261       -p port, --zabbix-port=port
262            Zabbix server port number.
263
264       -P precision, --precision=precision
265            Use  precision for numeric non-integer output values.  The default
266            is to use 3 decimal places (when applicable).   This  option  will
267            not override possible per-metric specifications.
268
269       -q scale, --count-scale=scale
270            Unit/scale  for  count  metrics,  possible  values include count x
271            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
272            10^7.   (These values are currently space-sensitive.)  This option
273            will not override possible per-metric  specifications.   See  also
274            pmParseUnitsStr(3).
275
276       -Q scale, --count-scale-force=scale
277            Like -q but this option will override per-metric specifications.
278
279       -r, --raw
280            Output  raw  metric  values, do not convert cumulative counters to
281            rates.  This option will override possible  per-metric  specifica‐
282            tions.
283
284       -R, --raw-prefer
285            Like  -r  but  this option will not override per-metric specifica‐
286            tions.
287
288       -s samples, --samples=samples
289            The argument samples defines the number of samples to be retrieved
290            and  reported.  If samples is 0 or -s is not specified, pcp2zabbix
291            will sample and report continuously (in real time mode)  or  until
292            the  end  of  the set of PCP archives (in archive mode).  See also
293            -T.
294
295       -S starttime, --start=starttime
296            When reporting archived metrics, the report will be restricted  to
297            those  records logged at or after starttime.  Refer to PCPIntro(1)
298            for a complete description of the syntax for starttime.
299
300       -t interval, --interval=interval
301            The default update interval may be set to something other than the
302            default  1  second.   The interval argument follows the syntax de‐
303            scribed in PCPIntro(1), and in the simplest form  may  be  an  un‐
304            signed  integer (the implied units in this case are seconds).  See
305            also the -T option.
306
307       -T endtime, --finish=endtime
308            When reporting archived metrics, the report will be restricted  to
309            those  records  logged before or at endtime.  Refer to PCPIntro(1)
310            for a complete description of the syntax for endtime.
311
312            When used to define the runtime before pcp2zabbix will exit, if no
313            samples  is given (see -s) then the number of reported samples de‐
314            pends on interval (see -t).  If samples  is  given  then  interval
315            will be adjusted to allow reporting of samples during runtime.  In
316            case all of -T, -s, and -t are given, endtime determines the actu‐
317            al time pcp2zabbix will run.
318
319       -v, --omit-flat
320            Omit  single-valued ``flat'' metrics from reporting, only consider
321            set-valued metrics (i.e., metrics with multiple  values)  for  re‐
322            porting.  See -i and -I.
323
324       -V, --version
325            Display version number and exit.
326
327       -x prefix, --zabbix-prefix=prefix
328            Metrics prefix for measurements sent to the server.
329
330       -X hostname, --zabbix-host=hostname
331            Specify the agent hostname as registered in Zabbix frontend.
332
333       -y scale, --time-scale=scale
334            Unit/scale  for time metrics, possible values include nanosec, ns,
335            microsec, us, millisec, ms, and so forth up to hour, hr.  This op‐
336            tion  will  not  override possible per-metric specifications.  See
337            also pmParseUnitsStr(3).
338
339       -Y scale, --time-scale-force=scale
340            Like -y but this option will override per-metric specifications.
341
342       -?, --help
343            Display usage message and exit.
344

FILES

346       pcp2zabbix.conf
347              pcp2zabbix configuration file (see -c)
348

PCP ENVIRONMENT

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

SEE ALSO

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