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. An Access-Control-Allow-Origin: * header is added to all JSON responses.
To create a new web context identifier, a web client invokes:
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 sudden 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.
The general form of the requests is as follows: /pmapi/NNNNN/OPERATION where
The general form of the requests is as follows:
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.
| PM_SEM_COUNTER "counter" |
|
| PM_SEM_INSTANT "instant" |
|
| PM_SEM_DISCRETE "discrete" |
|
The general form of the requests is as follows:
If any of the names/pmids are valid, 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.
The general form of the requests is as follows:
In addition, either query may be suffixed with:
The response is a JSON document that provides the metric metadata as an array. For example:
{ "indom":DDDD,
"instances": [
{ "instance":IIII, "name":"INAME" }
...
] }
The general form of these requests is as follows:
The general form of these requests is as follows:
In addition, either query may be suffixed with:
If successful, the response from these requests is a JSON document of the form:
{ "success" : true }
When enabled, pmwebd can emulate a subset of the graphite web-api to allow web applications like graphite and grafana to extract data from all archives under the configured -A directory. The graphite namespace is constructed from the PCP archives using a simple mapping that encodes the Cartesian product of archives, metrics, and instance-domain instances into dot-separated strings. Some metacharacter-quoting is employed to encode general strings into components. Only numeric PCP metrics are exposed; COUNTER semantic values are rate-converted.
|
|||||||||||||||
Since glob wildcarding is supported within metric name components, using them in the first component (an encoding of the archive name) is a good way to identify machines, or to match multiple archives spanning times of interest.
We list here only the broadest outline of the supported calls. pmwebd does not support every graphite web-api option, so many querystring parameters may be ignored. Arithmetic/statistical functions on metrics are not supported.
PCPIntro (1), PCPIntro (3), pmwebd (1), http://graphite.readthedocs.org/ and PMAPI (3)