# pmnewcontext

## NAME



           **pmNewContext** - establish a new PMAPI context
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
    
           **int pmNewContext(int** _type_**, const char ***_name_**);**
    
           **cc ... -lpcp**
    


## DESCRIPTION



           An  application using the Performance Metrics Application Program‐
           ming Interface (PMAPI) may manipulate several concurrent contexts,
           each associated with a source of performance metrics, e.g. pmcd(1)
           on some host, or a set of archives of performance metrics as  cre‐
           ated by pmlogger(1), or a stand-alone connection on the local host
           that does not involve pmcd(1).
    
           **pmNewContext** may  be used to establish a new context.  The source
           of the metrics is identified by _name_ , and may  be  either  a  host
           name (_type_ is **PM_CONTEXT_HOST**), or a comma-separated list of names
           referring to a set of archives (_type_ is **PM_CONTEXT_ARCHIVE**).  Each
           element  of  the list may either be the base name common to all of
           the physical files of an archive or the name of a  directory  con‐
           taining archives.
    
           For  a  _type_ of **PM_CONTEXT_HOST** , in addition to identifying a host
           the _name_ may also be used to encode additional  optional  informa‐
           tion  in  the form of a pmcd(1) port number, a pmproxy(1) hostname
           and   a   proxy   port    number.    For    example    the    _name_
           "app23:14321,4321@firewall.example.com:11111"  specifies a connec‐
           tion on port _14321_ (or port  _4321_  if  _14321_  is  unavailable)  to
           pmcd(1) on the host _app23_ via port _11111_ to pmproxy(1) on the host
           _firewall.example.com_.
    
           Alternatively,  for  a  _type_ of **PM_CONTEXT_HOST** , _name_ may be **unix:**
           for an authenticated Unix domain socket connection to  pmcd(1)  on
           the localhost or **local:** for an authenticated connection to pmcd(1)
           on  the  localhost via a Unix domain socket if available, else via
           an internet socket connection to **localhost**.  **local:** is the default
           choice for most applications when calling **pmNewContext** to  estab‐
           lish a context for pmcd(1) on the local host.
    
           For  a  _type_  of  **PM_CONTEXT_ARCHIVE** ,  each element of the list of
           names in _name_ may also be the name of any of the physical files of
           an  archive,  e.g.   _myarchive_**.meta**(the   metadata   file)   or
           _myarchive_**.index**(the temporal index) or _myarchive_**.0**(the first da‐
           ta  volume  of  the  archive) or _myarchive_**.0.bz2** or _myarchive_**.0.bz**
           (the first data volume compressed with **bzip2**(1)) or _myarchive_**.0.gz**
           or _myarchive_**.0.Z** or _myarchive_**.0.z**(the  first  data  volume  com‐
           pressed   with   **gzip**(1)),   _myarchive_**.1** or  _myarchive_**.3.bz2** or
           _myarchive_**.42.gz** etc.
    
           If more than one archive  is  specified  for  a  _type_  of  **PM_CON‐**
           **TEXT_ARCHIVE** ,  there  are some restrictions on the archives within
           the set:
           •  The archives must all have been generated on the same host.
           •  The archives must not overlap in time.
           •  The archives must all have been created using the same time
              zone.
           •  The _PMID_ of each metric should be the same in all of the
              archives.  Multiple _PMID_ s are currently tolerated by using the
              first _PMID_ defined for each metric and ignoring subsequent
              _PMID_ s.
           •  The type of each metric must be the same in all of the
              archives.
           •  The semantics of each metric must be the same in all of the
              archives.
           •  The units of each metric must be the same in all of the
              archives.
           •  The instance domain of each metric must be the same in all of
              the archives.
    
           In the case where _type_ is **PM_CONTEXT_LOCAL** , _name_ is ignored, and
           the context uses a stand-alone connection to the PMDA methods used
           by pmcd(1).  The mechanism in the library uses the same ``plugin''
           architecture that operates between pmcd(1) and DSO PMDAs, so oper‐
           ations involve function calls rather than IPC message passing -
           for **PM_CONTEXT_LOCAL** contexts this may mean lower latency for op‐
           erations like pmFetch(3), but at the cost of longer initialization
           time and possible access control differences compared to pmcd(1).
           When this type of context is used, the range of accessible perfor‐
           mance metrics is constrained to those from the DSO PMDAs defined
           in the pmcd(1) configuration file **/etc/pcp/pmcd/pmcd.conf** , so
           those reported by the command
                   $ awk '$3 == "dso" {print}' /etc/pcp/pmcd/pmcd.conf
           or alternatively reported by the command
                   $ pminfo -f pmcd.agent.type | grep 'value 0'
           This usually means the PMDA exporting metrics from the operating
           system and the ``pmcd'', ``pmproxy'' and may includes some others
           like ``mmv''.  Alternate DSO PMDAs can be used, refer to
           pmSpecLocalPMDA(3).
    
           In the case where _type_ is **PM_CONTEXT_HOST** , additional flags can be
           added to the _type_ to indicate if the connection to pmcd(1) should
           be encrypted (**PM_CTXFLAG_SECURE**), should be encrypted if possible
           (**PM_CTXFLAG_RELAXED**), is deferred (**PM_CTXFLAG_SHALLOW**), should use
           authentication (**PM_CTXFLAG_AUTH**), should be a connection to a con‐
           tainer (**PM_CTXFLAG_CONTAINER**), or if the file descriptor used to
           communicate with pmcd(1), should not be shared across contexts
           (**PM_CTXFLAG_EXCLUSIVE**).  Both the **PM_CTXFLAG_SHALLOW** and
           **PM_CTXFLAG_EXCLUSIVE** flags are now deprecated and ignored.
    
           When _type_ is **PM_CONTEXT_ARCHIVE** , additional flags can be added to
           the _type_ for restricted handling of the archive suited to applica‐
           tions that are aware of the structure of PCP archives, namely
           **PM_CTXFLAG_NO_FEATURE_CHECK**(do not check feature compatibility
           for archive label records), **PM_CTXFLAG_METADATA_ONLY**(open only
           the metadata, not the data volume(s) nor the index) and
           **PM_CTXFLAG_LAST_VOLUME**(open the archive at the start of the _last_
           data volume, instead of the default start of the _first_ data vol‐
           ume).
    
           Multiple flags can be specified by bit-wise ``or-ing'' of the
           **PM_CTXFLAG** macros, but not all combinations make sense, e.g. if
           **PM_CTXFLAG_METADATA_ONLY** and **PM_CTXFLAG_LAST_VOLUME** are specified,
           **PM_CTXFLAG_METADATA_ONLY** takes precedence.
    
           The initial instance profile is set up to select all instances in
           all instance domains.  In the case of a set of archives, the ini‐
           tial collection time is also set to zero, so that an initial
           pmFetch(3) will result in the earliest set of metrics being re‐
           turned from the set of archives.
    
           Once established, the association between a context and a source
           of metrics is fixed for the life of the context, however routines
           are provided to independently manipulate both the instance profile
           (see pmAddProfile(3) and pmDelProfile(3)) and the collection time
           for archives (see pmSetMode(3)).
    
           **pmNewContext** returns a handle that may be used with subsequent
           calls to pmUseContext(3).
    
           The new context remains the current PMAPI context for all subse‐
           quent calls across the PMAPI, until another call to
           pmNewContext(3) is made, or the context is explicitly changed with
           a call to pmDupContext(3) or pmUseContext(3), or destroyed using
           pmDestroyContext(3).
    
           When attempting to connect to a remote pmcd(1) on a machine that
           is booting, **pmNewContext** could potentially block for a long time
           until the remote machine finishes its initialization.  **pmNewCon‐**
           **text** will abort and return an error if the connection has not been
           established after some specified interval has elapsed.  The de‐
           fault interval is 5 seconds.  This may be modified by setting **PM‐**
           **CD_CONNECT_TIMEOUT** in the environment to a real number of seconds
           for the desired timeout.  This is most useful in cases where the
           remote host is at the end of a slow network, requiring longer la‐
           tencies to establish the connection correctly.
    


## CAVEATS



           When using a _type_ of **PM_CONTEXT_LOCAL** , the operating system PMDA
           may export data structures directly from the kernel, which means
           that the **pmNewContext** caller should be an executable program com‐
           piled for the same object code format as the booted kernel.
    
           In addition, applications using a **PM_CONTEXT_LOCAL** context must be
           single-threaded because the various DSO PMDAs may not be thread-
           safe.  This restriction is enforced at the PMAPI(3), where rou‐
           tines may return the error code **PM_ERR_THREAD** if the library de‐
           tects calls from more than one thread.
    
           Applications that use gethostbyname(3) should exercise caution be‐
           cause the static fields in _struct hostent_ may not be preserved
           across some PMAPI(3) calls.  In particular, pmNewContext(3) and
           pmReconnectContext(3) both may call gethostbyname(3) internally.
    


## DIAGNOSTICS



           **PM_ERR_PERMISSION**
    
                  No permission to perform requested operation
    
           **PM_ERR_CONNLIMIT**
    
                  PMCD connection limit for this host exceeded
    
           **PM_ERR_NOCONTEXT**
    
                  Requested context type was not **PM_CONTEXT_LOCAL** , **PM_CON‐**
                  **TEXT_HOST** or **PM_CONTEXT_ARCHIVE**.
    
           **PM_ERR_LOGOVERLAP**
    
                  Archives overlap in time
    
           **PM_ERR_LOGHOST**
    
                  Archives differ by host
    
           **PM_ERR_LOGCHANGETYPE**
    
                  The type of a metric differs among archives
    
           **PM_ERR_LOGCHANGESEM**
    
                  The semantics of a metric differs among archives
    
           **PM_ERR_LOGCHANGEINDOM**
    
                  The instance domain of a metric differs among archives
    
           **PM_ERR_LOGCHANGEUNITS**
    
                  The units of a metric differs among archives
    


## ENVIRONMENT



           **PMCD_CONNECT_TIMEOUT**
                  Timeout period (in seconds) for pmcd(1) connection at‐
                  tempts.
    
           **PMCD_PORT**
                  TCP/IP port(s) for connecting to pmcd(1), historically was
                  4321 and more recently the officially registered port
                  44321; in the current release, **pmcd** listens on both these
                  ports as a transitional arrangement.  If used, should be
                  set to a comma-separated list of numerical port numbers.
    


* * *