1PMSERIESDESCS(3) Library Functions Manual PMSERIESDESCS(3)
2
6 pmSeriesDescs, pmSeriesLabels, pmSeriesLabelValues, pmSeriesInstances,
7 pmSeriesMetrics, pmSeriesSources - fast, scalable time series metadata
8
10 #include <pcp/pmwebapi.h>
11 int pmSeriesDescs(pmSeriesSettings *sp, int count, sds *series, void
13 *arg);
14 int pmSeriesLabels(pmSeriesSettings *sp, int count, sds *series, void
15 *arg);
16 int pmSeriesLabelValues(pmSeriesSettings *sp, int count, sds *labels,
17 void *arg);
18 int pmSeriesInstances(pmSeriesSettings *sp, int count, sds *series,
19 void *arg);
20 int pmSeriesMetrics(pmSeriesSettings *sp, int count, sds *series, void
21 *arg);
22 int pmSeriesSources(pmSeriesSettings *sp, int count, sds *series, void
23 *arg);
24 cc ... -lpcp_web
26
28 Each performance metric and data source forming part of the Performance
29 Co-Pilot (PCP) fast, scalable time series service has certain proper‐
30 ties (metadata) associated with it. These properties can be queried
31 using the interfaces described here.
32 This functionality is provided through asynchronous APIs, which func‐
34 tion in an event-driven fashion where callbacks are invoked for each
35 metadata structure being returned.
36 As a general pattern, all interfaces in these APIs that need to invoke
38 callbacks provided by the calling program (see pmSeriesSetup(3)) will
39 take an opaque (void * pointer) parameter, arg. This pointer will be
40 passed through unchanged and is typically used to access a data struc‐
41 ture maintaining state within the calling program.
42 With a couple of exceptions, these interfaces tend to operate in one of
44 two modes. Firstly, one invocation is available to query metadata for
45 a specific (non-zero) count of time series. A second, (zero) count,
46 mode returns all available metadata of that type, across all time se‐
47 ries.
48 In order to retrieve metric descriptor information for one or more time
50 series, the pmSeriesDescs interface is used. For each valid series
51 identifier provided, a callback will be invoked providing the metric
52 units, semantics, and type as well as other identifiers associated with
53 it (pmID, InDom and source identifier). When this call is issued with
54 a zero value for count, It is an error to pass a zero or negative value
55 of count into this interface.
56 To extract label names and values, the pmSeriesLabels interface is
58 used. With a non-zero value for count valid series identifiers, this
59 routine will invoke a callback once for each label name and once for
60 each label name:value pair, for labels associated with those time se‐
61 ries. If called with a count of zero, this interface will return (via
62 the label name callback) all label names that have observed to date -
63 not associated with specific time series. The pmSeriesLabelValues in‐
64 terface is comparable to this latter mode, except will return all label
65 values that have been observed to date for the given array of labels
66 names (not associated with any specific time series identifiers).
67 pmSeriesInstances can be used to find metadata about instance domains
69 and instance identifiers associated with a given (non-zero) count of
70 time series identifiers. If a zero value is passed for count then all
71 instance names observed to date will be returned.
72 pmSeriesMetrics can be used to find metric names associated with a giv‐
74 en (non-zero) count of time series identifiers. If a zero value is
75 passed for count then all metric names observed to date will be re‐
76 turned.
77 pmSeriesSources can be used to find metadata about the source of met‐
79 rics - that is, host names and archive file paths. If a zero value is
80 passed for count then all metric sources observed to date will be re‐
81 turned.
82
84 Where these functions return a status code, this is always zero on suc‐
85 cess. On failure a negative PMAPI error code is returned.
86
88 pmproxy(1), pmlogger(1), pmseries(1), pmSeriesQuery(3), pmSeriesSet‐
89 up(3), PMAPI(3) and PMWEBAPI(3).
90Performance Co-Pilot PCP PMSERIESDESCS(3)