pmdiscoversetup(3) — Linux manual page


PMDISCOVERSETUP(3)        Library Functions Manual        PMDISCOVERSETUP(3)

NAME         top

       pmDiscoverSetup, pmDiscoverSetSlots, pmDiscoverSetEventLoop, pmDisco‐
       verSetConfiguration, 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
       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 functions provide an
       asynchronous event driven mechanism to automatically 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 importing performance data into the
       PCP infrastructure and writing PCP archives.

       The pmDiscover API services dynamically discover, monitor and manage
       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 log management infrustructure (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 registered callbacks
       for further processing.  Archives that are compressed or inactive are
       tracked/monitored but not log-tailed.

       The pmDiscover routines can be configured to automatically discover
       and monitor PCP archives in one or more directories as specified in
       the pmDiscoverModule, which is initially set up by calling
       pmDiscoverSetConfiguration to create a module of type
       pmDiscoverModule, as described above.  The resulting module is then
       passed to pmDiscoverSetup along with an initialized structure of
       callbacks 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 log volume and metadata files.

       In the case of pmproxy(1), callbacks are registered to capture
       performance data, which is then sent to redis(1) as the database
       back-end for fast scalable time-series queries by clients of the
       PMWEBAPI(3) REST API services.  Such clients include the pmseries(1)
       application and pmproxy(1), which is the back-end REST API server for
       grafana-pcp, a native grafana-server(1) data-source for PCP.

FILES         top

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

DIAGNOSTICS         top

       Generally zero on success, or on error a negative return code, see

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.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2020-11-01.  (At that time, the date of the most recent commit that
       was found in the repository was 2020-10-30.)  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

Performance Co-Pilot                 PCP                  PMDISCOVERSETUP(3)