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