Product SiteDocumentation Site

3.8.4. PMAPI Context Services

Table 3.1, “Context Components of PMAPI Functions ” shows which of the three components of a PMAPI context (metrics source, instance profile, and collection time) are relevant for various PMAPI functions. Those PMAPI functions not shown in this table either manipulate the PMAPI context directly, or are executed independently of the current PMAPI context.

Table 3.1. Context Components of PMAPI Functions

Function Name
Metrics Source
Instance Profile
Collection Time
Notes
pmAddProfile
Yes
Yes
 
 
pmDelProfile
Yes
Yes
 
 
pmDupContext
Yes
Yes
Yes
 
pmFetch
Yes
Yes
Yes
 
pmFetchArchive
Yes
 
Yes
(1)
pmGetArchiveEnd
Yes
 
 
(1)
pmGetArchiveLabel
Yes
 
 
(1)
pmGetChildren
Yes
 
 
 
pmGetChildrenStatus
Yes
 
 
 
pmGetContextHostName
Yes
 
 
 
pmGetPMNSLocation
Yes
 
 
 
pmGetInDom
Yes
 
Yes
(2)
pmGetInDomArchive
Yes
 
 
(1)
pmLookupDesc
Yes
 
 
(3)
pmLookupInDom
Yes
 
Yes
(2)
pmLookupInDomArchive
Yes
 
 
(1,2)
pmLookupInDomText
Yes
 
 
 
pmLookupLabels
Yes
 
 
 
pmLookupName
Yes
 
 
 
pmLookupText
Yes
 
 
 
pmNameAll
Yes
 
 
 
pmNameID
Yes
 
 
 
pmNameInDom
Yes
 
Yes
(2)
pmNameInDomArchive
Yes
 
 
(1,2)
pmSetMode
Yes
 
Yes
 
pmStore
Yes
 
 
(4)
pmTraversePMNS
Yes
 
 
 
Notes:
  1. Operation supported only for PMAPI contexts where the source of metrics is an archive.
  2. A specific instance domain is included in the arguments to these functions, and the result is independent of the instance profile for any PMAPI context.
  3. The metadata that describes a performance metric is sensitive to the source of the metrics, but independent of any instance profile and of the collection time.
  4. This operation is supported only for contexts where the source of the metrics is a host. Further, the instance identifiers are included in the argument to the function, and the effects upon the current values of the metrics are immediate (retrospective changes are not allowed). Consequently, from the current PMAPI context, neither the instance profile nor the collection time influence the result of this function.

3.8.4.1.  pmNewContext Function

int pmNewContext(int type, const char *name)
The pmNewContext function may be used to establish a new PMAPI context. The source of metrics is identified by name, and may be a host specification (type is PM_CONTEXT_HOST) or a comma-separated list of names referring to a set of archive logs (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 log or the name of a directory containing archive logs.
A host specification usually contains a simple hostname, an internet address (IPv4 or IPv6), or the path to the PMCD Unix domain socket. It can also specify properties of the connection to PMCD, such as the protocol to use (secure and encrypted, or native) and whether PMCD should be reached via a pmproxy host. Various other connection attributes, such as authentication information (user name, password, authentication method, and so on) can also be specified. Further details can be found in the PCPIntro(3) man page, and the companion Performance Co-Pilot Tutorials and Case Studies document.
In the case where type is PM_CONTEXT_ARCHIVE, there are some restrictions on the archives within the specified 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 pmIDs are currently tolerated by using the first pmID defined for each metric and ignoring subsequent pmIDs.
  • 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. When this type of context is in effect, the range of accessible performance metrics is constrained to DSO PMDAs listed in the pmcd configuration file ${PCP_PMCDCONF_PATH}. The reason this is done, as opposed to all of the DSO PMDAs found below ${PCP_PMDAS_DIR} for example, is that DSO PMDAs listed there are very likely to have their metric names reflected in the local Name Space file, which will be loaded for this class of context.
The initial instance profile is set up to select all instances in all instance domains, and the initial collection time is the current time at the time of each request for a host, or the time at the start of the first log for a set of archives. In the case of archives, the initial collection time results in the earliest set of metrics being returned from the set of archives at the first pmFetch.
Once established, the association between a PMAPI context and a source of metrics is fixed for the life of the context; however, functions are provided to independently manipulate both the instance profile and the collection time components of a context.
The function returns a “handle” that may be used in subsequent calls to pmUseContext. This new PMAPI context stays in effect for all subsequent context sensitive calls across the PMAPI until another call to pmNewContext is made, or the context is explicitly changed with a call to pmDupContext or pmUseContext.
For the python bindings creating and destroying a PMAPI context is done by creating and destroying an object of the pmapi class.