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).