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, e.g. to add the data to a redis-server(1)
       instance.  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
       redis-server(1) instance.

       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-server(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_ARCHIVE_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).