1PMSERIESSETUP(3) Library Functions Manual PMSERIESSETUP(3)
2
6 pmSeriesSetup, pmSeriesSetSlots, pmSeriesSetEventLoop, pmSeriesSetCon‐
7 figuration, pmSeriesSetMetricRegistry, pmSeriesClose - fast, scalable
8 time series services
9
11 #include <pcp/pmwebapi.h>
12 int pmSeriesSetup(pmSeriesModule *module, pmSeriesCallBacks *callbacks,
14 void *arg);
15 int pmSeriesSetSlots(pmSeriesModule *module, void *slots);
17 int pmSeriesSetEventLoop(pmSeriesModule *module, void *uvloop);
18 int pmSeriesSetConfiguration(pmSeriesModule *module, struct dict
19 *config);
20 int pmSeriesSetMetricRegistry(pmSeriesModule *module, struct
21 mmv_registry *registry);
22 int pmSeriesClose(pmSeriesModule *module);
24 cc ... -lpcp_web
26
28 The pmSeriesSetup and related API functions prepare an application for
29 accessing the fast, scalable time series querying functionality of the
30 Performance Co-Pilot (PCP).
31 This functionality is provided through asynchronous APIs, which func‐
33 tion in an event-driven fashion. The interfaces described here prepare
34 a given time series module which associates callback routines with cer‐
35 tain asynchronous events that occur as part of servicing time series
36 requests.
37 As a general pattern, all interfaces in these APIs that need to invoke
39 callbacks provided by the calling program will take an opaque (void *
40 pointer) parameter, arg. This pointer will be passed through unchanged
41 and is typically used to access a data structure maintaining state
42 within the calling program.
43 Where asynchronous setup is required by pmSeriesSetup its completion
45 will be indicated through use of the on_setup callback, which is part
46 of the passed in pmSeriesModule structure. This structure also pro‐
47 vides for custom diagnostics handling, through the on_info callback.
48 These are self-explanatory, see <pcp/pmwebapi.h> for exact calling con‐
49 ventions.
50 The callbacks registered by pmSeriesSetup to handle events are as fol‐
52 lows:
53 pmSeriesMatchCallBack on_match
55 When a time series query discovers time series identifiers that
56 match the query, the on_match callback will be called once for ev‐
57 ery series identifier (SID). The SID is a unique 40-byte ASCII
58 representation of a SHA hash.
59 pmSeriesDescCallBack on_desc
61 Metric descriptor requests from pmSeriesDescs(1) will invoke this
62 callback once for each series identifier.
63 pmSeriesInstCallBack on_inst
65 Instance identification callback - internal (numeric) and external
66 (string) instance IDs, as well as time series and source (host)
67 SHA1 identifiers. Called once for each instance. The associated
68 series identifier is also provided to the callback.
69 pmSeriesLabelCallBack on_labelmap
71 Provides metric labels (name and value mappings) for each series
72 identifier passed to pmSeriesLabels(1).
73 pmSeriesStringCallBack on_instance
75 Provides an instance name for a call to pmSeriesInstances(1)- the
76 callback is called once for each instance name. The associated
77 series identifier is also provided to the callback.
78 pmSeriesStringCallBack on_context
80 Provides a context name for a call to pmSeriesSources(1)- the
81 callback is called once for each source (hostname or archive).
82 The associated source identifier is also provided to the callback.
83 pmSeriesStringCallBack on_metric
85 Provides a metric name for a call to pmSeriesMetrics(1)- the call‐
86 back is called once for each metric name. The associated series
87 identifier is also provided to the callback.
88 pmSeriesStringCallBack on_label
90 Provides a label name for a call to pmSeriesLabels(1)- the call‐
91 back is called once for each label name. The associated series
92 identifier is also provided to the callback.
93 pmSeriesValueCallBack on_value
95 Calls to the pmSeriesQuery interface that provide a time window
96 may result in values being found for matching time series. The
97 on_value callback will be invoked once for each time series value,
98 also providing the sample timestamp (in both string and binary
99 form, as a time in nanoseconds since the epoch). The associated
100 series identifier is also provided to the callback.
101 pmSeriesDoneCallBack on_done
103 On completion of all asynchronous interfaces that return success
104 (zero return code), this callback will be called. It provides a
105 status code indicating overall success (zero) or failure (negative
106 PMAPI code) of the operation.
107 The helper functions pmSeriesSetSlots (redis), pmSeriesSetEventLoop
109 (libuv), pmSeriesSetConfiguration (configuration file) and pmSeriesSet‐
110 MetricRegistry (MMV instrumentation) interfaces provide a mechanism for
111 passing in state for each of the associated subsystems.
112 Finally, a call to pmSeriesClose is used to end services available from
114 a series module previously established through pmSeriesSetup.
115 Within PCP, the pmproxy(1) and pmseries(1) utilities are the primary
117 users of these interfaces, providing REST API and command line time se‐
118 ries query services respectively.
119
121 Where these functions return a status code, this is always zero on suc‐
122 cess. On failure a negative PMAPI error code is returned.
123
125 pmproxy(1), pmlogger(1), pmseries(1), redis-server(1), mmv_stats_reg‐
126 istry(3), pmSeriesDescs(3), pmSeriesQuery(3), PMAPI(3) and PMWEBAPI(3).
127Performance Co-Pilot PCP PMSERIESSETUP(3)