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