pmdainstance(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | MULTI-DIMENSIONAL INSTANCE NAMING | CAVEAT | DIAGNOSTICS | SEE ALSO | COLOPHON

PMDAINSTANCE(3)         Library Functions Manual         PMDAINSTANCE(3)

NAME         top

       pmdaInstance - return instance descriptions for a PMDA

C SYNOPSIS         top

       #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         top

       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, re‐
       sult will contain all the instances names and identifiers in  the
       instance 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
       identifier  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  performed 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
       instance inst.  The result structure is allocated with  malloc(3)
       and should be released by the caller with free(3).

MULTI-DIMENSIONAL INSTANCE NAMING         top

       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-
       dimensional  instance  domain  situations.  For this case the ap‐
       proach used by a number of PMDAs is to structure the external in‐
       stance names using a delimiter (``/'' or ``::'' are most commonly
       used) to allow separation of the other dimensions.  In this situ‐
       ation, instance domain labels should be used to define names  for
       each  instance name component.  This allows PMAPI(3) client tools
       to identify 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 struc‐
       tured using the ``::'' delimiter to separate the two  dimensions.
       The  instance domain itself has been labeled accordingly, as fol‐
       lows.

       $ 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
       example, restricting to processor "cpu0" using the  "cpu"  label,
       perhaps,  or to just the "/app" cgroup metrics using the "cgroup"
       label.

       Furthermore, using this labeling scheme  client  tools  can  also
       correlate 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         top

       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-
       dimensional  instance  names  is performed, the PMDA must use PM‐
       DA_INTERFACE_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         top

       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.

SEE ALSO         top

       malloc(3), PMAPI(3), PMDA(3), pmdaCacheStore(3), pmdaLabel(3) and
       pmGetInDom(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug  report  for  this  manual  page,  send  it  to
       pcp@groups.io.    This  page  was  obtained  from  the  project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩   on  2024-06-14.
       (At that time, the date of the most recent commit that was  found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems  in  this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or  you  have
       corrections  or  improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a  mail  to
       man-pages@man7.org

Performance Co-Pilot               PCP                   PMDAINSTANCE(3)

Pages that refer to this page: pmlogrewrite(1)pmda(3)pmdacache(3)pmdadaemon(3)pmdadso(3)pmdamain(3)