# pmseriessetup

## 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 functionali‐
           ty 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 comple‐
           tion 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 ex‐
                ternal (string) instance identifiers, as well as time series
                and source (host) SHA1 identifiers.  Called once for each in‐
                stance.  The associated series identifier is also provided to
                the callback.
    
           **pmSeriesLabelCallBack** _on_labelmap_
                Provides metric labels (name and value mappings) for each se‐
                ries 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 as‐
                sociated 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 win‐
                dow may result in values being found for matching time se‐
                ries.  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 provid‐
                ed to the callback.
    
           **pmSeriesDoneCallBack** _on_done_
                On completion of all asynchronous interfaces that return suc‐
                cess (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**(key-value server), **pm‐**
           **SeriesSetEventLoop**(libuv), **pmSeriesSetConfiguration**(configura‐
           tion file) and **pmSeriesSetMetricRegistry**(MMV instrumentation) in‐
           terfaces 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 pri‐
           mary 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.
    


* * *