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
       infrastructure  (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
       key-value server.  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
       key-value server.

       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  a key-value server 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).