PMSERIESSETUP(3)

💖 PMSERIESSETUP(3) — Library Functions Manual 💖

okay bestie, so this is a page from the Library Functions Manual, and it's giving main character energy for the whole time series subsystem. sit down, grab a boba, we're doing this. 🧋

---

✨ NAME ✨

pmSeriesSetup, pmSeriesSetSlots, pmSeriesSetEventLoop, pmSeriesSetConfiguration, pmSeriesSetMetricRegistry, pmSeriesClose — fast, scalable time series services 🦋

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmwebapi.h>

int pmSeriesSetup(pmSeriesModule *module, pmSeriesCallBacks *callbacks,
                  void *arg);

int pmSeriesSetSlots(pmSeriesModule *module, void *slots);
int pmSeriesSetEventLoop(pmSeriesModule *module, void *uvloop);
int pmSeriesSetConfiguration(pmSeriesModule *module,
                             struct dict *config);
int pmSeriesSetMetricRegistry(pmSeriesModule *module,
                              struct mmv_registry *registry);

int pmSeriesClose(pmSeriesModule *module);

cc ... -lpcp_web

---

👑 DESCRIPTION 👑

so pmSeriesSetup and its lil friend group of API functions are here to prep your application for accessing the fast, scalable time series querying functionality of the Performance Co-Pilot (PCP). iconic behaviour, honestly.

this whole thing is served through asynchronous APIs, which function in an event-driven fashion — no blocking, no waiting around, we're busy girls 💅. the interfaces described right here prepare a given time series module, and that module is what associates callback routines with certain asynchronous events that happen while servicing time series requests.

as a general pattern (iykyk), every interface in these APIs that needs to invoke callbacks provided by the calling program will take an opaque (void * pointer) parameter, arg. that pointer gets passed through unchanged, and it's typically used to access a data structure that maintains state within the calling program. she's a courier, she doesn't peek at the mail. 📬

where async setup is required by pmSeriesSetup, its completion will be indicated through the on_setup callback — which is part of the pmSeriesModule structure you passed in. that same structure also handles custom diagnostics, via the on_info callback. these are self-explanatory fr fr, so peek at <pcp/pmwebapi.h> for the exact calling conventions. 🔍

the callbacks registered by pmSeriesSetup to handle events are as follows — buckle up, it's a whole roster:

• pmSeriesMatchCallBack on_match — when a time series query discovers time series identifiers that match the query, the on_match callback gets called once for every series identifier (SID). the SID is a unique 40-byte ASCII representation of a SHA hash. yes, forty. not thirty-nine, not forty-one. 💀
• pmSeriesDescCallBack on_desc — metric descriptor requests coming from pmSeriesDescs(1) will invoke this callback once for each series identifier.
• pmSeriesInstCallBack on_inst — the instance identification callback 💫 internal (numeric) and external (string) instance identifiers, plus time series and source (host) SHA1 identifiers. called once for each instance. the associated series identifier is also handed to the callback.
• pmSeriesLabelCallBack on_labelmap — provides metric labels (name and value mappings) for each series identifier passed to pmSeriesLabels(1).
• pmSeriesStringCallBack on_instance — provides an instance name for a call to pmSeriesInstances(1) — the callback is called once for each instance name. the associated series identifier is also provided to the callback. 🎀
• pmSeriesStringCallBack on_context — provides a context name for a call to pmSeriesSources(1) — the callback is called once for each source (hostname or archive). the associated source identifier is also provided to the callback. 🌈
• pmSeriesStringCallBack on_metric — provides a metric name for a call to pmSeriesMetrics(1) — the callback is called once for each metric name. the associated series identifier is also provided to the callback. ⭐
• pmSeriesStringCallBack on_label — provides a label name for a call to pmSeriesLabels(1) — the callback is called once for each label name. the associated series identifier is also provided to the callback. 🍓
• pmSeriesValueCallBack on_value — calls to the pmSeriesQuery interface that provide a time window may result in values being found for matching time series. the on_value callback will be invoked once for each time series value, also providing the sample timestamp (in both string and binary form, as a time in nanoseconds since the epoch). the associated series identifier is also provided to the callback. 🔥
• pmSeriesDoneCallBack on_done — on completion of all asynchronous interfaces that return success (zero return code), this callback will be called. it provides a status code indicating overall success (zero) or failure (negative PMAPI code) of the operation. the finale, the moment we've all been waiting for. 🫶

the helper functions — pmSeriesSetSlots (key-value server), pmSeriesSetEventLoop (libuv), pmSeriesSetConfiguration (configuration file) and pmSeriesSetMetricRegistry (MMV instrumentation) — are the interfaces that give you a mechanism for passing in state for each of the associated subsystems. one lil state drop per subsystem, no cap. 🧚

finally, a call to pmSeriesClose is what ends the services available from a series module that was previously established through pmSeriesSetup. closing time, you don't gotta go home but you can't stay here. 💜

within PCP, the pmproxy(1) and pmseries(1) utilities are the primary users of these interfaces, providing REST API and command line time series query services respectively. they're the ones actually eating at this table. 👑

---

😭 DIAGNOSTICS 😭

where these functions return a status code, it's always zero on success. on failure you get a negative PMAPI error code back. so like... check your return values, bestie. every single time. no skipping. 🙈

---

💅 SEE ALSO 💅

pmproxy(1), pmlogger(1), pmseries(1), mmv_stats_registry(3), pmSeriesDescs(3), pmSeriesQuery(3), PMAPI(3) and PMWEBAPI(3).

---

go read them. all of them. I'm not kidding, the cross-references are the lore. 📚

---

and that's the page!! 🎉 brought to you by Performance Co-Pilot / PCP — this manual page is literally titled PMSERIESSETUP(3), and it slayed. mwah, bye bestie 💖✨🎀