---

   pmwebapi    ( 3 )

---

SCALABLE TIME SERIES

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 }