Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for pmwebapi (centos section 3)

PMWEBAPI(3)						     Library Functions Manual						       PMWEBAPI(3)

NAME
PMWEBAPI - introduction to the Performance Metrics Web Application Programming Interface
OVERVIEW
The PMWEBAPI interface is a binding of a subset of the PMAPI to the web. It uses HTTP as transport, REST as organizational style for request/parameter encoding (the GET and POST methods are interchangeable), and JSON as response encoding. A context identifier is used as a persistent way to refer to PMAPI contexts across related web requests. These context identifiers expire after a configurable period of disuse. Errors generally result in HTTP-level error responses.
CONTEXT CREATION
: pmNewContext To create a new web context identifier, a web client invokes: /pmapi/context?local=ANYTHING Creates a PM_CONTEXT_LOCAL PMAPI context. /pmapi/context?hostname=STRING /pmapi/context?hostspec=STRING Creates a PM_CONTEXT_HOST PMAPI context with the given host name and/or extended specification. If the host specification contains a userid/password combination, then the corresponding pmapi context operations will require HTTP Basic authentication credentials with matching userid/password. /pmapi/context?archivefile=ARCHIVE Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file name. In addition, the web client may add the parameter &polltimeout=MMMM for a maximum interval (in seconds) between expected accesses to the given context. This value is limited by pmwebd configuration, and is a courtesy to allow pmwebd to free up memory earlier in case of sud- den web application shutdown. If successful, the response from these requests is a JSON document of the form: { "context" : NNNNN } The number (a 32-bit unsigned decimal) is then used in all later operations.
PMAPI OPERATIONS
The general form of the requests is as follows: /pmapi/NNNNN/OPERATION where /pmapi is the fixed prefix for all PMWEBAPI operations, NNNNN is a PMWEBAPI context number returned from a context-creation call, or assigned permanently at pmwebd startup, and OPERATION?PARAM1=VALUE2&PARAM2=VALUE2 identifies the operation and its URL-encoded parameters. Some parameters may be optional. METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r The general form of the requests is as follows: /pmapi/NNNNN/_metric Traverse the entire PMNS. /pmapi/NNNNN/_metric?prefix=NAME Traverse the subtree of PMNS with the prefix NAME. The response is a JSON document that provides the metric metadata as an array. For example: { "metrics": [ { "name":"foo.bar", "pmID":PPPP, "indom":DDDD, "type":"32", "sem":"instant", "units":"MHz", "text-oneline":"foo bar", "text-help":"blah blah blah" }, { "name":"foo.bar2", ... } ... ] } Most of the fields are self-explanatory. PPPP the PMID DDDD the instance domain type from pmTypeStr units from pmUnitsStr sem an abbreviation of the metric semantic: PM_SEM_COUNTER "counter" PM_SEM_INSTANT "instant" PM_SEM_DISCRETE "discrete" METRIC VALUE: pmFetch The general form of the requests is as follows: /pmapi/NNNNN/_fetch?names=NAME1,NAME2 Fetch current values for given named metrics. /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2 Fetch current values for given PMIDs. The response is a JSON document that provides the values for all requested metrics, for all their instances. { "timestamp": { "s":SEC, "us":USEC }, "values": [ { "pmid":PPPP1, "name":"NAME1", "instances:" [ { "instance":IIII1, "value":VALUE1 } { "instance":IIII2, "value":VALUE2 } ... ] }, { "pmid":PPPP2, "name":"NAME2", ... } ... ] } Most of the fields are self-explanatory. Numeric metric types are represented as JSON integer or floating-point values. Strings are passed verbatim, except that non-ASCII values are replaced with a Unicode 0xFFFD REPLACEMENT CHARACTER code. Event type metrics are not currently supported. INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom The general form of the requests is as follows: /pmapi/NNNN/_indom?indom=DDDD List instances of the given instance domain. /pmapi/NNNN/_indom?name=NAME List instances of the instance domain belonging to the named metric. In addition, either query may be suffixed with: &instance=IIII,JJJJ Restrict listings to given instance code numbers. &iname=INAME1,INAME2 Restrict listings to given instance names. The response is a JSON document that provides the metric metadata as an array. For example: { "indom":DDDD, "instances": [ { "instance":IIII, "name":"INAME" } ... ] } INSTANCE PROFILE: pmAddProfile, pmDelProfile /pmapi/NNNN/_profile_reset? These are not currently supported. /pmapi/NNNN/_profile_reset?indom=DDDD These are not currently supported. /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ These are not currently supported. /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ These are not currently supported. /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ These are not currently supported. /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2 These are not currently supported. DERIVED METRICS: pmRegisterDerived /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION These are not currently supported. CONTEXT COPY: pmDupContext /pmapi/NNNNN/copy These are not currently supported. CONTEXT CLOSE: pmDestroyContext /pmapi/NNNNN/destroy This is not likely to be supported, as it is destructive and would offer a tempting target to brute-force attackers. Instead, the pmwebd timeout is used to automatically free unused contexts.
SEE ALSO
PCPIntro(1), PCPIntro(3), pmwebd(3), and PMAPI(3) Performance Co-Pilot PCP PMWEBAPI(3)