1PMSERIESQUERY(3) Library Functions Manual PMSERIESQUERY(3)
2
6 pmSeriesQuery, pmSeriesWindow, pmSeriesValues, pmSeriesLoad - fast,
7 scalable time series querying
8
10 #include <pcp/pmwebapi.h>
11 int pmSeriesQuery(pmSeriesSettings *sp, sds *query, pmSeriesFlags
13 flags, void *arg);
14 int pmSeriesWindow(pmSeriesSettings *sp, sds *window,
15 pmSeriesTimeWindow *window, void *arg);
16 int pmSeriesValues(pmSeriesSettings *sp, pmSeriesTimeWindow *window,
17 int count, sds *series, void *arg);
18 int pmSeriesLoad(pmSeriesSettings *sp, sds *query, pmSeriesFlags flags,
20 void *arg);
21 cc ... -lpcp_web
23
25 Searching for time series identifiers and values using the Performance
26 Co-Pilot (PCP) fast, scalable time series services is achieved using
27 the pmseries(1) utility, and associated pmproxy(1) REST API service.
28 The implementation of these facilities is shared and available for oth‐
30 er programs to use as well. The functionality is provided through
31 asynchronous APIs, which function in an event-driven fashion where
32 callbacks are invoked for each set of series identifiers or values
33 structure being returned. These callbacks must be registered using pm‐
34 SeriesSetup(3) before any query API calls are made.
35 As a general pattern, these interfaces take an opaque (void * pointer)
37 parameter, arg. This pointer will be passed through unchanged and is
38 typically used to access a data structure maintaining state within the
39 calling program.
40 Depending on the pmseries query string provided, pmSeriesQuery operates
42 in one of two modes.
43 Firstly, if no time window specification is provided (square brackets),
45 then the interface will return only matching series identifiers and no
46 values. These identifiers are returned via the on_match callback reg‐
47 istered using pmSeriesSetup. If the query expression includes function
48 calls or arithmetic operators (rather than simple metric names), then
49 the returned identifier is dynamically created and persistently associ‐
50 ated with the expression. The query expression may be retrieved with
51 the pmSeriesExprs(3) API call. See also PMWEBAPI(3) and the -e option
52 to pmseries(1).
53 The second mode is where a time window specification is used in the
55 query string, or when the pmSeriesValues interface is used. This mode
56 provides values and time stamps for all matching time series identi‐
57 fiers having data points within the provided time window. In this
58 case, the results are returned via the on_value callback registered us‐
59 ing pmSeriesSetup. A helper routine to create a time window structure
60 from a square-bracket enclosed time specification is provided in the
61 form of pmSeriesWindow.
62 Further metadata (metric names, labels, units, semantics, type, etc)
64 about matched time series and their values can be obtained using the
65 interfaces described on the pmSeriesDescs(3) manual page.
66 Typically, loading of time series is handled automatically by the pm‐
68 proxy daemon, which uses the pmDiscoverSetup(3) series of interfaces to
69 automatically detect and load logged time series from pmlogger(1).
70 However, it is also possible to manually load time series from a PCP
71 archive using the pmSeriesLoad interface. The provided query string
72 must provide an archive or directory to load data from using the
73 source.path keyword.
74
76 Where these functions return a status code, this is always zero on suc‐
77 cess. On failure a negative PMAPI error code is returned.
78
80 pmproxy(1), pmlogger(1), pmSeriesSetup(3), pmSeriesDescs(3), pmDiscov‐
81 erSetup(3), PMAPI(3) and PMWEBAPI(3).
82Performance Co-Pilot PCP PMSERIESQUERY(3)