PMSERIESDESCS(3)

💖 PMSERIESDESCS — Library Functions Manual 💖

okay bestie, gather round, because this one is the time series metadata page and it's genuinely so good. this is section 3 of the library functions manual, and the whole vibe is: you want to know stuff about your metrics, not the metrics themselves. metadata era. 💅

---

✨ NAME ✨

pmSeriesDescs, pmSeriesLabels, pmSeriesLabelValues, pmSeriesInstances, pmSeriesMetrics, pmSeriesSources — fast, scalable time series metadata 🌈

---

🎀 C SYNOPSIS 🎀

#include <pcp/pmwebapi.h>

int pmSeriesDescs(pmSeriesSettings *sp, int count, sds *series,
                  void *arg);
int pmSeriesLabels(pmSeriesSettings *sp, int count, sds *series,
                   void *arg);
int pmSeriesLabelValues(pmSeriesSettings *sp, int count, sds *labels,
                        void *arg);
int pmSeriesInstances(pmSeriesSettings *sp, int count, sds *series,
                      void *arg);
int pmSeriesMetrics(pmSeriesSettings *sp, int count, sds *series,
                    void *arg);
int pmSeriesSources(pmSeriesSettings *sp, int count, sds *series,
                    void *arg);

cc ... -lpcp_web

link it with -lpcp_web and you're literally set 🫶

---

💜 DESCRIPTION 💜

so every single performance metric and data source that's part of the Performance Co-Pilot (PCP) fast, scalable time series service comes with certain properties attached — that's the metadata. and you can go query all of it with the interfaces down below. it's giving ✨ receipts ✨.

this whole thing runs on asynchronous APIs, meaning it's event-driven: a callback gets invoked for each metadata structure that comes back at you. no blocking, no waiting around, she's busy. 😭

🌸 the general pattern

as a general pattern, every interface in these APIs that needs to invoke callbacks provided by the calling program (peep pmSeriesSetup(3)) takes an opaque void * parameter, arg. that pointer gets passed straight through, unchanged, and it's typically used to reach a data structure that holds state inside your calling program. so like, your little carry-on bag 🎒.

🌼 the two modes

with a couple of exceptions, these interfaces operate in one of two modes:

1. one invocation queries metadata for a specific (non-zero) count of time series.
2. a second mode — count of zero — returns all available metadata of that type, across all time series. everything. the whole closet. 👑

🦋 pmSeriesDescs

to grab metric descriptor info for one or more time series, you use pmSeriesDescs. for each valid series identifier you hand over, a callback fires giving you the metric units, semantics, and type, plus the other identifiers associated with it (pmID, InDom and source identifier). when you issue this call with a count of zero, it's an error to pass a zero or negative value of count into this interface.

⚠️ bestie. fr fr. pmSeriesDescs does not do the zero-count "give me everything" mode. zero or negative count = error. periodt.

🍓 pmSeriesLabels

to pull label names and values, that's pmSeriesLabels. with a non-zero count of valid series identifiers, this routine invokes a callback once for each label name and once for each label name:value pair, for the labels attached to those time series. if you call it with a count of zero, it returns — via the label name callback — all label names observed to date, not associated with any specific time series.

🧚 pmSeriesLabelValues

pmSeriesLabelValues is comparable to that latter mode, except it returns all label values that have been observed to date for the given array of labels names — and again, not associated with any specific time series identifiers. 🫧

👑 pmSeriesInstances

pmSeriesInstances finds metadata about instance domains and instance identifiers associated with a given (non-zero) count of time series identifiers. if you pass a count of zero, then all instance names observed to date get returned. 💫

🌈 pmSeriesMetrics

pmSeriesMetrics finds metric names associated with a given (non-zero) count of time series identifiers. if you pass a count of zero, then all metric names observed to date get returned. slay.

⭐ pmSeriesSources

pmSeriesSources finds metadata about the source of metrics — that is, host names and archive file paths. if you pass a count of zero, then all metric sources observed to date get returned. iconic.

---

💀 DIAGNOSTICS 💀

wherever these functions return a status code, it's always zero on success. on failure you get a negative PMAPI error code. that's it, that's the whole mood. no cap.

---

🎀 SEE ALSO 🎀

• pmproxy(1)
• pmlogger(1)
• pmseries(1)
• pmSeriesQuery(3)
• pmSeriesSetup(3)
• PMAPI(3)
• PMWEBAPI(3)

go read them, bestie, they're all bangers 💖

---

mwah 💋 this page came to you from Performance Co-Pilot (that's the PCP girlies), and yeah, the date and the whole footer situation — consider it stamped and signed, PMSERIESDESCS(3) through and through.