Ubuntu Manpage: PMWEBAPI - introduction to the Performance Metrics Web Application Programming Interface

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.  An Access-Control-Allow-Origin: * header is added
       to all JSON responses.

CONTEXT CREATION: pmNewContext

       To create a new web context identifier, a web client invokes:

       /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/pass‐
              word.

       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.

CONTEXT CREATION: configurable permanent contexts

       In  addition,  permanent contexts may be created by pmwebd at initialization using its -h, -a, -L command
       line options, so that a set of fixed NNNNN numbers may be made available to web clients.

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, pmLookupText, pmTraversePMNS_r
The general form of the requests is as follows:

/pmapi/NNNNN/_metric
Traverse the entire Performance Metrics Name Space (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.

name A name for the metric as defined in the PMNS. If the PMNS contains multiple names associated with
the metric's Performance Metric Identifier (PMID), one of these will be returned via name, but
there is no way to determine which of the duplicate names this will be.

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.

If any of the names/pmids are valid, the response is a JSON document that provides the values for all re‐
quested 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 float‐
ing-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
The general form of these requests is as follows:

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

METRIC STORE: pmStore
The general form of these requests is as follows:

/pmapi/NNNN/_store?name=NAME&value=VALUE
Store a new value for given named metrics.

/pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
Store a new value for given performance metric identifier (PMID).

In addition, either query may be suffixed with:

&instance=IIII,JJJJ
Restrict store to given instance code numbers.

&iname=INAME1,INAME2
Restrict store to given instance names.

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

{ "success" : true }

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.

PROMETHEUS
Prometheus exporting of live metrics from a preexisting PMWEBAPI context is available:

The general form of the requests is:

/pmapi/NNNNN/metrics?target=NAME1,NAME2,...
Fetch current values for given named metrics.

For all numeric metrics with the given NAME prefixes, create a prometheus text export format giving their
current value and related metadata. The response has text/plain type rather than JSON, and is designed
to be ingested by a Prometheus server, or pcp's own pmdaprometheus.

The native PCP metric metadata (metric name, semantics and units) are first output with the # PCP prefix.
If the units string is empty, then none is output. The units metadata string may contain spaces and ex‐
tends to the end of the line. Prometheus metric types are heuristically inferred from PCP metric types,
and units/scales are converted to base seconds/bytes/count if possible, with a corresponding suffix added
to the metric name. PCP metric names are mapped so that . are exchanged with :. Instance domain in‐
stances are represented as Prometheus labels with quoted instance names.

# PCP proc.nprocs instant none
# HELP proc:nprocs instantaneous number of processes
# TYPE proc:nprocs gauge
proc:nprocs 7

# PCP kernel.pernode.cpu.intr counter millisec
# HELP kernel:pernode:cpu:intr_seconds_total total interrupt CPU time from /proc/stat for each node
# TYPE kernel:pernode:cpu:intr_seconds_total counter
kernel:pernode:cpu:intr_seconds_total{instance="node0"} 25603.540000000001

# PCP filesys.blocksize instant byte
# HELP filesys:blocksize_bytes Size of each block on mounted filesystem (Bytes)
# TYPE filesys:blocksize_bytes gauge
filesys:blocksize_bytes{instance="/dev/mapper/docker-253:0-83713-\
9a130460b46163fcf4443710db3159dea6bb5ec2aaca108515839a7a28c191ce"} 4096
filesys:blocksize_bytes{instance="/dev/mapper/VolGroup00-root17"} 4096

GRAPHITE