# pmdainstance

## NAME



           **pmdaInstance** - return instance descriptions for a PMDA
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
           **#include <pcp/pmda.h>**
    
           **int pmdaInstance(pmInDom** _indom_**, int** _inst_**, char ***_name_**,**
                            **pmInResult ****_result_**, pmdaExt ***_pmda_**);**
    
           **cc ... -lpcp_pmda -lpcp**
    


## DESCRIPTION



           **pmdaInstance** uses  the standard PMDA(3) data structures to return
           information concerning the instance domain _indom_.
    
           The _result_ structure is constructed by **pmdaInstance** and will  con‐
           tain one or more instance names and/or identifiers as specified by
           the _inst_ and _name_ arguments.
    
           If _inst_ has the value **PM_IN_NULL** and _name_ is a null string, _result_
           will  contain  all  the instances names and identifiers in the in‐
           stance domain.
    
           If _inst_ is **PM_IN_NULL** but _name_ is the name of an instance  in  the
           instance domain _indom_ , then _result_ will contain the instance iden‐
           tifier  for  instance _name_.  Note that if _name_ contains no spaces,
           partial matching up to the first space in  the  instance  name  is
           performed,  i.e.  ``**1** '' will match instance name ``**1 minute** ''.  If
           _name_ contains an embedded space, then no partial matching is  per‐
           formed and _name_ should match one of the instance names exactly.
    
           If _name_ is a null string but _inst_ is an instance identifier in the
           instance  domain  _indom_ , then _result_ will contain the name for in‐
           stance _inst_.  The _result_ structure is allocated with malloc(3) and
           should be released by the caller with free(3).
    


## MULTI-DIMENSIONAL INSTANCE NAMING



           Further to the above description of _name_ , the  set  of  rules  de‐
           scribing    external   instance   names   is   provided   in   the
           pmdaCacheStore(3) manual page.
    
           Instance domains adds another dimension (set of  values)  to  met‐
           rics.  However, this may not suffice to describe complex multi-di‐
           mensional  instance domain situations.  For this case the approach
           used by a number of PMDAs is to structure  the  external  instance
           names  using  a delimiter (``/'' or ``::'' are most commonly used)
           to allow separation of the other dimensions.  In  this  situation,
           instance domain labels should be used to define names for each in‐
           stance name component.  This allows PMAPI(3) client tools to iden‐
           tify and refine value fetches to specific dimensions of interest.
    
           For  example, some of the Linux kernel cgroup (control group) met‐
           ric instance domains are multi-dimensional.  The  instance  domain
           represents  individual values across both control groups and CPUs,
           making this a two-dimensional instance domain.  The instance names
           associated with this cgroup metrics indom have been structured us‐
           ing the ``::'' delimiter to separate the two dimensions.  The  in‐
           stance domain itself has been labeled accordingly, as follows.
    
           **$ pminfo --desc --fetch --labels cgroup.cpuacct.usage_percpu**
           cgroup.cpuacct.usage_percpu
                Data Type: 64-bit unsigned int  InDom: 3.22 0xc00016
                Semantics: counter  Units: nanosec
                inst [0 or "/::cpu0"] value 713787
                inst [1 or "/::cpu1"] value 353969
                inst [2 or "/app::cpu0"] value 407816
                inst [3 or "/app::cpu1"] value 202747
                inst [0 or "/::cpu0"] labels {"device_type":"cpu","cgroup":"/","cpu":0}
                inst [1 or "/::cpu1"] labels {"device_type":"cpu","cgroup":"/","cpu":1}
                inst [2 or "/app::cpu0"] labels {"device_type":"cpu","cgroup":"/app","cpu":0}
                inst [3 or "/app::cpu1"] labels {"device_type":"cpu","cgroup":"/app","cpu":1}
    
           **$ pminfo --labels 3.22**
           InDom: 3.22 0xc00016
                labels {"device_type":"cpu"}
    
           As  shown  above  the individual instances inherit the labels from
           the instance domain, and the PMDA also applies additional  per-in‐
           stance  labels  describing  individual cgroup and CPU names.  When
           this model has been used by the PMDA, PMAPI clients  are  able  to
           restrict their queries to the cgroup metric instances - in the ex‐
           ample, restricting to processor "cpu0" using the "cpu" label, per‐
           haps,  or to just the "/app" cgroup metrics using the "cgroup" la‐
           bel.
    
           Furthermore, using this labeling scheme client tools can also cor‐
           relate related instances across different instance domains.
    
           **$ pminfo --desc --fetch --labels kernel.percpu.cpu.irq.soft**
           kernel.percpu.cpu.irq.soft
                Data Type: 64-bit unsigned int  InDom: 60.0 0xf000000
                Semantics: counter  Units: millisec
                inst [0 or "cpu0"] value 6770
                inst [1 or "cpu1"] value 100
                inst [0 or "cpu0"] labels {"device_type":"cpu"}
                inst [1 or "cpu1"] labels {"device_type":"cpu"}
    
           **$ pminfo --labels 60.0**
           InDom: 60.0 0xf000000
                labels {"device_type":"cpu"}
    
           Although these two metrics have different instance  domains  (_60.0_
           and  _3.22_  respectively) and are sourced from different PMDAs, the
           "device_type" label identifies the common device  to  which  these
           values relate.
    


## CAVEAT



           The  PMDA must be using **PMDA_INTERFACE_2** or later, as specified in
           the call to pmdaDSO(3) or pmdaDaemon(3).  If labeling of multi-di‐
           mensional instance names is performed, the PMDA must use  **PMDA_IN‐**
           **TERFACE_7** or later.
    
           Because  of optional partial matching up to the first space in the
           instance name, the **PMDA** developer should ensure that  if  instance
           names  are  allowed to have spaces, the names are unique up to the
           first space.
    


## DIAGNOSTICS



           If any errors occur during the execution of **pmdaInstance** , the  _re‐_
           _sult_  structure  is  deallocated.  If the instance domain _indom_ is
           not supported by the PMDA, **pmdaInstance** will return **PM_ERR_INDOM**.
    
           If the _inst_ or _name_ does not correspond to any  instances  in  the
           _indom_ domain, **pmdaInstance** will return **PM_ERR_INST**.
    


* * *