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       Archives that are compressed or inactive are tracked/monitored but  not
45       log-tailed.
46
47       The pmDiscover routines can be configured to automatically discover and
48       monitor PCP archives in one or more directories  as  specified  in  the
49       pmDiscoverModule,  which  is initially set up by calling pmDiscoverSet‐
50       Configuration to create a module of type pmDiscoverModule, as described
51       above.   The  resulting  module is then passed to pmDiscoverSetup along
52       with an initialized structure of callbacks of type pmDiscoverCallBacks.
53
54       Setting up a discovery module and callbacks would normally  declare  an
55       instance of pmDiscoverSettings, e.g.
56
57            #include <pcp/pmwebapi.h>
58
59            static pmDiscoverSettings someapp_discover = {
60                .callbacks.on_source        = pmSomeappDiscoverSource,
61                .callbacks.on_closed        = pmSomeappDiscoverClosed,
62                .callbacks.on_labels        = pmSomeappDiscoverLabels,
63                .callbacks.on_metric        = pmSomeappDiscoverMetric,
64                .callbacks.on_values        = pmSomeappDiscoverValues,
65                .callbacks.on_indom         = pmSomeappDiscoverInDom,
66                .callbacks.on_text          = pmSomeappDiscoverText,
67                .module.on_info             = someapp_logging_function,
68            };
69
70       And then initialize this with API calls similar to the following:
71
72            pmDiscoverSetEventLoop(&someapp_discover.module, myevents);
73            pmDiscoverSetConfiguration(&someapp_discover.module, myconfig);
74            pmDiscoverSetMetricRegistry(&someapp_discover.module, metric_registry);
75            pmDiscoverSetup(&someapp_discover.module, &someapp_discover.callbacks, &privatedata);
76
77       The  above code must then implement each of the declared callbacks etc.
78       to do whatever is required with the data passed  in  to  the  callback.
79       Prototypes  for  these callbacks can be found in the pmwebapi.h header.
80       The callbacks will be made asynchronously, as archives  are  discovered
81       or  deleted and as new data is written to active archive log volume and
82       metadata files.
83
84       In the case of pmproxy(1), callbacks are registered to capture  perfor‐
85       mance data, which is then sent to redis(1) as the database back-end for
86       fast scalable time-series queries by clients of  the  PMWEBAPI(3)  REST
87       API services.  Such clients include the pmseries(1) application and pm‐
88       proxy(1), which is the back-end REST API server for  grafana-pcp(1),  a
89       native grafana(1) data-source for PCP.
90

FILES

92       The  default  archive  directory  is  $PCP_LOG_DIR,  which  is normally
93       /var/log/pcp/pmlogger.  The API recursively descends  all  sub-directo‐
94       ries  and  also  dynamically  discovers any new directories or archives
95       found therein.
96

DIAGNOSTICS

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

SEE ALSO

102       pmerr(1),    pmlogger(1),    pmproxy(1),    pmseries(1),   PMWEBAPI(3),
103       mmv_stats_registry(3),   PMAPI(3),   pmErrStr(3),    pcp.conf(5)    and
104       pcp.env(5).
105
106
107
108Performance Co-Pilot                  PCP                   PMDISCOVERSETUP(3)
Impressum