|
NAME | OVERVIEW | CONTEXT CREATION: pmNewContext | CONTEXT CREATION: configurable permanent contexts | PMAPI OPERATIONS | GRAPHITE | SEE ALSO | COLOPHON |
|
PMWEBAPI(3) Library Functions Manual PMWEBAPI(3)
PMWEBAPI - introduction to the Performance Metrics Web Application
Programming Interface
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:
/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.
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 op‐
erations.
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.
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 Perfor‐
mance Metric Identifier (PMID), one of these will be returned
via name, but there is no way to determine which of the dupli‐
cate 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 requested metrics, for all their in‐
stances.
{ "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
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. In‐
stead, the pmwebd timeout is used to automatically free unused
contexts.
PROMETHEUS
Prometheus exporting of live metrics from a preexisting PMWEBAPI con‐
text 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 pm‐
daprometheus.
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 extends 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 correspond‐
ing suffix added to the metric name. PCP metric names are mapped so
that . are exchanged with :. Instance domain instances are repre‐
sented 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
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.
┌─────────┬────────┬───────────────────────────────────────────────────────┐
│position │ number │ purpose │
├─────────┼────────┼───────────────────────────────────────────────────────┤
│ 1 │ 1 │ encoded pathname of the archive .meta file (default), │
│ │ │ or canonicalized archive hostname (-J mode) │
│ 2 │ N │ the N components of the pcp metric name │
│ N+2 │ 1 │ instance name of the metric (if any) │
└─────────┴────────┴───────────────────────────────────────────────────────┘
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.
/graphite/render?format=json&target=FOO&from=TIME&until=TIME
Return a series of values of the given metrics, between the
two times, sampled every 60 seconds.
/graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
Same, with a slightly different result encoding.
/graphite/render?format=png&target=FOO&from=TIME&until=TIME&....
Same, but render the curves into a PNG image file. Several
color- and rendering-control-related parameters are supported.
/graphite/metrics/find?query=FOO.BAR.*
Provide incremental metric-tree traversal using wildcards.
/graphite/graphlot/findmetric?query=FOO+BAR
Search through metrics with space-separated regular
expressions.
/graphite/browser/search?q=FOO+BAR
Same, with a slightly different result encoding.
PCPIntro(1), PCPIntro(3), pmwebd(1), http://graphite.readthedocs.org/
and PMAPI(3)
This page is part of the PCP (Performance Co-Pilot) project.
Information about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2018-02-02. (At that time, the date of the most recent commit that
was found in the repository was 2018-02-02.) If you discover any
rendering problems in this HTML version of the page, or you believe
there is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
Performance Co-Pilot PCP PMWEBAPI(3)
Pages that refer to this page: pmjson(1), pmwebd(1), pmhttpnewclient(3)
|
HTML rendering created 2018-02-02 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.
|
|