# pmdiscoversetup

## 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 func‐
           tions provide an asynchronous event driven mechanism to  automati‐
           cally  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 im‐
           porting  performance  data into the PCP infrastructure and writing
           PCP archives.
    
           The **pmDiscover** API services dynamically discover, monitor and man‐
           age 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  infra‐
           structure  (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 reg‐
           istered 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 discov‐
           er and monitor PCP archives in one or more directories  as  speci‐
           fied in the **pmDiscoverModule** , which is initially set up by calling
           **pmDiscoverSetConfiguration** to create a _module_ of type **pmDiscover‐**
           **Module** , as described above.  The resulting _module_ is  then  passed
           to  **pmDiscoverSetup** along  with an initialized structure of _call‐_
           _backs_ 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)  applica‐
           tion  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  nor‐
           mally  **/var/log/pcp/pmlogger**.   The  API  recursively descends all
           sub-directories and also dynamically discovers any new directories
           or archives found therein.
    


* * *