PMSERIESQUERY(3)

💖 PMSERIESQUERY(3) 💖

okay bestie, so this is a Library Functions Manual page for PMSERIESQUERY(3) and it is lowkey the whole vibe behind querying time series at speed. buckle up 🎀

---

✨ NAME ✨

pmSeriesQuery, pmSeriesWindow, pmSeriesValues, pmSeriesLoad — fast, scalable time series querying 🦋

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmwebapi.h>

int pmSeriesQuery(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags,
                  void *arg);
int pmSeriesWindow(pmSeriesSettings *sp, sds *window,
                   pmSeriesTimeWindow *window, void *arg);
int pmSeriesValues(pmSeriesSettings *sp, pmSeriesTimeWindow *window,
                   int count, sds *series, void *arg);
int pmSeriesLoad(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags,
                 void *arg);

cc ... -lpcp_web

like, the compile line is right there, no cap. 🔥

---

💅 DESCRIPTION 💅

so if you wanna search for time series identifiers and values using the Performance Co-Pilot (PCP) fast, scalable time series services, the way you normally do it is through the pmseries(1) utility and its bestie the pmproxy(1) REST API service. iconic behavior honestly.

the implementation of all these facilities is shared, and it's available for other programs to use too — not just the cool kids. 🫶 the functionality comes at you through asynchronous APIs, which means they work in that event-driven way where callbacks get invoked for each set of series identifiers or values structures that comes back. and here's the thing, bestie: those callbacks must be registered using pmSeriesSetup(3) before you make any query API calls. no registration, no results. periodt.

the general pattern for these interfaces is that they take an opaque (void * pointer) parameter, arg. that pointer gets passed through unchanged — it's typically used to access a data structure that keeps state inside the calling program. so you can smuggle your little context object through, as a treat. 🎀

depending on the pmseries query string you hand over, pmSeriesQuery operates in one of two modes.

Mode one: if there's no time window specification provided (you know, square brackets []), then the interface returns only matching series identifiers and no values. those identifiers come back via the on_match callback registered using pmSeriesSetup. and here's the ✨ special ✨ part — if the query expression includes function calls or arithmetic operators (rather than just simple metric names), then the returned identifier is dynamically created and persistently associated with the expression. you can retrieve that query expression with the pmSeriesExprs(3) API call. see also PMWEBAPI(3) and the -e option to pmseries(1). iykyk 😌

Mode two: this is where a time window specification is used in the query string, or when the pmSeriesValues interface is used. this mode gives you values and time stamps for all matching time series identifiers that have data points within the provided time window. in this case the results come back via the on_value callback registered using pmSeriesSetup. and there's a little helper routine to create a time window structure from a square-bracket enclosed time specification, and it's called pmSeriesWindow. cute, right? 🌈

if you want further metadata — metric names, labels, units, semantics, type, etc. — about matched time series and their values, that's all available using the interfaces described on the pmSeriesDescs(3) manual page. go get your descs. 👑

typically, loading of time series is handled automatically by the pmproxy daemon, which uses the pmDiscoverSetup(3) series of interfaces to automatically detect and load logged time series from pmlogger(1). but — plot twist — it's also possible to manually load time series from a PCP archive using the pmSeriesLoad interface. the provided query string must provide an archive or directory to load data from using the source.path keyword. don't forget that keyword, bestie, it's doing all the work. 🙈

---

⭐ DIAGNOSTICS ⭐

where these functions return a status code, it's always zero on success. on failure a negative PMAPI error code is returned. so like, zero = slay, negative = not slay. 💀

---

🦋 SEE ALSO 🦋

• pmproxy(1)
• pmlogger(1)
• pmSeriesSetup(3)
• pmSeriesDescs(3)
• pmDiscoverSetup(3)
• PMAPI(3)
• PMWEBAPI(3)

---

and that's the whole page, bestie!! 💖 this one came from Performance Co-Pilot (that's the source, mwah) and the version tag is just PCP, dated back on PMSERIESQUERY(3). go forth and query, you absolute main character. 💅✨🎀