---

pmdiscoversetup(3) — Linux manual page

PMDISCOVERSETUP(3) Library Functions Manual PMDISCOVERSETUP(3)

NAME top

 pmDiscoverSetup, pmDiscoverSetSlots, pmDiscoverSetEventLoop,
 pmDiscoverSetConfiguration, pmDiscoverSetMetricRegistry,
 pmDiscoverClose - asynchronous archive location and contents
 discovery services

C SYNOPSIS top

 #include <pcp/pmwebapi.h>
 int pmDiscoverSetup(pmDiscoverModule *module,
 pmDiscoverCallBacks *callbacks, void *arg);
 int pmDiscoverSetSlots(pmDiscoverModule *module, void *slots);
 int pmDiscoverSetEventLoop(pmDiscoverModule *module, void
 *uvloop);
 int pmDiscoverSetConfiguration(pmDiscoverModule *module,
 struct dict *config);
 int pmDiscoverSetMetricRegistry(pmDiscoverModule *module,
 struct mmv_registry *registry);
 int pmDiscoverClose(pmDiscoverModule *module);
 cc ... -lpcp_web

DESCRIPTION top

 The pmDiscoverSetup and related functions are an integral part of
 the libpcp_web API library, as used by and described in
 pmwebapi(3), pmproxy(1), pmseries(1) and elsewhere. These func‐
 tions provide an asynchronous event driven mechanism to automati‐
 cally discover PCP archives created by pmlogger(1) and any other
 application capable of writing PCP archives. This includes
 pmrep(1) and other applications using the LOGIMPORT(3) API for im‐
 porting performance data into the PCP infrastructure and writing
 PCP archives.
 The pmDiscover API services dynamically discover, monitor and man‐
 age directories of PCP archives as they are created, written to,
 compressed and eventually deleted. The underlying archive life-
 cycle is normally managed by the PCP archive management infra‐
 structure (see pmlogger_daily(1)). Discovered archives that are
 active (currently being written) are "log-tailed" to extract near
 live/real-time performance data which is then passed off via reg‐
 istered callbacks for further processing, e.g. to add the data to
 a key-value server. Archives that are compressed or inactive are
 tracked/monitored but not log-tailed - this is because compressed
 archives never grow and so log-tailing would never discover any
 new data. See the --load option in pmseries(1) for a supported
 mechanism for ingesting previously collected (inctive) PCP
 archives, whether compressed or not, into a key-value server.
 The pmDiscover routines can be configured to automatically discov‐
 er and monitor PCP archives in one or more directories as speci‐
 fied in the pmDiscoverModule, which is initially set up by calling
 pmDiscoverSetConfiguration to create a module of type pmDiscover‐
 Module, as described above. The resulting module is then passed
 to pmDiscoverSetup along with an initialized structure of call‐
 backs of type pmDiscoverCallBacks.
 Setting up a discovery module and callbacks would normally declare
 an instance of pmDiscoverSettings, e.g.
 #include <pcp/pmwebapi.h>
 static pmDiscoverSettings someapp_discover = {
 .callbacks.on_source = pmSomeappDiscoverSource,
 .callbacks.on_closed = pmSomeappDiscoverClosed,
 .callbacks.on_labels = pmSomeappDiscoverLabels,
 .callbacks.on_metric = pmSomeappDiscoverMetric,
 .callbacks.on_values = pmSomeappDiscoverValues,
 .callbacks.on_indom = pmSomeappDiscoverInDom,
 .callbacks.on_text = pmSomeappDiscoverText,
 .module.on_info = someapp_logging_function,
 };
 And then initialize this with API calls similar to the following:
 pmDiscoverSetEventLoop(&someapp_discover.module, myevents);
 pmDiscoverSetConfiguration(&someapp_discover.module, myconfig);
 pmDiscoverSetMetricRegistry(&someapp_discover.module, metric_registry);
 pmDiscoverSetup(&someapp_discover.module, &someapp_discover.callbacks, &privatedata);
 The above code must then implement each of the declared callbacks
 etc. to do whatever is required with the data passed in to the
 callback. Prototypes for these callbacks can be found in the
 pmwebapi.h header. The callbacks will be made asynchronously, as
 archives are discovered or deleted and as new data is written to
 active archive volume and metadata files.
 In the case of pmproxy(1), callbacks are registered to capture
 performance data, which is then sent to a key-value server for
 fast scalable time-series queries by clients of the PMWEBAPI(3)
 REST API services. Such clients include the pmseries(1) applica‐
 tion and pmproxy(1), which is the back-end REST API server for
 grafana-pcp, a native grafana-server(1) data-source for PCP.

DIAGNOSTICS top

 Generally zero on success, or on error a negative return code, see
 pmerr(1).

FILES top

 The default archive directory is $PCP_ARCHIVE_DIR, which is nor‐
 mally /var/log/pcp/pmlogger. The API recursively descends all
 sub-directories and also dynamically discovers any new directories
 or archives found therein.

SEE ALSO top

 grafana-server(1), pmerr(1), pmlogger(1), pmproxy(1), pmseries(1),
 PMWEBAPI(3), mmv_stats_registry(3), PMAPI(3), pmErrStr(3),
 pcp.conf(5) and pcp.env(5).

COLOPHON top

 This page is part of the PCP (Performance Co-Pilot) project. In‐
 formation about the project can be found at ⟨http://www.pcp.io/⟩.
 If you have a bug report for this manual page, send it to
 pcp@groups.io. This page was obtained from the project's upstream
 Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
 2025年08月11日. (At that time, the date of the most recent commit
 that was found in the repository was 2025年08月11日.) If you discover
 any rendering problems in this HTML version of the page, or you
 believe there is a better or more up-to-date source for the page,
 or you have corrections or improvements to the information in this
 COLOPHON (which is not part of the original manual page), send a
 mail to man-pages@man7.org
Performance Co-Pilot PCP PMDISCOVERSETUP(3)

---

Pages that refer to this page: pmseriesquery(3)

---

---

---