1PMDISCOVERSETUP(3) Library Functions Manual PMDISCOVERSETUP(3)
2
6 pmDiscoverSetup, pmDiscoverSetSlots, pmDiscoverSetEventLoop, pmDiscov‐
7 erSetConfiguration, pmDiscoverSetMetricRegistry, pmDiscoverClose -
8 asynchronous archive location and contents discovery services
9
11 #include <pcp/pmwebapi.h>
12 int pmDiscoverSetup(pmDiscoverModule *module, pmDiscoverCallBacks
14 *callbacks, void *arg);
15 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 int pmDiscoverClose(pmDiscoverModule *module);
24 cc ... -lpcp_web
26
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 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 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 Setting up a discovery module and callbacks would normally declare an
55 instance of pmDiscoverSettings, e.g.
56 #include <pcp/pmwebapi.h>
58 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 And then initialize this with API calls similar to the following:
71 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 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 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, a na‐
89 tive grafana-server(1) data-source for PCP.
90
92 Generally zero on success, or on error a negative return code, see
93 pmerr(1).
94
96 The default archive directory is $PCP_LOG_DIR, which is normally
97 /var/log/pcp/pmlogger. The API recursively descends all sub-directo‐
98 ries and also dynamically discovers any new directories or archives
99 found therein.
100
102 grafana-server(1), pmerr(1), pmlogger(1), pmproxy(1), pmseries(1),
103 PMWEBAPI(3), mmv_stats_registry(3), PMAPI(3), pmErrStr(3), pcp.conf(5)
104 and pcp.env(5).
105Performance Co-Pilot PCP PMDISCOVERSETUP(3)