'\" t
.\"
.\" Copyright (c) 2013-2022,2025 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMWEBAPI 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3PMWEBAPI\f1 \- introduction to the Performance Metrics Web Application Programming Interface
.SH HTTP SYNOPSIS
.ft 3
.ad l
.hy 0
GET /metrics
.br
GET /series/...
.br
GET /search/...
.br
GET /pmapi/...
.br
POST /logger/...
.hy
.ad
.ft 1
.SH C SYNOPSIS
.ft 3
.ad l
.hy 0
#include <pcp/pmwebapi.h>
.sp
.ft 1
\& ... assorted routines ...
.ft 3
.sp
cc ... \-lpcp_web \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
.de SAMPLE
.PP
.RS 2n
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..
The PMWEBAPI is a collection of interfaces providing
Performance Co-Pilot services for web applications.
It consists of APIs for web applications querying
and analysing both live and historical performance
data, as well as APIs used by web servers.
.PP
The usual HTTP URL-encoded optional parameter rules
apply and PMWEBAPI REST requests always follow the
convention:
.P
\fI/api/endpoint\fR?\fIparameter1\fR=\fIvalue1\fR&\fIparameter2\fR=\fIvalue2\fR
.PP
Examples in all following sections use the
.BR curl (1)
command line utility with a local
.BR pmproxy (1)
server listening on port 44322 (default port).
The
.BR pmjson (1)
utility is used to neatly format any JSON output,
as opposed to the compact (minimal whitespace) form
provided by default.
The examples in the scalable time series section use
historical data recorded by the
.BR pmlogger (1)
service, in conjunction with a local key-value server.
.SH OPEN METRICS AND OPEN TELEMETRY
Exporting of live performance metrics in either Open Metrics (\c
.IR https://openmetrics.io )
or Open Telemetry (\c
.IR https://opentelemetry.io )
formats is available.
.PP
All requests are performed on the web server host by default,
unless a
.I hostspec
parameter is provided.
.SS GET /metrics
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
names	string	T{
Comma-separated list of metric names
T}
filter	string	T{
Comma-separated list of excluded metric names
T}
match	string	T{
Pattern matching style (exact, glob or regex)
T}
times	boolean	T{
Append sample times (milliseconds since epoch)
T}
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
.TE
.P
Fetches current values and metadata for all metrics, or only
metrics indicated by a comma-separated list of
.IR names .
.PP
For all numeric metrics with the given NAME prefixes, create
an open text export format giving their current value and
related metadata.
.PP
Choice of output format is selected using the HTTP
.I Accept
header.
With no header, the default response format is Open Metrics
.IR text .
Using the header with value
.I application/json
switches the response to the Open Telemetry JSON format.
.PP
In Open Telemetry response mode, sample timestamps are always
included and are reported using nanosecond precision.
.SAMPLE
$ curl -H Accept:application/json -s http://localhost:44322/metrics?names=disk.dev,filesys | pmjson
{
    "resourceMetrics": [
        {
            "resource": {
                "attributes": [ ... ]
            },
            "scopeMetrics": [
                {
                    "scope": { ... },
                    "metrics": [
                        {
                            "name": "disk.dev.total.bytes",
                            "description": "per-disk count of total bytes read and written",
                            "unit": "KiBy",
                            "sum": {
                                "aggregationTemporality": "CUMULATIVE",
                                "isMonotonic": true,
                                "dataPoints": [
                                    {
                                        "attributes": [ ... ]
                                        "timeUnixNano": "1753934255798173",
                                        "asInt": "68927569"
                                    }
                                ]
                            }
                        },
                        ...
.ESAMPLE
.PP
In Open Metrics response mode, the native PCP metric metadata
(metric name, type, indom, semantics and units) is first output
for each metric with
.B # PCP
prefix.
The metadata reported is of the form described on
.BR pmTypeStr (3),
.BR pmInDomStr (3),
.BR pmSemStr (3)
and
.BR pmUnitsStr (3)
respectively.
If the
.BR pmUnitsStr (3)
units string is empty, then
.B none
is output.
The units metadata string may contain spaces and extends to
the end of the line.
.PP
PCP metric names are mapped so that the \fB.\fP separators
are exchanged with \fB_\fP (':' in back-compatibility mode,
where "# PCP" is the identifying line suffix).
Both metric labels and instances are represented as Open Metrics
labels, with external instance names being quoted and the
flattened PCP label hierarchy being presented with each value.
.PP
When metric
.I names
pattern matching is performed using the
.I filter
option, the default mode is glob-based matching.
The
.I match
option can be used to instead request regex-based or
exact-match metric filtering.
.SAMPLE
$ curl -s http://localhost:44322/metrics?names=proc.nprocs,kernel.pernode.cpu.intr,filesys.blocksize

# PCP5 proc.nprocs 3.8.99 u32 PM_INDOM_NULL instant none
# HELP proc_nprocs instantaneous number of processes
# TYPE proc_nprocs gauge
proc_nprocs {hostname="app1"} 7

# PCP5 kernel.pernode.cpu.intr 60.0.66 u64 60.19 counter millisec
# HELP kernel_pernode_cpu_intr total interrupt CPU [...]
# TYPE kernel_pernode_cpu_intr counter
kernel_pernode_cpu_intr{hostname="app1",instname="node0"} 25603

# PCP5 filesys.blocksize 60.5.9 u32 60.5 instant byte
# HELP filesys_blocksize Size of each block on mounted file[...]
# TYPE filesys_blocksize gauge
filesys_blocksize{hostname="app1",instname="/dev/sda1"} 4096
filesys_blocksize{hostname="app1",instname="/dev/sda2"} 4096
.ESAMPLE
.SH SCALABLE TIME SERIES
The fast, scalable time series query capabilities
provided by the
.BR pmseries (1)
command are also available through a REST API.
These queries provide access to performance data
(metric metadata and values) from multiple hosts
simultaneously, and in a fashion suited to efficient
retrieval by any number of web applications.
.PP
All requests in this group can be accompanied by an optional
.IR client
parameter.
The value passed in the request will be sent back in the
response \- all responses will be in JSON object form in
this case, with top level "client" and "result" fields.
.PP
REST API clients can optionally submit an URL-encoded query string
in the body of the HTTP request unless otherwise noted.
In this case the POST method must be used instead of the GET method.
.SS GET \fI/series/ping\fR
Simple liveness test for clients to check whether the server is up
and supports the \fI/series\fR API.
.SS GET \fI/series/query\fR \- \fBpmSeriesQuery\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
expr	string	Query string in \f(CBpmseries\fR(1) format
client	string	Request identifier sent back with response
.TE
.PP
Performs a time series query for either matching identifiers,
or matching identifiers with series of time-stamped values.
.PP
The query is in the format described in
.BR pmseries (1)
and is passed to the server via either the
.I expr
parameter (HTTP GET) or via the message body (HTTP POST).
.PP
When querying for time series matches only, no time window
options are specified and matching series identifiers are
returned in a JSON array.
.SAMPLE
$ curl -s 'http://localhost:44322/series/query?expr=disk.dev.read*' | pmjson
[
  "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
  "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
  "605fc77742cd0317597291329561ac4e50c0dd12"
]
.ESAMPLE
.PP
When querying for time series values as well, a time
window must be specified as part of the query string.
The simplest form is to just request the most recent
sample.
.SAMPLE
$ curl -s 'http://localhost:44322/series/query?expr=disk.dev.read*[samples:1]' | pmjson
[
  {
    "series": "9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
    "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4",
    "timestamp": 1547483646.2147431,
    "value": "12499"
  }, {
    "series": "ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
    "instance": "6b08b489ba56cae7f0d4c3795d8b757506a2901c",
    "timestamp": 1547485701.7431218,
    "value": "1118623"
  }, {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4",
    "timestamp": 1547483646.2147431,
    "value": "71661"
  }
]
.ESAMPLE
.SS GET \fI/series/values\fR \- \fBpmSeriesValues\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
series	string	Comma-separated list of series identifiers
client	string	Request identifier sent back with response
_
samples	number	Count of samples to return
interval	string	Time between successive samples
start	string	Sample window start time
finish	string	Sample window end time
offset	string	Sample window offset
align	string	Sample time alignment
zone	string	Time window timezone
.TE
.P
Performs values retrievals for one or more time series
identifiers.
The JSON response contains the same information as the
\fBpmseries\fR \-\fBq\fR/\-\-\fBquery\fR option using
any of the time window parameters described on
.BR pmseries (1).
If no time window parameters are specified, the single
most recent value observed is retrieved.
.SAMPLE
$ curl -s http://localhost:44322/series/values?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
  {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "timestamp": 1317633022959.959241041,
    "value": "71660"
  }
]
.ESAMPLE
.SS GET \fI/series/descs\fR \- \fBpmSeriesDescs\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
series	string	Comma-separated list of series identifiers
client	string	Request identifier sent back with response
.TE
.P
Performs a descriptor lookup for one or more time series
identifiers.
The JSON response contains the same information as the
\fBpmseries\fR \-\fBd\fR/\-\-\fBdesc\fR option.
.SAMPLE
$ curl -s http://localhost:44322/series/descs?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
  {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "source": "f5ca7481da8c038325d15612bb1c6473ce1ef16f",
    "pmid": "60.0.4",
    "indom": "60.1",
    "semantics": "counter",
    "type": "u32",
    "units": "count",
  }
]
.SS GET \fI/series/labels\fR \- \fBpmSeriesLabels\fR(3), \fBpmSeriesLabelValues\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
series	string	Comma-separated list of series identifiers
match	string	Glob pattern string to match on all labels
name	string	Find all known label values for given name
names	string	Comma-separated list of label names
client	string	Request identifier sent back with response
.TE
.P
This command operates in one of three modes.
It can perform a label set lookup for one or more time
series identifiers, when given the
.I series
parameter).
It can produce a list of all known label names, in the
absence of
.IR name ,
.I names
or
.I series
parameters.
The JSON responses for these modes contains the same information
as the \fBpmseries\fR \-\fBl\fR/\-\-\fBlabels\fR option.
.P
Alternatively, it can produce a list of all known label
values for a given label
.I name
or
.IR names .
The JSON response for this mode contains the same information
as the \fBpmseries\fR \-\fBv\fR/\-\-\fBvalues\fR option.
.SAMPLE
$ curl -s http://localhost:44322/series/labels?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
  {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "labels": {
      "agent": "linux",
      "domainname": "acme.com",
      "groupid": 1000,
      "hostname": "www.acme.com",
      "latitude": -25.28496,
      "longitude": 152.87886,
      "machineid": "295b16e3b6074cc8bdbda8bf96f6930a",
      "platform": "dev",
      "userid": 1000
    }
  }
]
.ESAMPLE
.P
Alternatively, with no
.IR name ,
.I names
or
.I series
parameters, return the list of all known label names.
.SAMPLE
$ curl -s http://localhost:44322/series/labels | pmjson
[
    "agent",
    "appversion",
    "domainname",
    "groupid",
    "hostname",
    "jobid",
    "latitude",
    "longitude",
    "machineid",
    "platform",
    "userid"
]
.ESAMPLE
.P
Use the
.I name
or
.I names
parameters to find all possible label values for the given name(s).
.SAMPLE
$ curl -s http://localhost:44322/series/labels?names=hostname,domainname | pmjson
{
    "hostname": [ "app", "nas" ],
    "domainname": [ "acme.com" ]
}
.ESAMPLE
.SS GET \fI/series/metrics\fR \- \fBpmSeriesMetrics\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
series	string	Comma-separated list of series identifiers
match	string	Glob pattern string to match on all names
client	string	Request identifier sent back with response
.TE
.P
Performs a metric name lookup for one or more time series
identifiers.
The JSON response contains the same information as the
\fBpmseries\fR \-\fBm\fR/\-\-\fBmetrics\fR option.
.SAMPLE
$ curl -s http://localhost:44322/series/metrics?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
  {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "name": "disk.dev.read_bytes"
  }
]
.ESAMPLE
.P
Alternatively, with no
.I series
argument, this request will return the list of all known
metric names.
.SAMPLE
$ curl -s http://localhost:44322/series/metrics | pmjson
[
    "disk.dev.read",
    "disk.dev.read_bytes",
    "disk.dev.read_merge",
    "kernel.all.load",
    "kernel.all.pswitch",
    ...
]
.ESAMPLE
.SS GET \fI/series/sources\fR \- \fBpmSeriesSources\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
series	string	Comma-separated list of source identifiers
match	string	Glob pattern string to match on all sources
client	string	Request identifier sent back with response
.TE
.P
Performs a lookup for one or more time series sources,
returning an array of all PMAPI context names used to
access the time series from that source.
The JSON response contains the same information as the
\fBpmseries\fR \-\fBS\fR/\-\-\fBsource\fR option.
.SAMPLE
$ curl -s http://localhost:44322/series/sources?source=2cd6a38f9339f2dd1f0b4775bda89a9e7244def6 | pmjson
[
  {
    "source": "2cd6a38f9339f2dd1f0b4775bda89a9e7244def6",
    "context": [
      "/var/log/pcp/pmlogger/acme",
      "www.acme.com"
    ]
  }
]
.ESAMPLE
.SS GET \fI/series/instances\fR \- \fBpmSeriesInstances\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | lx.
Parameters	Type	Explanation
_
series	string	T{
.hy 0
.ad l
Comma-separated list of series identifiers
T}
match	string	T{
.hy 0
.ad l
Glob pattern string to match on all instances
T}
client	string	T{
.hy 0
.ad l
Request identifier sent back with response
T}
.TE
.P
Provide instance identifiers and names for one or more
time series identifiers.
The JSON response contains the same information as the
\fBpmseries\fR \-\fBi\fR/\-\-\fBinstance\fR option.
.SAMPLE
$ curl -s http://localhost:44322/series/instances?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
  {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "source": "97261ac7742cd4e50c0d03175913295d12605fc7",
    "instance": "c3795d8b757506a2901c6b08b489ba56cae7f0d4"
    "id": 1,
    "name": "sda",
  }, {
    "series": "605fc77742cd0317597291329561ac4e50c0dd12",
    "source": "97261ac7742cd4e50c0d03175913295d12605fc7",
    "instance": "57506a2901c6b08b489ba56cae7f0d4c3795d8b7"
    "id": 2,
    "name": "sdb",
  }
]
.ESAMPLE
.P
Alternatively, with no
.I series
argument, this request will return the list of all known
instance names.
.SAMPLE
$ curl -s http://localhost:44322/series/instances | pmjson
[
    "1 minute",
    "5 minute",
    "15 minute",
    "cpu0",
    "cpu1",
    "cpu2",
    "cpu3",
    "node0",
    "node1",
    "sda",
    "sdb",
    ...
]
.ESAMPLE
.SS GET \fI/series/load\fR \- \fBpmSeriesLoad\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
expr	string	Source load string in \f(CBpmseries\fR(1) format
client	string	Request identifier sent back with response
.TE
.PP
Load time series performance data from the specified source
into the key-value server cache.
This request is equivalent to the \fBpmseries\fR \-\fBl\fR/\-\-\fBload\fR
option.
.SAMPLE
$ curl -s http://localhost:44322/series/load?expr={source.name:"/var/log/pcp/pmlogger/acme"}
{
  "success": true
}
.ESAMPLE
.SH FULL TEXT SEARCH
The full text search capabilities
provided by the
.BR pmsearch (1)
command are also available through a REST API.
These queries provide access to an index over performance
metric names, instances, instance domains and help text,
suitable for a metric search engine, and in a fashion suited
to efficient querying by any number of web applications.
.PP
In order to use this functionality, the optional
.I ValkeySearch
module must be loaded in the key-value server at the time
.B pmproxy
is started, such that metrics, instances and help text it
discovers can be automatically indexed.

.SS GET \fI/search/text\fR \- \fBpmSearchTextQuery\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
query	string	Query string in \f(CBpmsearch\fR(1) format
highlight	fields	Include matching markup in response fields
offset	number	Result offset cursor for pagination
limit	number	Maximum results to include in response
field	fields	Queried fields (defaults to all)
return	fields	Fields to actually return (defaults to all)
type	types	Entity types to filter (defaults to all)
.TE
.PP
Performs a text search query across metrics and instance
domains \- all forms of names and help texts.
.PP
The mandatory search string is further described in
.BR pmsearch (1)
and is passed to the server via the
.I query
parameter (HTTP GET).
.SAMPLE
$ curl -s http://localhost:44322/search/text?query=halt | pmjson
{
  "total": 2,
  "offset": 0,
  "limit": 10,
  "elapsed": 0.000504,
  "results": [
    {
      "name": "kvm.halt_exits",
      "type": "metric",
      "indom": "95.0.4",
      "oneline": "Number of guest exits due to halt calls.",
      "helptext": "This type of exit is usually seen when a guest is idle."
    },
    {
      "name": "kvm.halt_wakeup",
      "type": "metric",
      "indom": "95.0.6",
      "oneline": "Number of wakeups from a halt.",
    }
  ]
}
.ESAMPLE
.PP
The available search entity
.I types
are
.IR metric ,
.IR indom
and
.IR instance .
Query parameters
.IR highlight
and
.IR field
take
.IR name ,
.IR oneline
and
.IR helptext .
.PP
Query parameter
.IR return
takes
.IR name ,
.IR type ,
.IR oneline ,
.IR helptext ,
.IR indom .
There is typically both a name and help text associated with
metrics. Contents of these are then matched against
.IR query .
An instance domain has help text and a numeric identifier,
while instances have a name only (which can be searched).
.SS GET \fI/search/suggest\fR \- \fBpmSearchTextSuggest\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
query	string	Search query for search engine
limit	number	Max results to include in response
.TE
.PP
Provides search query suggestions, that is, metric and instance names.
.PP
The mandatory search string is further described in
.BR pmsearch (1)
and is passed to the server via the
.I query
parameter (HTTP GET).
.SAMPLE
$ curl -s http://localhost:44322/search/suggest?query=disk&limit=4 | pmjson
[
    "disk.all.avactive",
    "disk.all.aveq",
    "disk.all.blkread",
    "disk.all.blktotal"
]
.ESAMPLE
.SS GET \fI/search/indom\fR \- \fBpmSearchTextInDom\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
query	string	Target indom for search engine
offset	number	Result offset cursor for pagination
limit	number	M results to include in response
.TE
.PP
Provides all entities (instances, metrics) related to indom, including itself, that is passed to the server via the
.I query
parameter.
.SS GET \fI/search/info\fR \- \fBpmSearchInfo\fR(3)
Provides metrics relating to operation of the search engine,
in particular showing document and text record counts.
.SAMPLE
$ curl -s http://localhost:44322/search/info | pmjson
{
    "docs": 1589,
    "terms": 3855,
    "records": 116831,
    "records_per_doc_avg": 73.52,
    "bytes_per_record_avg": 6.36,
    "inverted_sz_mb": 0.71,
    "inverted_cap_mb": 0.00,
    "inverted_cap_ovh": 0.00,
    "skip_index_size_mb": 0.00,
    "score_index_size_mb": 0.00,
    "offsets_per_term_avg": 9.41,
    "offset_bits_per_record_avg": 8.00
}
.ESAMPLE
.SH PMAPI HOST SERVICES
The live performance collection facilities available from
.BR pmcd (1)
can also be accessed through a REST API.
.PP
All requests are performed on the web server host by default,
unless either a
.I hostspec
or
.I context
parameter is provided.
.I hostname
can be used in place of
.IR hostspec .
.PP
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
.I /pmapi/context
interface, or implicitly allocated using other interfaces.
.PP
The timeout interval is configurable at context creation time,
and as such the
.I polltimeout
parameter can be used anywhere the
.I 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.
.PP
To specify a specific existing context in any PMAPI web request,
the endpoints can be accessed with either the
.I context
parameter or embedded in the endpoint URL itself, such as
.BR /pmapi/[number]/fetch .
.SS GET \fI/pmapi/context\fR \- \fBpmNewContext\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
polltimeout	number	T{
Seconds of inactivity before closing context
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
To create a context for live sampling, a web client can access any
.I /pmapi
URL (optionally using the
.I hostspec
or
.I context
parameter).
If no context exists, a new one will be created for that web
client, and its identifier returned for future accesses.
.PP
However,
.I /pmapi/context
is provided as a dedicated URL for applications wishing to
explicitly create the contexts they use.
.PP
If successful, the server responds with a HTTP 200 (OK) code
and JSON message body of the form:
.SAMPLE
$ curl -s http://localhost:44322/pmapi/context?hostspec=www.acme.com&polltimeout=0.5 | 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
  }
}
.ESAMPLE
.PP
The context (a 32-bit unsigned decimal number) can then be
used with all later requests.
.PP
In the case of a
.I 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.
.SS GET \fI/pmapi/metric\fR \- \fBpmLookupDesc\fR(3), \fBpmLookupLabels\fR(3), \fBpmLookupName\fR(3), \fBpmLookupText\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
name	string	T{
An individual metric name
T}
names	string	T{
Comma-separated list of metric names
T}
pmid	pmID	T{
Numeric or \f(CBpmIDStr\fR(3) metric identifier
T}
pmids	string	T{
Comma-separated numeric or \f(CBpmIDStr\fR(3) pmIDs
T}
prefix	string	T{
Metric namespace component as in \f(CBPMNS\fR(5)
T}
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
The
.I 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).
.PP
The
.I 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
.I name
or
.I names
.PP
The server response is a JSON document that provides metric
metadata as an array.
.SAMPLE
$ 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 [...]"
    }
  ]
}
.ESAMPLE
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
.BR pminfo (1)
command with the \-\fBdlmstT\fR options.
.PP
The semantics, type and units fields are as returned by
.BR pmTypeStr (3),
.BR pmUnitsStr (3)
and
.BR pmSemStr (3).
.SS GET \fI/pmapi/fetch\fR \- \fBpmFetch\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
delta	string	T{
Sampling interval in \f(CBpmParseInterval\fR(3) form
T}
name	string	T{
An individual metric name
T}
names	string	T{
Comma-separated list of metric names
T}
pmid	pmID	T{
Numeric or \f(CBpmIDStr\fR(3) metric identifier
T}
pmids	string	T{
Comma-separated numeric or \f(CBpmIDStr\fR(3) pmIDs
T}
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
This request fetches (samples) current values for given metrics.
.PP
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).
.SAMPLE
$ 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 }
      ]
    }
  ]
}
.ESAMPLE
The response fields map directly to fields from the underlying
.BR pmFetch (3)
sampling interface.
.PP
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.
.PP
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.
.SS GET \fI/pmapi/children\fR \- \fBpmGetChildren\fR(3), \fBpmGetChildrenStatus\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
prefix	string	T{
Metric namespace component as in \f(CBPMNS\fR(5)
T}
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
The
.I 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.
.PP
The
.I prefix
parameter can be used to specify a subtree of the PMNS for
traversal.
.PP
The server response is a JSON document that provides the set
of leaf and non-leaf nodes below the given namespace node or
root.
.SAMPLE
$ 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"
  ]
}
.ESAMPLE
.SS GET \fI/pmapi/indom\fR \- \fBpmGetInDom\fR(3), \fBpmNameInDom\fR(3), \fBpmLookupInDom\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
iname	string	T{
Comma-separated list of instance names
T}
indom	pmInDom	T{
Numeric or \f(CBpmInDomStr\fR(3) instance domain
T}
instance	number	T{
Comma-separated list of instance numbers
T}
match	string	T{
Pattern matching style (exact, glob or regex)
T}
name	string	T{
An individual metric name
T}
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
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.
.PP
The request can be further qualified with a comma-separated list
of the instances to report on, either by name or number, using the
.I instance
and
.I iname
parameters.
.PP
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.
.PP
The response is a JSON document that provides the instance domain
metadata as an array.
.SAMPLE
$ 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": { ...  },
    }
  ]
}
.ESAMPLE
.SS GET \fI/pmapi/profile\fR \- \fBpmAddProfile\fR(3), \fBpmDelProfile\fR(3)
.TS
box,center;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
iname	string	T{
Comma-separated list of instance names
T}
indom	pmInDom	T{
Numeric or \f(CBpmInDomStr\fR(3) instance domain
T}
instance	number	T{
Comma-separated list of instance numbers
T}
expr	string	T{
One of "add" or "del" (mandatory).
T}
match	string	T{
Pattern matching style (exact, glob or regex)
T}
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
Some PMAPI operations can be performed with an active instance
domain profile which restricts (filters) the set of resulting
instances returned, as described on
.BR pmAddProfile (3).
.SAMPLE
$ curl -s http://localhost:44322/pmapi/profile?expr=add,indom=60.2,iname=1%20minute
{ "context": 348734, "success": true }
.ESAMPLE
.SS GET \fI/pmapi/store\fR \- \fBpmStore\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
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	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
Some performance metrics allow their value to be modified,
for example to re-initialize counters or to modify control
variables.
.PP
This operation takes a single metric
.I name
to modify, and optionally
specific
.IR instance s.
The mandatory
.I value
will be interpreted according to the type of the metric
being modified.
.PP
If successful, the response from these requests is a JSON document of the form:
.SAMPLE
$ curl -s http://localhost:44322/pmapi/store?name=pmcd.control.timeout&value=10
{
  "context": 348734,
  "success": true
}
.ESAMPLE
.SS GET \fI/pmapi/derive\fR: \fBpmAddDerived\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
expr	string	Derived metric expression
name	string	New derived metric name
_
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
context	number	T{
Web context number (optional like hostspec)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
Create a new derived metric, as defined by the
.BR pmAddDerived (3)
metric interface.
Derived metrics are associated with the named context, or a new
context is created and returned in the result.
.PP
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).
.SAMPLE
$ 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
        }
      ]
    }
  ]
}
.ESAMPLE
.SS GET \fI/pmapi/metrics\fR: \fBpmLookupDesc\fR(3),\fBpmLookupLabels\fR(3), \fBpmFetch\fR(3)
.TS
box;
c | c | cw(2.4i)
lf(CR) | l | l.
Parameters	Type	Explanation
_
names	string	T{
Comma-separated list of metric names
T}
times	boolean	T{
Append sample times (milliseconds since epoch)
T}
_
context	number	T{
Web context number (optional like hostspec)
T}
hostspec	string	T{
Host specification as described in \f(CBPCPIntro\fR(1)
T}
polltimeout	number	T{
Seconds of inactivity before context closed
T}
client	string	T{
Request identifier sent back with response
T}
.TE
.P
This request is a subset of the style described in the
``OPEN METRICS AND OPEN TELEMETRY'' 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.
.SH ARCHIVE WEBHOOK \- \fBLOGARCHIVE\fR(5)
Remote archive push functionality is available via the
.BR pmlogger (1)
and
.BR pmlogpush (1)
utilities.
This is achieved through a series of HTTP POST operations to
the API endpoints described here.
.PP
All requests in this group can be accompanied by an optional
.IR client
parameter.
The value passed in the request will be sent back in the
response \- all responses are in JSON object form and will
include an additional top level "client" field.
.SS GET \fI/logger/ping\fR
Basic liveness test for clients to check whether the server is up
and supports the \fI/logger\fR API.
.SS POST \fI/logger/label\fR
The body of this API is the machine-agnostic binary (on-disk)
representation of a PCP archive label as described in
.BR LOGARCHIVE (5).
Either version 2 and 3 are accepted, and the
.I volume
field of this stucture will be ignored \- one API call suffices
for all of the volumes of an archive,
.B pmproxy
ensures correct content is written for each.
.P
This API returns a numeric token (LOGID) that must be used in all
subsequent API interactions for this archive as described below.
.SS POST \fI/logger/meta/LOGID\fR
The request body contains metadata file records as described in
.BR LOGARCHIVE .
.SS POST \fI/logger/index/LOGID\fR
The request body contains temporal index records as described in
.BR LOGARCHIVE .
.SS POST \fI/logger/volume/VOLID/LOGID\fR
The request body contains timestamped metric value samples, as
described in
.BR LOGARCHIVE .
The numeric volume (VOLID) to which these records is to be
written is a mandatory part of the API endpoint.
.SH NOTES
For the REST APIs, errors generally result in HTTP-level
error responses.
Wherever possible, any PMAPI error string will also be
provided in a message along with the response.
.PP
All responses will be returned using HTTP 1.1 protocol and
with chunked encoding being used to stream responses that
are larger than a configured maximum size.
Compression will be used on responses whenever the client
indicates appropriate support.
.PP
An
.nh
.I Access-Control-Allow-Origin: *
.hy
header is added to all REST API responses.
.SH SEE ALSO
.BR PCPIntro (1),
.BR curl (1),
.BR pmcd (1),
.BR pmdaopenmetrics (1),
.BR pminfo (1),
.BR pmjson (1),
.BR pmlogger (1),
.BR pmlogpush (1),
.BR pmproxy (1),
.BR pmseries (1),
.BR PCPIntro (3),
.BR PMAPI (3)
and
.BR LOGARCHIVE (5)

.\" control lines for scripts/man-spell
.\" +ok+ offset_bits_per_record_avg kernel_pernode_cpu_intr
.\" +ok+ offsets_per_term_avg bytes_per_record_avg score_index_size_mb
.\" +ok+ records_per_doc_avg skip_index_size_mb filesys_blocksize
.\" +ok+ inverted_cap_ovh inverted_cap_mb inverted_sz_mb halt_wakeup
.\" +ok+ polltimeout proc_nprocs halt_exits read_bytes read_merge ValkeySearch
.\" +ok+ domainname appversion prometheus machineid blocksize
.\" +ok+ buddyinfo cebcbadc helptext slabinfo blktotal instname
.\" +ok+ hostspec avactive wakeups pernode physmem filesys blkread oneline
.\" +ok+ nonleaf freemem groupid pswitch dlmstT vmstat nprocs userid bdbda
.\" +ok+ descs xFFFD linux blkio pmIDs iname jobid avgsz ddff desc intr numa
.\" +ok+ aveq aac cae nas dba fbe bda sda sdb def del sem cfa dfa ffd bfe
.\" +ok+ api app ksm kvm ba ca da bb eb fb ac dc fc dd fd ce af bf ef