PCP2ZABBIX(1)

📦
version 7.2.2 · 6 versions
, in arch rolling, fedora 43, fedora 44, ubuntu stonking

PCP2ZABBIX(1) 💖

okay bestie, welcome to the General Commands Manual entry for pcp2zabbix — it's a whole vibe and honestly? iconic. let's get into it 🫶

✨ NAME ✨

pcp2zabbix — the pcp-to-zabbix metrics exporter 💅

🌸 SYNOPSIS 🌸

pcp2zabbix [-5CGHIjlLnrRvV?]  [-4 action] [-8|-9 limit] [-a archive] [-A
align] [--archive-folio folio] [-b|-B space-scale] [-c config]
[--container container] [-D debug] [--daemonize] [-e derived] [-E send-
interval] [-g server] [-h host] [-i instances] [-J rank] [-K spec] [-N
predicate] [-O origin] [-p port] [-P|-0 precision] [-q|-Q count-scale]
[-s samples] [-S starttime] [-t interval] [-T endtime] [-x prefix] [-X
hostname] [-y|-Y time-scale] metricspec [...]

🦋 DESCRIPTION 🦋

pcp2zabbix is a customizable performance metrics exporter tool that yeets metrics from PCP straight to Zabbix. literally any available performance metric — live or archived, system and/or application — can be picked for exporting, either via command line arguments or via a config file. no cap. 🔥

pcp2zabbix is a close relative of pmrep(1) — like, sibling energy fr fr. go read pmrep(1) for the metricspec description that pcp2zabbix accepts on the command line. and for the pcp2zabbix.conf config file syntax, see pmrep.conf(5). this page right here describes the pcp2zabbix-specific options and how its config file differs from pmrep.conf(5). pmrep(1) also lists some usage examples, and most of those are applicable with pcp2zabbix too. 🎀

lowkey important: only the command line options listed on this page are supported. other options that exist for pmrep(1) are not supported. periodt.

Options via environment values (see pmGetOptions(3)) override the corresponding built-in default values (if any). Config file options override the corresponding environment variables (if any). Command line options override the corresponding config file options (if any). it's a whole hierarchy, bestie — CLI stays winning 👑

💜 CONFIGURATION FILE 💜

pcp2zabbix uses a config file with syntax described in pmrep.conf(5). these options are common with pmrep.conf:

  • version
  • source
  • speclocal
  • derived
  • header
  • globals
  • samples
  • interval
  • type
  • type_prefer
  • ignore_incompat
  • names_change
  • instances
  • live_filter
  • rank
  • limit_filter
  • limit_filter_force
  • invert_filter
  • predicate
  • omit_flat
  • precision
  • precision_force
  • count_scale
  • count_scale_force
  • space_scale
  • space_scale_force
  • time_scale
  • time_scale_force

The rest of the pmrep.conf options are recognized but ignored for compatibility. they're just there, chilling. 🙈

🌈 pcp2zabbix specific options 🌈

  • zabbix_server (string) — Specify the destination Zabbix server hostname or IP address. If a host is monitored by a proxy, use the proxy hostname or IP address instead. The corresponding command line option is -g. Defaults to localhost.
  • zabbix_port (integer) — Specify the port number of the server trapper running on the server. The corresponding command line option is -p. Defaults to 10051.
  • zabbix_host (string) — Specify the agent hostname as registered in the Zabbix frontend. Host IP address and DNS name will not work, so don't even try it. The corresponding command line option is -X. Defaults to the metrics source host.
  • zabbix_interval (string) — Indicates the interval to send metrics to the Zabbix server. This can be longer than the reporting interval to minimize the overhead when communicating with the server (since each send creates a new connection, and we're not about that wasteful life). Follows the time syntax described in PCPIntro(1). The corresponding command line option is -E. Defaults to the reporting interval. Zabbix tools send at most 250 metrics at a time. Ignored when reading metrics from PCP archives, in which case metrics will be sent roughly at 250 metric batches.
  • zabbix_prefix (string) — Specify the prefix for metrics sent to the Zabbix server. The corresponding command line option is -x. Defaults to pcp..
  • zabbix_lld (boolean) — Specify whether to enable Zabbix low-level discovery. The corresponding command line option is -l. Defaults to no.

👑 OPTIONS 👑

The available command line options are:

  • -0 precision, --precision-force=precision — Like -P but this option will override per-metric specifications. it's giving "no, I said what I said" 💅
  • -4 action, --names-change=action — Specify which action to take on receiving a metric names change event during sampling. These events occur when a PMDA discovers new metrics sometime after starting up, and informs running client tools like pcp2zabbix. Valid values for action are update (refresh metrics being sampled), ignore (do nothing — this is the default behaviour) and abort (exit the program if such an event occurs). pick your fighter 😤
  • -5, --ignore-unknown — Silently ignore any metric name that cannot be resolved. At least one metric must be found for the tool to start. (so you can't just ignore your way into nothing, bestie.)
  • -8 limit, --limit-filter=limit — Limit results to instances with values above/below limit. A positive integer will include instances with values at or above the limit in reporting. A negative integer will include instances with values at or below the limit in reporting. A value of zero performs no limit filtering. This option will not override possible per-metric specifications. See also -J and -N.
  • -9 limit, --limit-filter-force=limit — Like -8 but this option will override per-metric specifications. assertive. we love to see it.
  • -a archive, --archive=archive — Performance metric values are retrieved from the set of Performance Co-Pilot (PCP) archive files identified by the archive argument, which is a comma-separated list of names, each of which may be the base name of an archive or the name of a directory containing one or more archives. 🗂️
  • -A align, --align=align — Force the initial sample to be aligned on the boundary of a natural time unit align. Refer to PCPIntro(1) for a complete description of the syntax for align.
  • --archive-folio=folio — Read metric source archives from the PCP archive folio created by tools like pmchart(1) or, less often, manually with mkaf(1).
  • -b scale, --space-scale=scale — Unit/scale for space (byte) metrics; possible values include bytes, Kbytes, KB, Mbytes, MB, and so forth. This option will not override possible per-metric specifications. See also pmParseUnitsStr(3).
  • -B scale, --space-scale-force=scale — Like -b but this option will override per-metric specifications.
  • -c config, --config=config — Specify the config file or directory to use. In case config is a directory, all files in it ending .conf will be included. The default is the first found of: ./pcp2zabbix.conf, $HOME/.pcp2zabbix.conf, $HOME/pcp/pcp2zabbix.conf, and $PCP_SYSCONF_DIR/pcp2zabbix.conf. For details, see the above section and pmrep.conf(5).
  • --container=container — Fetch performance metrics from the specified container, either local or remote (see -h).
  • -C, --check — Exit before reporting any values, but after parsing the configuration and metrics and printing possible headers. it's the "just checking in" of options 🫶
  • --daemonize — Daemonize on startup.
  • -e derived, --derived=derived — Specify derived performance metrics. If derived starts with a slash (/) or with a dot (.) it will be interpreted as a PCP derived metrics configuration file, otherwise it will be interpreted as comma- or semicolon-separated derived metric expressions. For a complete description of derived metrics and PCP derived metrics configuration files see pmLoadDerivedConfig(3) and pmRegisterDerived(3). Alternatively, using pmrep.conf(5) configuration syntax allows defining derived metrics as part of metricsets.

In case of issues with derived metrics, review the aforementioned manual pages in detail and ensure all the required metrics are available, especially when using archives. Use -Dderive to see additional debug information about parsing derived metrics. 🔍

  • -E interval, --zabbix-interval=interval — Specify the interval to send metrics to the server. See the zabbix_interval description above for details.
  • -g server, --zabbix-server=server — Destination Zabbix server.
  • -G, --no-globals — Do not include global metrics in reporting (see pmrep.conf(5)).
  • -h host, --host=host — Fetch performance metrics from pmcd(1) on host, rather than from the default localhost.
  • -H, --no-header — Do not print any headers. minimalism, but make it metrics.
  • -i instances, --instances=instances — Retrieve and report only the specified metric instances. By default all instances, present and future, are reported.

Refer to pmrep(1) for a complete description of this option.

  • -I, --ignore-incompat — Ignore incompatible metrics. By default incompatible metrics (that is, their type is unsupported or they cannot be scaled as requested) will cause pcp2zabbix to terminate with an error message. With this option all incompatible metrics are silently omitted from reporting. This may be especially useful when requesting non-leaf nodes of the PMNS tree for reporting. 🍃
  • -l, --zabbix-lld — Add low-level discovery (LLD) metrics. This allows PCP metric instance domains to be sent to Zabbix, so that prototype items/triggers/graphs may be automatically constructed by Zabbix. For each PCP metric with an instance domain, the key pcp.discovery[pcp.met.ric] is sent periodically. This symbol should be added to a discovery rule, and will define the {#PCP.MET.RIC} LLD macro. This macro can in turn be used to define prototype items/triggers/graphs. The names are adjusted if -x was given to override the pcp. prefix. ✨
  • -j, --live-filter — Perform instance live filtering. This allows capturing all named instances even if processes are restarted at some point (unlike without live filtering). Performing live filtering over a huge number of instances will add some internal overhead so a bit of user caution is advised. See also -n.
  • -J rank, --rank=rank — Limit results to highest/lowest ranked instances of set-valued metrics. A positive integer will include highest valued instances in reporting. A negative integer will include lowest valued instances in reporting. A value of zero performs no ranking. Ranking does not imply sorting, see -6. See also -8.
  • -K spec, --spec-local=spec — When fetching metrics from a local context (see -L), the -K option may be used to control the DSO PMDAs that should be made accessible. The spec argument conforms to the syntax described in pmSpecLocalPMDA(3). More than one -K option may be used.
  • -L, --local-PMDA — Use a local context to collect metrics from DSO PMDAs on the local host without PMCD. See also -K.
  • -n, --invert-filter — flips the order of the vibe check 💅. By default, instance live filtering (when you ask for it, see -j) happens before instance ranking (when you ask for it, see -J). Pass this and the logic gets inverted: ranking goes first, then live filtering. Chaos? No, just different.
  • -N predicate, --predicate=predicate — hand over a comma-separated list of predicate filter reference metrics, bestie. Normally ranking (see -J) happens for each metric individually. With predicates, ranking happens only for the predicate metrics you named. And when reporting? The rest of the metrics sharing the same instance domain (see PCPIntro(1)) as the predicate will include only the highest/lowest ranking instances of that corresponding predicate. Ranking does not imply sorting, btw — see -6.

So, for example: use proc.memory.rss (resident memory size of process) as the predicate metric, together with proc.io.total_bytes and mem.util.used as the metrics to be reported. Result? Only the processes using most/least (as per -J) memory get included when reporting total bytes written by processes. And since mem.util.used is a single-valued metric (so it does not share the same instance domain as the process related metrics), it just gets reported as usual. Periodt. ✨

  • -O origin, --origin=origin — when you're reporting archived metrics, start the report at origin within the time window (see -S and -T). For the full glow-up on the syntax for origin, go read PCPIntro(1).
  • -p port, --zabbix-port=port — Zabbix server port. That's it, that's the whole thing. 🔌
  • -P precision, --precision=precision — use precision for numeric non-integer output values. Default is 3 decimal places (when applicable). Heads up though: this option will not override possible per-metric specifications. She has boundaries. 💅
  • -q scale, --count-scale=scale — unit/scale for count metrics. Possible values include count x 10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to 10^7. (These values are currently space-sensitive — yes, space-sensitive, be careful 😭.) This option will not override possible per-metric specifications. See also pmParseUnitsStr(3).
  • -Q scale, --count-scale-force=scale — like -q, but this one will override per-metric specifications. Bossy, and honestly? Iconic.
  • -r, --raw — output raw metric values, do not convert cumulative counters to rates. This option will override possible per-metric specifications. No conversion, no filter, just the truth. 🫶
  • -R, --raw-prefer — like -r, but this one will not override per-metric specifications. Softer approach, same raw energy.
  • -s samples, --samples=samples — samples is the number of samples to be retrieved and reported. If samples is 0, or if -s isn't specified at all, pcp2zabbix will sample and report continuously (in real time mode) or until the end of the set of PCP archives (in archive mode). See also -T. Forever girlie behavior ♾️.
  • -S starttime, --start=starttime — when reporting archived metrics, the report gets restricted to only those records logged at or after starttime. For the complete description of the syntax for starttime, refer to PCPIntro(1).
  • -t interval, --interval=interval — set the reporting interval to something other than the default 1 second. The interval argument follows the syntax described in PCPIntro(1), and in its simplest form it can just be an unsigned integer (the implied units in that case are seconds). See also the -T option. ⏰
  • -T endtime, --finish=endtime — when reporting archived metrics, the report gets restricted to those records logged before or at endtime. Refer to PCPIntro(1) for the complete description of the syntax for endtime.

When used to define the runtime before pcp2zabbix will exit: if no samples is given (see -s), then the number of reported samples depends on interval (see -t). If samples is given, then interval will be adjusted to allow reporting of samples during runtime. And in the case where all of -T, -s, and -t are given, endtime determines the actual time pcp2zabbix will run. It's giving final boss energy 👑

  • -v, --omit-flat — report only set-valued metrics with instances (e.g. disk.dev.read) and omit single-valued "flat" metrics without instances (e.g. kernel.all.sysfork). See -i and -I. Flat metrics, you are being left on read 🙈
  • -V, --version — display version number and exit. Quick lil flex, then she's out.
  • -x prefix, --zabbix-prefix=prefix — metrics prefix for measurements sent to the server. 🎀
  • -X hostname, --zabbix-host=hostname — agent hostname as registered in the Zabbix frontend.
  • -y scale, --time-scale=scale — unit/scale for time metrics. Possible values include nanosec, ns, microsec, us, millisec, ms, and so forth up to hour, hr. This option will not override possible per-metric specifications. See also pmParseUnitsStr(3).
  • -Y scale, --time-scale-force=scale — like -y, but this option will override per-metric specifications. Forceful. We love a decisive queen 💅
  • -?, --help — display usage message and exit. When you're lost, just ask bestie 🫶

📁 FILES 📁

  • pcp2zabbix.conf — the pcp2zabbix configuration file (see -c).
  • $PCP_SYSCONF_DIR/pmrep/*.conf — system provided default pmrep configuration files.

🌍 PCP ENVIRONMENT 🌍

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

Of particular note: PCP_DISCRETE_ONCE can be set to ensure that discrete metric values are reported only once, unless they change at some point. One and done, unless she switches up ✨

🐛 DEBUGGING OPTIONS 🐛

The -D or --debug option enables the output of additional diagnostics on stderr to help triage problems, although ngl the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning.

Real talk: this section is for the devs. If you're an end-user peeking in here, you're valid, but the vibes may be cryptic 💀

👀 SEE ALSO 👀

PCPIntro(1), mkaf(1), pcp(1), pcp2elasticsearch(1), pcp2graphite(1), pcp2influxdb(1), pcp2json(1), pcp2spark(1), pcp2xlsx(1), pcp2xml(1), pmcd(1), pminfo(1), pmrep(1), pmGetOptions(3), pmLoadDerivedConfig(3), pmParseUnitsStr(3), pmRegisterDerived(3), pmSpecLocalPMDA(3), zbxpcp(3), LOGARCHIVE(5), pcp.conf(5), pmrep.conf(5) and PMNS(5).

And that's the whole page, bestie 💖 This manual page is from Performance Co-Pilot, shipped as part of PCP, and it lives under the name PCP2ZABBIX(1) — same page, same date stamp on the bottom as always. Go forth, rank your instances, and slay 🦋👑

📦 where this page comes from