NAME

pmSeriesSetup, pmSeriesSetSlots, pmSeriesSetEventLoop, pmSeriesSetConfiguration, pmSeriesSetMetricRegistry, pmSeriesClose - fast, scalable time series services

C SYNOPSIS

#include <pcp/pmwebapi.h>

int pmSeriesSetup(pmSeriesModule *module, pmSeriesCallBacks *callbacks, void *arg);

int pmSeriesSetSlots(pmSeriesModule *module, void *slots);
int pmSeriesSetEventLoop(pmSeriesModule *module, void *uvloop);
int pmSeriesSetConfiguration(pmSeriesModule *module, struct dict *config);
int pmSeriesSetMetricRegistry(pmSeriesModule *module, struct mmv_registry *registry);

int pmSeriesClose(pmSeriesModule *module);

cc ... -lpcp_web

DESCRIPTION

The pmSeriesSetup and related API functions prepare an application for accessing the fast, scalable time series querying functionality of the Performance Co-Pilot (PCP).

This functionality is provided through asynchronous APIs, which function in an event-driven fashion. The interfaces described here prepare a given time series module which associates callback routines with certain asynchronous events that occur as part of servicing time series requests.

As a general pattern, all interfaces in these APIs that need to invoke callbacks provided by the calling program will take an opaque (void * pointer) parameter, arg. This pointer will be passed through unchanged and is typically used to access a data structure maintaining state within the calling program.

Where asynchronous setup is required by pmSeriesSetup its completion will be indicated through use of the on_setup callback, which is part of the passed in pmSeriesModule structure. This structure also provides for custom diagnostics handling, through the on_info callback. These are self-explanatory, see <pcp/pmwebapi.h> for exact calling conventions.

The callbacks registered by pmSeriesSetup to handle events are as follows:

pmSeriesMatchCallBack on_match

When a time series query discovers time series identifiers that match the query, the on_match callback will be called once for every series identifier (SID). The SID is a unique 40-byte ASCII representation of a SHA hash.

pmSeriesDescCallBack on_desc

Metric descriptor requests from pmSeriesDescs(1) will invoke this callback once for each series identifier.

pmSeriesInstCallBack on_inst

Instance identification callback - internal (numeric) and external (string) instance IDs, as well as time series and source (host) SHA1 identifiers. Called once for each instance. The associated series identifier is also provided to the callback.

pmSeriesLabelCallBack on_labelmap

Provides metric labels (name and value mappings) for each series identifier passed to pmSeriesLabels(1).

pmSeriesStringCallBack on_instance

Provides an instance name for a call to pmSeriesInstances(1)- the callback is called once for each instance name. The associated series identifier is also provided to the callback.

pmSeriesStringCallBack on_context

Provides a context name for a call to pmSeriesSources(1)- the callback is called once for each source (hostname or archive). The associated source identifier is also provided to the callback.

pmSeriesStringCallBack on_metric

Provides a metric name for a call to pmSeriesMetrics(1)- the callback is called once for each metric name. The associated series identifier is also provided to the callback.

pmSeriesStringCallBack on_label

Provides a label name for a call to pmSeriesLabels(1)- the callback is called once for each label name. The associated series identifier is also provided to the callback.

pmSeriesValueCallBack on_value

Calls to the pmSeriesQuery interface that provide a time window may result in values being found for matching time series. The on_value callback will be invoked once for each time series value, also providing the sample timestamp (in both string and binary form, as a time in nanoseconds since the epoch). The associated series identifier is also provided to the callback.

pmSeriesDoneCallBack on_done

On completion of all asynchronous interfaces that return success (zero return code), this callback will be called. It provides a status code indicating overall success (zero) or failure (negative PMAPI code) of the operation.

The helper functions pmSeriesSetSlots (redis), pmSeriesSetEventLoop (libuv), pmSeriesSetConfiguration (configuration file) and pmSeriesSetMetricRegistry (MMV instrumentation) interfaces provide a mechanism for passing in state for each of the associated subsystems.

Finally, a call to pmSeriesClose is used to end services available from a series module previously established through pmSeriesSetup.

Within PCP, the pmproxy(1) and pmseries(1) utilities are the primary users of these interfaces, providing REST API and command line time series query services respectively.

DIAGNOSTICS

Where these functions return a status code, this is always zero on success. On failure a negative PMAPI error code is returned.

SEE ALSO

pmproxy(1), pmlogger(1), pmseries(1), redis-server(1), mmv_stats_registry(3), pmSeriesDescs(3), pmSeriesQuery(3), PMAPI(3) and PMWEBAPI(3).