pmdiscoversetup(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | DIAGNOSTICS | FILES | SEE ALSO | COLOPHON

PMDISCOVERSETUP(3)      Library Functions Manual      PMDISCOVERSETUP(3)

NAME         top

       pmDiscoverSetup, pmDiscoverSetSlots, pmDiscoverSetEventLoop,
       pmDiscoverSetConfiguration, pmDiscoverSetMetricRegistry,
       pmDiscoverClose - asynchronous archive location and contents
       discovery services

C SYNOPSIS         top

       #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         top

       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
       importing performance data into the PCP infrastructure and  writ‐
       ing 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  in‐
       frastructure  (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  be‐
       cause  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  dis‐
       cover  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 struc‐
       ture of callbacks of type pmDiscoverCallBacks.

       Setting up a discovery module and callbacks  would  normally  de‐
       clare 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 in‐
       clude 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         top

       Generally zero on success, or on error a  negative  return  code,
       see pmerr(1).

FILES         top

       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 directo‐
       ries or archives found therein.

SEE ALSO         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug  report  for  this  manual  page,  send  it  to
       [email protected].    This  page  was  obtained  from  the  project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩   on  2024-06-14.
       (At that time, the date of the most recent commit that was  found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems  in  this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or  you  have
       corrections  or  improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a  mail  to
       [email protected]

Performance Co-Pilot               PCP                PMDISCOVERSETUP(3)

Pages that refer to this page: pmseriesquery(3)