This is a writeup to be added to the programmer's guide for the python
api (site-packages/pcp/pmapi.py). The "For more information see the C
function description" lines all point back to the C function writeup.
The index entries add an entry for "pmEntry python", e.g.
pmNameAll function
pmNameAll Function <links to C writeup>
pmNameAll Python <links to python writeup>
PMAPI Python Procedural Interface
The following sections describe all of the PMAPI functions that provide
access to the PCP infrastructure
on behalf of a client application:
• PMAPI Name Space services
• PMAPI metric description services
• PMAPI instance domain services
• PMAPI context services
• PMAPI timezone services
• PMAPI metrics services
• PMAPI record-mode services
• PMAPI archive-specific services
• PMAPI time control services
• PMAPI ancillary support services
PMAPI Name Space Services
pmGetChildren Function
[name1, name2...] = pmGetChildren(name)
Return names of children for the given PMNS node name. Given a full
pathname to a node in the current
PMNS, as identified by name, return a tuple containing the relative
names of all the immediate descendents
of name in the current PMNS. For more information see the C function
description.
pmGetChildrenStatus Function
([name1, name2...],[status1, status2...]) = pmGetChildrenStatus(name)
Return names and status of children for the given metric name. Given a
full pathname to a node in the
current PMNS, as identified by name, return a tuple containing the
relative names and statuses of all the
immediate descendents of name in the current PMNS. For more information
see the C function description.
pmGetPMNSLocation Function
int loc = pmGetPMNSLocation()
Return the namespace location type. Returns whether a PMNS is an archive
cpmapi.PMNS_ARCHIVE, a
local PMNS file cpmapi.PMNS_LOCAL, or a remote PMCD cpmapi.PMNS_REMOTE.
The constants
are available by importing cpmapi. For more information see the C
function description.
pmLoadNameSpace Function
int status = pmLoadNameSpace(filename)
Load a local namespace. Load a local tailored Name Space from filename.
For more information see
the C function description.
pmLookupName Function
c_uint pmid [] = pmLookupName("MetricName")
c_uint pmid [] = pmLookupName(("MetricName1", "MetricName2", ...))
e.g. pmid = pmLookupName(("hinv.ncpu","kernel.all.load"))
Lookup pmIDs from a list of metric names. Return an array of associated
PMIDs corresponding to a
tuple of MetricNames. The returned pmid tuple is passed to pmLookupDescs
and pmFetch. For more
information see the C function description.
pmNameAll Function
[name1, name2...] = pmNameAll(pmid_id)
Return a tuple of all metric names having this identical pmid. For more
information see the C function
description.
pmNameID Function
str name = pmNameID(pmid)
Return a metric name corresponding to a pmid. For more information see
the C function description.
pmTraversePMNS Function
int status = pmTraversePMNS(name, traverse_callback)
Perform a depth first traversal of the PMNS by scanning namespace, depth
first, and call a python
function traverse_callback for each node. For more information see the C
function description.
pmUnLoadNameSpace Function
pmUnLoadNameSpace("NameSpace")
If a local PMNS was loaded with pmLoadNameSpace, calling
pmUnloadNameSpace forces all
subsequent Name Space functions to use the distributed PMNS. For more
information see the C function
description.
PMAPI Metrics Description Services
pmLookupDesc Function
pmDesc* pmdesc = pmLookupDesc(c_uint pmid)
Lookup a metric description structure pmDesc corresponding to pmid. The
returned pmdesc is passed
to pmExtractValue and pmLookupInDom. For more information see the C
function description.
pmLookupDescs Function
(pmDesc* pmdesc)[] = pmLookupDescs(c_uint pmids[N])
(pmDesc* pmdesc)[] = pmLookupDescs(c_uint pmid)
Similar to pmLookupDesc but does a metric description lookup for each
element in a PMID array pmids.
pmLookupDescs python function
pmLookupInDomText Function
"instance" = pmLookupInDomText(pmDesc pmdesc)
Lookup the description text about the performance metrics pmDesc pmdesc.
The default is a one line
summary; for a more verbose description add an optional second parameter
cpmapi.PM_TEXT_HELP.
The constant is available by importing cpmapi. For more information see
the C function description.
pmLookupText Function
"desc" = pmLookupText(pmID pmid)
Lookup the description text about the performance metrics pmID pmid. The
default is a one line
summary; for a more verbose description add an optional second parameter
cpmapi.PM_TEXT_HELP.
The constant is available by importing cpmapi. For more information see
the C function description.
PMAPI Instance Domain Services
pmGetInDom Function
([instance1, instance2...] [name1, name2...]) pmGetInDom(pmDesc pmdesc)
Return the list of instances and a list of instance names for an
instance domain pmdesc. For more
information see the C function description.
pmLookupInDom Function
int instid = pmLookupInDom(pmDesc pmdesc, "Instance")
Return the instance id corresponding to "Instance" in the instance
domain pmdesc. For more
information see the C function description.
pmNameInDom Function
"string" = pmNameInDom(pmDesc pmdesc, c_uint instid)
Return the text name of an instance corresponding to an instance domain
pmdesc with instance identifier
instid. For more information see the C function description.
PMAPI Context Services
pmNewContext Function
This is unimplemented. A new context is established when a pmContext
object is created.
For more information see the C function description.
pmDestroyContext Function
This is unimplemented. The context is destroyed when the pmContext
object is destroyed.
For more information see the C function description.
pmDupContext Function
pmContext context = pmDupContext()
This is unimplemented. Context changes are handled by the individual
methods in a pmContext class
instance. For more information see the C function description.
pmUseContext Function
This is unimplemented. Context changes are handled by the individual
methods in a pmContext class instance.
For more information see the C function description.
pmWhichContext Function
int ctx_idx = pmWhichContext()
Returns the handle of the current PMAPI context. For more information
see the C function description.
pmAddProfile Function
int status = pmAddProfile(pmDesc pmdesc, c_uint instid)
int status = pmAddProfile(pmDesc pmdesc, [c_uint instid])
add the list of instances instid to the instance profile of the instance
pmdesc. For more information
see the C function description.
pmDelProfile Function
int status = pmDelProfile(pmDesc pmdesc, c_uint instid)
int status = pmDelProfile(pmDesc pmdesc, [c_uint instid])
delete the list of instances instid from the instance profile of the
instance domain pmdesc. For more
information see the C function description.
pmSetMode Function
int status = pmSetMode(mode, timeVal timeval, int delta)
Define the collection time and mode for reading archive files. mode is
defined in the c_api.PM_MODE*
constants defined in by importing cpmapi. For more information see the C
function description.
pmReconnectContext Function
int status = pmReconnectContext()
Reestablish the connection for the context. For more information see the
C function description.
pmGetContextHostName Function
"hostname" = pmGetContextHostName()
Retrieve the hostname for the given context.
PMAPI Timezone Services
pmNewContextZone Function
pmNewContextZone()
Query and set the current reporting timezone. For more information see
the C function description.
pmNewZone Function
int tz_handle = pmNewZone(int tz)
Create new zone handle and set reporting timezone for the timezone
defined by tz. For more information
see the C function description.
pmUseZone Function
int status = pmUseZone(int tz_handle)
Sets the current reporting timezone defined by timezone tz_handle. For
more information see the C
function description.
pmWhichZone Function
"zone string" = pmWhichZone()
Return the current reporting timezone. For more information see the C
function description.
pmLocaltime Function
struct tm *pmLocaltime (int seconds);
Convert the date and time for a reporting timezone.
pmCtime Function
"time string" = pmCtime (int seconds)
Format the date and time for a reporting timezone.
PMAPI Metrics Services
pmFetch Function
pmResult* pmresult = pmFetch(c_uint pmid[])
Fetch a pmResult corresponding to a pmid list, which is returned from
pmLookupName. The returned
pmresult is passed to pmExtractValue. For more information see the C
function description.
pmFreeResult Function
pmFreeResult(pmResult* pmresult)
Free a pmresult previously allocated by pmFetch. For more information
see the C function description.
pmStore Function
pmResult* pmresult = pmStore(pmResult* pmresult)
The inverse of pmFetch. For more information see the C function description.
PMAPI Archive-Specific Services
pmGetArchiveLabel Function
int loglabel = pmGetArchiveLabel()
Get the label record from the archive. For more information see the C
function description.
pmGetArchiveEnd Function
int status = pmGetArchiveEnd()
Get the last recorded timestamp from the archive. For more information
see the C function description.
pmGetInDomArchive Function
((instance1, instance2...) (name1, name2...)) pmGetInDom(pmDesc pmdesc)
Get the instance IDs and names for the union of all instances for the
instance domain pmdesc that can be
found in the archive log. For more information see the C function
description.
pmLookupInDomArchive Function
c_uint instid = pmLookupInDomArchive(pmDesc pmdesc, "Instance")
Return the instance id in pmdesc corresponding to Instance. For more
information see the C function
description.
pmNameInDomArchive Function
"string" = pmNameInDomArchive(pmDesc pmdesc, c_uint instid)
Return the text name of an instance corresponding to an instance domain
pmdesc with instance identifier
instid. For more information see the C function description.
pmFetchArchive Function
pmResult* pmresult = pmFetchArchive()
Fetch measurements from the target source. For more information see the
C function description.
PMAPI Ancilliary Support Services
pmGetConfig Function
"string" = pmGetConfig ("env variable")
Return value for environment variable "env variable" from environment or
pcp config file.
pmErrStr Function
"string" = pmErrStr (int error_code)
Return error string for error code. For more information see the C
function description.
pmExtractValue Function
pmAtomValue = pmExtractValue(int valfmt, const pmValue * ival,
int itype,
pmAtomValue *oval,
int otype)
e.g. pmExtractValue(results.contents.get_valfmt(i),
results.contents.get_vlist(i, 0),
descs[i].contents.type, c_api.PM_TYPE_FLOAT)
Extract a value from a pmValue struct ival stored in format valfmt (see
pmFetch), and convert its
type from itype to otype. For more information see the C function
description.
pmConvScale Function
pmAtomValue = pmConvScale(int itype, pmAtomValue value,
pmDesc* pmdesc , int descidx, int otype)
e.g. pmConvScale(c_api.PM_TYPE_FLOAT, pmAtomValue,
pmDesc*, 3, c_api.PM_SPACE_MBYTE)
Convert a value pointed to by pmdesc entry descidx to a different scale
otype. For more
information see the C function description.
pmUnitsStr Function
"units string" = pmUnitsStr(pmUnits pmunits)
Translate a pmUnits struct pmunits to a readable string. For more
information see the C function
description.
pmIDStr Function
"ID string" = pmIDStr(int pmID)
Translate a pmID pmid to a readable string. For more information see the
C function description.
pmInDomStr Function
"indom" = pmGetInDom(pmDesc pmdesc)
Translate an instance domain ID pointed to by a pmDesc pmdesc to a
readable string. For more
information see the C function description.
pmTypeStr Function
"type" = pmTypeStr(int type)
Translate a performance metric type to a readable string. Constants are
available for the types, e.g.
c_api.PM_TYPE_FLOAT, by importing cpmapi. For more information see the C
function description.
pmAtomStr Function
"value" = pmAtomStr(atom, type)
Translate a pmAtomValue atom having performance metric type to a
readable string. Constants are
available for the types, e.g. c_api.PM_TYPE_U32, by importing cpmapi.
For more information see the
C function description.
pmPrintValue Function
pmPrintValue(FILE* file, pmResultpmresult, pmdesc, vset_index,
vlist_index, min_wid
e.g. pmPrintValue(file, value, pmdesc, vset_index, vlist_index, min_width)
Print the value of a pmresult pointed to by vset_index/vlist_index and
described by pmdesc.
The format of a pmResult is described in pmResult For more information
see the C function description.
pmflush Function
int status = pmFlush()
flush the internal buffer shared with pmprintf. For more information see
the C function description.
pmprintf Function
append message to internal buffer for later printing. For more
information see the C function description.
pmSortInstances Function
pmSortInstances (pmResult* pmresult)
sort all metric instances in result returned by pmFetch. For more
information see the C function description.
pmParseInterval Function
(struct timeval, "error message") = pmParseInterval("time string")
parse a "time string" into a timeval struct. For more information see
the C function description.
pmParseMetricSpec Function
(pmMetricSpec metricspec ,errormsg) = pmParseMetricSpec("metric
specification", isa
e.g. (result,errormsg) = pmParseMetricSpec("hinv.ncpu", 0, "localhost")
Parse a "metric specification" into a pmMetricSpec struct. For more
information see the C function
description.
|