pmDiscoverSetEventLoop(3)

1PMDISCOVERSETUP(3)         Library Functions Manual         PMDISCOVERSETUP(3)
2
3
4

NAME

6       pmDiscoverSetup,  pmDiscoverSetSlots, pmDiscoverSetEventLoop, pmDiscov‐
7       erSetConfiguration,  pmDiscoverSetMetricRegistry,   pmDiscoverClose   -
8       asynchronous archive location and contents discovery services
9

C SYNOPSIS

11       #include <pcp/pmwebapi.h>
12
13       int pmDiscoverSetup(pmDiscoverModule *module, pmDiscoverCallBacks
14               *callbacks, void *arg);
15
16       int pmDiscoverSetSlots(pmDiscoverModule *module, void *slots);
17       int pmDiscoverSetEventLoop(pmDiscoverModule *module, void *uvloop);
18       int pmDiscoverSetConfiguration(pmDiscoverModule *module, struct dict
19               *config);
20       int pmDiscoverSetMetricRegistry(pmDiscoverModule *module, struct
21               mmv_registry *registry);
22
23       int pmDiscoverClose(pmDiscoverModule *module);
24
25       cc ... -lpcp_web
26

DESCRIPTION

28       The pmDiscoverSetup and related functions are an integral part  of  the
29       libpcp_web  API  library,  as used by and described in pmwebapi(3), pm‐
30       proxy(1), pmseries(1) and elsewhere.  These functions provide an  asyn‐
31       chronous  event driven mechanism to automatically discover PCP archives
32       created by pmlogger(1) and any other application capable of writing PCP
33       archives.   This  includes  pmrep(1)  and  other applications using the
34       LOGIMPORT(3) API for importing performance data  into  the  PCP  infra‐
35       structure and writing PCP archives.
36
37       The  pmDiscover  API  services dynamically discover, monitor and manage
38       directories of PCP archives as they are created, written to, compressed
39       and  eventually deleted.  The underlying archive life-cycle is normally
40       managed by the PCP log  management  infrustructure  (see  pmlogger_dai‐
41       ly(1)).   Discovered archives that are active (currently being written)
42       are "log-tailed" to extract near live/real-time performance data  which
43       is  then  passed  off  via registered callbacks for further processing,
44       e.g. to add the data to a redis-server(1) instance.  Archives that  are
45       compressed  or inactive are tracked/monitored but not log-tailed - this
46       is because compressed archives never grow and so log-tailing would nev‐
47       er  discover  any new data.  See the --load option in pmseries(1) for a
48       supported mechanism for ingesting previously  collected  (inctive)  PCP
49       archives, whether compressed or not, into a redis-server(1) instance.
50
51       The pmDiscover routines can be configured to automatically discover and
52       monitor PCP archives in one or more directories  as  specified  in  the
53       pmDiscoverModule,  which  is initially set up by calling pmDiscoverSet‐
54       Configuration to create a module of type pmDiscoverModule, as described
55       above.   The  resulting  module is then passed to pmDiscoverSetup along
56       with an initialized structure of callbacks of type pmDiscoverCallBacks.
57
58       Setting up a discovery module and callbacks would normally  declare  an
59       instance of pmDiscoverSettings, e.g.
60
61            #include <pcp/pmwebapi.h>
62
63            static pmDiscoverSettings someapp_discover = {
64                .callbacks.on_source        = pmSomeappDiscoverSource,
65                .callbacks.on_closed        = pmSomeappDiscoverClosed,
66                .callbacks.on_labels        = pmSomeappDiscoverLabels,
67                .callbacks.on_metric        = pmSomeappDiscoverMetric,
68                .callbacks.on_values        = pmSomeappDiscoverValues,
69                .callbacks.on_indom         = pmSomeappDiscoverInDom,
70                .callbacks.on_text          = pmSomeappDiscoverText,
71                .module.on_info             = someapp_logging_function,
72            };
73
74       And then initialize this with API calls similar to the following:
75
76            pmDiscoverSetEventLoop(&someapp_discover.module, myevents);
77            pmDiscoverSetConfiguration(&someapp_discover.module, myconfig);
78            pmDiscoverSetMetricRegistry(&someapp_discover.module, metric_registry);
79            pmDiscoverSetup(&someapp_discover.module, &someapp_discover.callbacks, &privatedata);
80
81       The  above code must then implement each of the declared callbacks etc.
82       to do whatever is required with the data passed  in  to  the  callback.
83       Prototypes  for  these callbacks can be found in the pmwebapi.h header.
84       The callbacks will be made asynchronously, as archives  are  discovered
85       or  deleted and as new data is written to active archive log volume and
86       metadata files.
87
88       In the case of pmproxy(1), callbacks are registered to capture  perfor‐
89       mance data, which is then sent to redis-server(1) as the database back-
90       end for fast scalable time-series queries by clients of the PMWEBAPI(3)
91       REST  API  services.   Such clients include the pmseries(1) application
92       and pmproxy(1), which is the back-end REST API server for  grafana-pcp,
93       a native grafana-server(1) data-source for PCP.
94

DIAGNOSTICS

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

FILES

100       The default archive directory is $PCP_ARCHIVE_DIR,  which  is  normally
101       /var/log/pcp/pmlogger.   The  API recursively descends all sub-directo‐
102       ries and also dynamically discovers any  new  directories  or  archives
103       found therein.
104

NAME

C SYNOPSIS

DESCRIPTION

DIAGNOSTICS

FILES

SEE ALSO