---

   pmwebapi    ( 3 )

---

PMAPI HOST SERVICES

The live performance collection facilities available from pmcd(1) can also be accessed through a REST API.

All requests are performed on the web server host by default, unless either a hostspec or context parameter is provided. hostname can be used in place of hostspec.

Context identifiers are used as a persistent way to refer to PMAPI contexts across related web requests. These contexts expire after a configurable period of disuse, and are either explicitly allocated using the /pmapi/context interface, or implicitly allocated using other interfaces.

The timeout interval is configurable at context creation time, and as such the polltime parameter can be used anywhere the hostspec is specified. It sets the context timeout in terms of length of inactive time. The unit for the timeout value is seconds and the default is 5.

To specify a specific existing context in any PMAPI web request, the endpoints can be accessed with either the context parameter or embedded in the endpoint URL itself, such as /pmapi/[number]/fetch.

GET /pmapi/context - pmNewContext(3) ┌────────────┬────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │polltimeout │ number │ Seconds of inactivity before closing context │ │client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────────┘ To create a context for live sampling, a web client can access any /pmapi URL (optionally using the hostspec or context parameter). If no context exists, a new one will be created for that web client, and its identifier returned for future accesses.

However, /pmapi/context is provided as a dedicated URL for applications wishing to explicitly create the contexts they use.

If successful, the server responds with a HTTP 200 (OK) code and JSON message body of the form:

$ curl -s http://localhost:44322/pmapi/context?hostspec=www.acme.com&polltime=500 | pmjson { "context": 348734, "source": "05af7f3eb840277fd3cfa91f90ef0067199743c", "hostspec": "www.acme.com", "labels": { "domainname": "acme.com", "groupid": 1000, "hostname": "www.acme.com", "machineid": "295b7623b6074cc8bdbda8bf96f6930a" "platform": "dev", "userid": 1000 } }

The context (a 32-bit unsigned decimal number) can then be used with all later requests.

In the case of a hostspec containing authentication information, such as a username, the server will follow the HTTP Basic Authentication protocol to ascertain necessary authentication details from the user, providing the client web application an opportunity to request these from the user.

GET /pmapi/metric - pmLookupDesc(3), pmLookupLabels(3), pmLookupName(3), pmLookupText(3) ┌────────────┬────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────────┤ │name │ string │ An individual metric name │ │names │ string │ Comma-separated list of metric names │ │pmid │ pmID │ Numeric or pmIDStr(3) metric identifier │ │pmids │ string │ Comma-separated numeric or pmIDStr(3) pmIDs │ │prefix │ string │ Metric namespace component as in PMNS(5) │ ├────────────┼────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────────┘ The metric endpoint provides detailed PMAPI metric metadata for one or more metrics. If no parameters are supplied, the response will be for all metrics found when traversing the entire Performance Metrics Name Space (PMNS).

The prefix parameter can be used to specify a subtree of the PMNS for traversal. Alternatively, a specific metric or comma- separated list of metrics can be specified using either name or names

The server response is a JSON document that provides metric metadata as an array.

$ curl -s http://localhost:44322/pmapi/metric?names=kernel.all.load,disk.all.read | pmjson { "context": 348734, "metrics": [ { "name": "kernel.all.load", "pmid": "60.2.0", "indom": "60.2", "type": "FLOAT", "sem": "instant", "units": "none", "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b", "source": "05af7f3eb840277fd3cfa91f90ef0067199743c", "labels": { "agent": "linux", "domainname": "acme.com", "groupid": 1000, "hostname": "www.acme.com", "platform": "dev", "userid": 1000 }, "text-oneline": "1, 5 and 15 minute load average" }, { "name": "disk.all.read", "pmid": "60.0.24", "type": "U64", "sem": "counter", "units": "count", "series": "d2b28c7f6dc0d69ffd21dba7ba955e78c37719b", "source": "05af7f3eb840277fd3cfa91f90ef0067199743c", "labels": { "agent": "linux", "domainname": "acme.com", "groupid": 1000, "hostname": "www.acme.com", "platform": "dev", "userid": 1000 }, "text-oneline": "total read operations, summed for all disks", "text-help": "Cumulative number of disk read operations [...]" } ] } Most of the fields are directly transcribed from the PMAPI calls for metric descriptors, labels and help text mentioned above and are exactly as would be observed using the pminfo(1) command with the -dlmstT options.

The semantics, type and units fields are as returned by pmTypeStr(3), pmUnitsStr(3) and pmSemStr(3).

GET /pmapi/fetch - pmFetch(3) ┌────────────┬────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────────┤ │delta │ string │ Sampling interval in pmParseInterval(3) form │ │name │ string │ An individual metric name │ │names │ string │ Comma-separated list of metric names │ │pmid │ pmID │ Numeric or pmIDStr(3) metric identifier │ │pmids │ string │ Comma-separated numeric or pmIDStr(3) pmIDs │ ├────────────┼────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────────┘ This request fetches (samples) current values for given metrics.

If any of the names or pmids provided are valid, the response is a JSON document that provides the values for all instances of the metrics, unless a instance profile has been set for the web context (see section on InDom profiles below).

$ curl -s http://localhost:44322/pmapi/fetch?names=kernel.all.load,disk.all.read | pmjson { "context": 348734, "timestamp": 1547483646.2147431, "values": [ { "pmid": "60.2.0", "name": "kernel.all.load", "instances:" [ { "instance": 1, "value": 0.1 }, { "instance": 5, "value": 0.17 }, { "instance": 15, "value": 0.22 } ] }, { "pmid":"60.0.24", "name":"disk.all.read", "instances:" [ { "instance": null, "value": 639231 } ] } ] } The response fields map directly to fields from the underlying pmFetch(3) sampling interface.

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.

In backward compatibility mode the timestamp is presented as a JSON map with second (sec) and microsecond (us) fields, instead of using the more compact floating point representation shown above.

GET /pmapi/children - pmGetChildren(3), pmGetChildrenStatus(3) ┌────────────┬────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────────┤ │prefix │ string │ Metric namespace component as in PMNS(5) │ ├────────────┼────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────────┘ The children endpoint provides iterative namespace traversal for a context. If no parameters are supplied, the response will describe the direct descendants of the Performance Metrics Name Space (PMNS) root.

The prefix parameter can be used to specify a subtree of the PMNS for traversal.

The server response is a JSON document that provides the set of leaf and non-leaf nodes below the given namespace node or root.

$ curl -s http://localhost:44322/pmapi/children?prefix=mem | pmjson { "context": 348734, "name": "mem", "leaf": [ "physmem", "freemem" ], "nonleaf": [ "util", "numa", "vmstat", "buddyinfo", "slabinfo", "zoneinfo", "ksm" ] }

GET /pmapi/indom - pmGetInDom(3), pmNameInDom(3), pmLookupInDom(3) ┌────────────┬─────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │iname │ string │ Comma-separated list of instance names │ │indom │ pmInDom │ Numeric or pmInDomStr(3) instance domain │ │instance │ number │ Comma-separated list of instance numbers │ │match │ string │ Pattern matching style (exact, glob or regex) │ │name │ string │ An individual metric name │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴─────────┴────────────────────────────────────────────────┘ This request lists the current instances of an instance domain. The instance domain is either specified directly (in numeric or string form) or indirectly, by association with the specified metric.

The request can be further qualified with a comma-separated list of the instances to report on, either by name or number, using the instance and iname parameters.

In the case of instance name qualifiers, these will be matched by exact string comparison by default. Alternatively, the match parameter can be used to specify that regular expression or glob pattern matching should be used instead.

The response is a JSON document that provides the instance domain metadata as an array.

$ curl -s http://localhost:44322/pmapi/indom?name=kernel.all.load | pmjson { "context": 348734, "indom": "60.2", "labels": { "domainname": "acme.com", "groupid": 1000, "hostname": "www.acme.com", "machineid": "295b7623b6074cc8bdbda8bf96f6930a" "platform": "dev", "userid": 1000 }, "instances": [ { "instance": 1, "name": "1 minute" "labels": { ... }, }, { "instance": 5, "name": "5 minute" "labels": { ... }, }, { "instance": 15, "name": "15 minute" "labels": { ... }, } ] }

GET /pmapi/profile - pmAddProfile(3), pmDelProfile(3) ┌────────────┬─────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │iname │ string │ Comma-separated list of instance names │ │indom │ pmInDom │ Numeric or pmInDomStr(3) instance domain │ │instance │ number │ Comma-separated list of instance numbers │ │expr │ string │ One of "add" or "del" (mandatory). │ │match │ string │ Pattern matching style (exact, glob or regex) │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴─────────┴────────────────────────────────────────────────┘ Some PMAPI operations can be performed with an active instance domain profile which restricts (filters) the set of resulting instances returned, as described on pmAddProfile(3).

$ curl -s http://localhost:44322/pmapi/profile?expr=add,indom=60.2,iname=1%20minute { "context": 348734, "success": true }

GET /pmapi/store - pmStore(3) ┌────────────┬────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────────┤ │iname │ string │ Comma-separated list of instance names │ │instance │ number │ Comma-separated list of instance numbers │ │name │ string │ An individual metric name │ │value │ (any) │ New value for the given metric instance(s) │ ├────────────┼────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────────┘ Some performance metrics allow their value to be modified, for example to re-initialize counters or to modify control variables.

This operation takes a single metric name to modify, and optionally specific instances. The mandatory value will be interpreted according to the type of the metric being modified.

If successful, the response from these requests is a JSON document of the form:

$ curl -s http://localhost:44322/pmapi/store?name=pmcd.control.timeout&value=10 { "context": 348734, "success": true }

GET /pmapi/derive: pmAddDerived(3) ┌────────────┬────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────────┤ │expr │ string │ Derived metric expression │ │name │ string │ New derived metric name │ ├────────────┼────────┼────────────────────────────────────────────────┤ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │context │ number │ Web context number (optional like hostspec) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────────┘ Create a new derived metric, as defined by the pmAddDerived(3) metric interface. Derived metrics are associated with the named context, or a new context is created and returned in the result.

This interface is one of the few that allows a POST to be used in place of a GET. In this case the HTTP POST request body may be used to provide one or more derived metrics specifications (all at once, across multiple lines, as a convenience).

$ curl -s http://localhost:44322/pmapi/derive?name=blkio.avgsz&expr=disk.all.blktotal/disk.all.total | pmjson { "context": 348734, "success": true }

$ curl -s http://localhost:44322/pmapi/fetch?name=blkio.avgsz&samples=2 | pmjson { "context": 348734, "timestamp": 1547483648.2147428, "values": [ { "pmid": "511.0.27", "name": "blkio.avgsz", "instances:" [ { "instance": null, "value": 9231 } ] } ] }

GET /pmapi/metrics: pmLookupDesc(3),pmLookupLabels(3), pmFetch(3) ┌────────────┬─────────┬────────────────────────────────────────────────┐ │Parameters │ Type │ Explanation │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │names │ string │ Comma-separated list of metric names │ │times │ boolean │ Append sample times (milliseconds since epoch) │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │context │ number │ Web context number (optional like hostspec) │ │hostspec │ string │ Host specification as described in PCPIntro(1) │ │polltimeout │ number │ Seconds of inactivity before context closed │ │client │ string │ Request identifier sent back with response │ └────────────┴─────────┴────────────────────────────────────────────────┘ This request is a subset of the style described in the ``OPEN METRICS'' section, allowing a web context identifier to be passed as a parameter. It is otherwise very similar in terms of parameters and response handling, please refer to the earlier section for details.