NAME

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

C SYNOPSIS

       #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

       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  asyn‐
       chronous  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 normal‐
       ly 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  pmDiscover‐
       SetConfiguration  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  pmDiscover‐
       CallBacks.

       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 head‐
       er.  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(1), a native grafana(1) data-source for PCP.

FILES

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

DIAGNOSTICS

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

SEE ALSO

       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).

Performance Co-Pilot                                   PCP                                    PMDISCOVERSETUP(3)