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

DIAGNOSTICS

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

FILES

       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.

SEE ALSO

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