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  asyn‐
       chronous  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 normal‐
       ly 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 da‐
       ta  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 pmDiscover‐
       SetConfiguration 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 pmDiscover‐
       CallBacks.

       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  head‐
       er.   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 re‐
       cursively 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).

Performance Co-Pilot                                   PCP                                    PMDISCOVERSETUP(3)