PMDISCOVERSETUP(3)

okay bestie, we're reading PMDISCOVERSETUP(3) from the Library Functions Manual today and it's literally the girlboss of asynchronous archive discovery 💅✨

---

✨ 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 💖

So pmDiscoverSetup and her little friend group are like, a whole integral part of the libpcp_web API library — the one that gets used by and described in pmwebapi(3), pmproxy(1), pmseries(1) and literally everywhere else. What they do? They give you an asynchronous, event driven mechanism to automatically discover PCP archives created by pmlogger(1) and by any other application that can write PCP archives. Yes, that includes pmrep(1) and any other app using the LOGIMPORT(3) API to import performance data into the PCP infrastructure and write PCP archives. iconic behavior tbh 🌈

The pmDiscover API services dynamically discover, monitor and manage directories of PCP archives as they're created, written to, compressed, and eventually deleted. The underlying archive life-cycle is normally managed by the PCP archive management infrastructure (peep pmlogger_daily(1) for that). Discovered archives that are active (like, currently being written) get "log-tailed" to extract near live/real-time performance data, which then gets passed off via registered callbacks for further processing — e.g. adding the data to a key-value server. Archives that are compressed or inactive are tracked/monitored but not log-tailed — and no, that's not a vibe, that's a fact: compressed archives never grow, 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. iykyk 🫶)

The pmDiscover routines can be configured to automatically discover 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 then gets passed to pmDiscoverSetup along with an initialized structure of callbacks of type pmDiscoverCallBacks. it's giving plumbing but make it cute 💅

Setting up a discovery module and callbacks would normally declare an instance of pmDiscoverSettings, like:

#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 you 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. main character energy, honestly 👑

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) application and pmproxy(1), which is the back-end REST API server for grafana-pcp, a native grafana-server(1) data-source for PCP. slay 🎀

---

🩺 DIAGNOSTICS 🩺

Generally zero on success, or on error a negative return code — go see pmerr(1). no cap, if it's negative, something's up 😭

---

📁 FILES 📁

The default archive directory is $PCP_ARCHIVE_DIR, which is normally /var/log/pcp/pmlogger. The API recursively descends all sub-directories and also dynamically discovers any new directories or archives found therein. she's nosy and we love that for her 🙈

---

👀 SEE ALSO 👀

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

---

that's the whole page, bestie — brought to you by Performance Co-Pilot (that's the source, that's the version, it's just PCP 💜), same as always. go discover some archives fr fr ✨🦋🌸