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 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.

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)

---