The fast, scalable time series query capabilities provided by the
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.
All requests in this group can be accompanied by an optional
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.
GET /series/query - pmSeriesQuery(3)
┌───────────┬────────┬────────────────────────────────────────────┐
│Parameters │ Type │ Explanation │
├───────────┼────────┼────────────────────────────────────────────┤
│expr │ string │ Query string in pmseries(1) format │
│client │ string │ Request identifier sent back with response │
└───────────┴────────┴────────────────────────────────────────────┘
Performs a time series query for either matching identifiers, or
matching identifiers with series of time-stamped values.
The query is in the format described in pmseries(1) and is passed
to the server via either the expr parameter (HTTP GET) or via the
message body (HTTP POST).
When querying for time series matches only, no time window
options are specified and matching series identifiers are
returned in a JSON array.
$ curl -s 'http://localhost:44322/series/query?expr=disk.dev.read*' | pmjson
[
"9d8c7fb51ce160eb82e3669aac74ba675dfa8900",
"ddff1bfe286a3b18cebcbadc1678a68a964fbe9d",
"605fc77742cd0317597291329561ac4e50c0dd12"
]
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.
$ 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"
}
]
GET /series/values - pmSeriesValues(3)
┌───────────┬────────┬────────────────────────────────────────────┐
│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 │
└───────────┴────────┴────────────────────────────────────────────┘
Performs values retrievals for one or more time series
identifiers. The JSON response contains the same information as
the pmseries -q/--query option using any of the time window
parameters described on pmseries(1). If no time window
parameters are specified, the single most recent value observed
is retrieved.
$ curl -s http://localhost:44322/series/values?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
{
"series": "605fc77742cd0317597291329561ac4e50c0dd12",
"timestamp": 1317633022959.959241041,
"value": "71660"
}
]
GET /series/descs - pmSeriesDescs(3)
┌───────────┬────────┬────────────────────────────────────────────┐
│Parameters │ Type │ Explanation │
├───────────┼────────┼────────────────────────────────────────────┤
│series │ string │ Comma-separated list of series identifiers │
│client │ string │ Request identifier sent back with response │
└───────────┴────────┴────────────────────────────────────────────┘
Performs a descriptor lookup for one or more time series
identifiers. The JSON response contains the same information as
the pmseries -d/--desc option.
$ 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",
}
]
GET /series/labels - pmSeriesLabels(3), pmSeriesLabelValues(3)
┌───────────┬────────┬────────────────────────────────────────────┐
│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 │
└───────────┴────────┴────────────────────────────────────────────┘
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 series parameter). It can produce a list of all known
label names, in the absence of name, names or series parameters.
The JSON responses for these modes contains the same information
as the pmseries -l/--labels option.
Alternatively, it can produce a list of all known label values
for a given label name or names. The JSON response for this mode
contains the same information as the pmseries -v/--values option.
$ 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
}
}
]
Alternatively, with no name, names or series parameters, return
the list of all known label names.
$ curl -s http://localhost:44322/series/labels | pmjson
[
"agent",
"appversion",
"domainname",
"groupid",
"hostname",
"jobid",
"latitude",
"longitude",
"machineid",
"platform",
"userid"
]
Use the name or names parameters to find all possible label
values for the given name(s).
$ curl -s http://localhost:44322/series/labels?names=hostname,domainname | pmjson
{
"hostname": [ "app", "nas" ],
"domainname": [ "acme.com" ]
}
GET /series/metrics - pmSeriesMetrics(3)
┌───────────┬────────┬────────────────────────────────────────────┐
│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 │
└───────────┴────────┴────────────────────────────────────────────┘
Performs a metric name lookup for one or more time series
identifiers. The JSON response contains the same information as
the pmseries -m/--metrics option.
$ curl -s http://localhost:44322/series/metrics?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson
[
{
"series": "605fc77742cd0317597291329561ac4e50c0dd12",
"name": "disk.dev.read_bytes"
}
]
Alternatively, with no series argument, this request will return
the list of all known metric names.
$ 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",
...
]
GET /series/sources - pmSeriesSources(3)
┌───────────┬────────┬─────────────────────────────────────────────┐
│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 │
└───────────┴────────┴─────────────────────────────────────────────┘
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 pmseries -S/--source option.
$ curl -s http://localhost:44322/series/sources?source=2cd6a38f9339f2dd1f0b4775bda89a9e7244def6 | pmjson
[
{
"source": "2cd6a38f9339f2dd1f0b4775bda89a9e7244def6",
"context": [
"/var/log/pcp/pmlogger/acme",
"www.acme.com"
]
}
]
GET /series/instances - pmSeriesInstances(3)
┌───────────┬────────┬───────────────────────────────────────────────┐
│Parameters │ Type │ Explanation │
├───────────┼────────┼───────────────────────────────────────────────┤
│series │ string │ Comma-separated list of series identifiers │
│match │ string │ Glob pattern string to match on all instances │
│client │ string │ Request identifier sent back with response │
└───────────┴────────┴───────────────────────────────────────────────┘
Provide instance identifiers and names for one or more time
series identifiers. The JSON response contains the same
information as the pmseries -i/--instance option.
$ 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",
}
]
Alternatively, with no series argument, this request will return
the list of all known instance names.
$ curl -s http://localhost:44322/series/instances | pmjson
[
"1 minute",
"5 minute",
"15 minute",
"cpu0",
"cpu1",
"cpu2",
"cpu3",
"node0",
"node1",
"sda",
"sdb",
...
]
GET /series/load - pmSeriesLoad(3)
┌───────────┬────────┬────────────────────────────────────────────┐
│Parameters │ Type │ Explanation │
├───────────┼────────┼────────────────────────────────────────────┤
│expr │ string │ Source load string in pmseries(1) format │
│client │ string │ Request identifier sent back with response │
└───────────┴────────┴────────────────────────────────────────────┘
Load time series performance data from the specified source into
the redis-server cache. This request is equivalent to the
pmseries -l/--load option.
$ curl -s http://localhost:44322/series/load?expr={source.name:"/var/log/pcp/pmlogger/acme"}
{
"success": true
}
