HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |HTTP SYNOPSIS |C SYNOPSIS |DESCRIPTION |OPEN METRICS AND OPEN TELEMETRY |SCALABLE TIME SERIES |FULL TEXT SEARCH |PMAPI HOST SERVICES |NOTES |SEE ALSO |COLOPHON | |
PMWEBAPI(3) Library Functions ManualPMWEBAPI(3)PMWEBAPI- introduction to the Performance Metrics Web Application Programming Interface
GET /metricsGET /series/...GET /search/...GET /pmapi/...POST /logger/...
#include <pcp/pmwebapi.h> ... assorted routines ...cc ... -lpcp_web -lpcp
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. The usual HTTP URL-encoded optional parameter rules apply and PMWEBAPI REST requests always follow the convention:/api/endpoint?parameter1=value1¶meter2=value2 Examples in all following sections use thecurl(1) command line utility with a localpmproxy(1) server listening on port 44322 (default port). Thepmjson(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 se‐ ries section use historical data recorded by thepmlogger(1) ser‐ vice, in conjunction with a local key-value server/
Exporting of live performance metrics in either Open Metrics (https://openmetrics.io) or Open Telemetry (https://opentelemetry.io) formats is available. All requests are performed on the web server host by default, un‐ less ahostspec parameter is provided.GET /metrics ┌────────────┬─────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │ names │ string │ Comma-separated list of metric names │ │ filter │ string │ Comma-separated list of excluded metric names │ │ match │ string │ Pattern matching style (exact, glob or regex) │ │ times │ boolean │ Append sample times (milliseconds since epoch) │ ├────────────┼─────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ └────────────┴─────────┴────────────────────────────────────────────────┘ Fetches current values and metadata for all metrics, or only met‐ rics indicated by a comma-separated list ofnames. For all numeric metrics with the given NAME prefixes, create an open text export format giving their current value and related metadata. Choice of output format is selected using the HTTPAccept header. With no header, the default response format is Open Metricstext. Using the header with valueapplication/json switches the response to the Open Telemetry JSON format. In Open Telemetry response mode, sample timestamps are always in‐ cluded and are reported using nanosecond precision. $ curl -H Accept:application/json -shttp://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" } ] } }, ... In Open Metrics response mode, the native PCP metric metadata (metric name, type, indom, semantics and units) is first output for each metric with# PCPprefix. The metadata reported is of the form described onpmTypeStr(3),pmInDomStr(3),pmSemStr(3) andpmUnitsStr(3) respectively. If thepmUnitsStr(3) units string is empty, thennoneis output. The units metadata string may contain spaces and extends to the end of the line. PCP metric names are mapped so that the.separators are exchanged with_(':' in back-compatibility mode, where "# PCP" is the iden‐ tifying line suffix). Both metric labels and instances are repre‐ sented as Prometheus labels, with external instance names being quoted and the flattened PCP metric hierarchy being presented with each value. When metricnames pattern matching is performed using thefilter option, the default mode is glob-based matching. Thematch option can be used to instead request regex-based or exact-match metric filtering. $ curl -shttp://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 The fast, scalable time series query capabilities provided by thepmseries(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 suit‐ ed to efficient retrieval by any number of web applications. All requests in this group can be accompanied by an optionalclient 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. 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. [1mGET/series/ping Simple liveness test for clients to check whether the server is up and supports the/series API.GET/series/query-pmSeriesQuery(3) ┌────────────┬────────┬────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────────────┤ │ expr │ string │ Query string inpmseries(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 inpmseries(1) and is passed to the server via either theexpr 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 identi‐ fiers. The JSON response contains the same information as thepm‐series-q/--queryoption using any of the time window parameters described onpmseries(1). If no time window parameters are speci‐ fied, the single most recent value observed is retrieved. $ curl -shttp://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 identi‐ fiers. The JSON response contains the same information as thepm‐series-d/--descoption. $ curl -shttp://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 theseries parameter). It can produce a list of all known label names, in the absence ofname,names orseries parameters. The JSON responses for these modes contains the same information as thepmseries-l/--labelsoption. Alternatively, it can produce a list of all known label values for a given labelname ornames. The JSON response for this mode contains the same information as thepmseries-v/--valuesoption. $ curl -shttp://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 noname,names orseries parameters, return the list of all known label names. $ curl -shttp://localhost:44322/series/labels | pmjson [ "agent", "appversion", "domainname", "groupid", "hostname", "jobid", "latitude", "longitude", "machineid", "platform", "userid" ] Use thename ornames parameters to find all possible label values for the given name(s). $ curl -shttp://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 identi‐ fiers. The JSON response contains the same information as thepm‐series-m/--metricsoption. $ curl -shttp://localhost:44322/series/metrics?series=605fc77742cd0317597291329561ac4e50c0dd12 | pmjson [ { "series": "605fc77742cd0317597291329561ac4e50c0dd12", "name": "disk.dev.read_bytes" } ] Alternatively, with noseries argument, this request will return the list of all known metric names. $ curl -shttp://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 thepmseries-S/--sourceoption. $ curl -shttp://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 thepmseries-i/--instanceoption. $ curl -shttp://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 noseries argument, this request will return the list of all known instance names. $ curl -shttp://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 inpmseries(1) format │ │ client │ string │ Request identifier sent back with response │ └────────────┴────────┴────────────────────────────────────────────┘ Load time series performance data from the specified source into the key-value server cache. This request is equivalent to thepm‐series-l/--loadoption. $ curl -s http://localhost:44322/series/load?expr={source.name:"/var/log/pcp/pmlogger/acme"} { "success": true } The full text search capabilities provided by thepmsearch(1) com‐ mand are also available through a REST API. These queries provide access to an index over performance metric names, instances, in‐ stance domains and help text, suitable for a metric search engine, and in a fashion suited to efficient querying by any number of web applications. In order to use this functionality, the optionalValkeySearch mod‐ ule must be loaded in the key-value server at the timepmproxyis started, such that metrics, instances and help text it discovers can be automatically indexed.GET/search/text-pmSearchTextQuery(3) ┌────────────┬────────┬─────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├────────────┼────────┼─────────────────────────────────────────────┤ │ query │ string │ Query string inpmsearch(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) │ └────────────┴────────┴─────────────────────────────────────────────┘ Performs a text search query across metrics and instance domains - all forms of names and help texts. The mandatory search string is further described inpmsearch(1) and is passed to the server via thequery parameter (HTTP GET). $ curl -shttp://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.", } ] } The available search entitytypes aremetric,indom andinstance. Query parametershighlight andfield takename,oneline andhelp‐text. Query parameterreturn takesname,type,oneline,helptext,indom. There is typically both a name and help text associated with met‐ rics. Contents of these are then matched againstquery. An in‐ stance domain has help text and a numeric identifier, while in‐ stances have a name only (which can be searched).GET/search/suggest-pmSearchTextSuggest(3) ┌────────────┬────────┬────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├────────────┼────────┼────────────────────────────────────┤ │ query │ string │ Search query for search engine │ │ limit │ number │ Max results to include in response │ └────────────┴────────┴────────────────────────────────────┘ Provides search query suggestions, that is, metric and instance names. The mandatory search string is further described inpmsearch(1) and is passed to the server via thequery parameter (HTTP GET). $ curl -shttp://localhost:44322/search/suggest?query=disk&limit=4 | pmjson [ "disk.all.avactive", "disk.all.aveq", "disk.all.blkread", "disk.all.blktotal" ]GET/search/indom-pmSearchTextInDom(3) ┌────────────┬────────┬─────────────────────────────────────┐ │ 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 │ └────────────┴────────┴─────────────────────────────────────┘ Provides all entities (instances, metrics) related to indom, in‐ cluding itself, that is passed to the server via thequery parame‐ ter.GET/search/info-pmSearchInfo(3) Provides metrics relating to operation of the search engine, in particular showing document and text record counts. $ curl -shttp://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 } The live performance collection facilities available frompmcd(1) can also be accessed through a REST API. All requests are performed on the web server host by default, un‐ less either ahostspec orcontext parameter is provided.hostname can be used in place ofhostspec. 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 allo‐ cated using the/pmapi/context interface, or implicitly allocated using other interfaces. The timeout interval is configurable at context creation time, and as such thepolltimeout parameter can be used anywhere thehost‐spec 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. To specify a specific existing context in any PMAPI web request, the endpoints can be accessed with either thecontext parameter or embedded in the endpoint URL itself, such as/pmapi/[num‐ber]/fetch.GET/pmapi/context-pmNewContext(3) ┌─────────────┬────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ polltimeout │ number │ Seconds of inactivity before closing context │ │ client │ string │ Request identifier sent back with response │ └─────────────┴────────┴────────────────────────────────────────────────┘ To create a context for live sampling, a web client can access any/pmapi URL (optionally using thehostspec orcontext parameter). If no context exists, a new one will be created for that web client, and its identifier returned for future accesses. However,/pmapi/context is provided as a dedicated URL for appli‐ cations wishing to explicitly create the contexts they use. If successful, the server responds with a HTTP 200 (OK) code and JSON message body of the form: $ curl -shttp://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 } } The context (a 32-bit unsigned decimal number) can then be used with all later requests. In the case of ahostspec containing authentication information, such as a username, the server will follow the HTTP Basic Authen‐ tication protocol to ascertain necessary authentication details from the user, providing the client web application an opportunity to request these from the user.GET/pmapi/metric-pmLookupDesc(3),pmLookupLabels(3),pmLookupName(3),pmLookupText(3) ┌─────────────┬────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ name │ string │ An individual metric name │ │ names │ string │ Comma-separated list of metric names │ │ pmid │ pmID │ Numeric orpmIDStr(3) metric identifier │ │ pmids │ string │ Comma-separated numeric orpmIDStr(3) pmIDs │ │ prefix │ string │ Metric namespace component as inPMNS(5) │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴────────┴────────────────────────────────────────────────┘ Themetric 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 Perfor‐ mance Metrics Name Space (PMNS). Theprefix parameter can be used to specify a subtree of the PMNS for traversal. Alternatively, a specific metric or comma-separat‐ ed list of metrics can be specified using eithername ornames The server response is a JSON document that provides metric meta‐ data as an array. $ curl -shttp://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 [...]" } ] } 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 thepminfo(1) command with the -dlmstToptions. The semantics, type and units fields are as returned bypmTypeStr(3),pmUnitsStr(3) andpmSemStr(3).GET/pmapi/fetch-pmFetch(3) ┌─────────────┬────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ delta │ string │ Sampling interval inpmParseInterval(3) form │ │ name │ string │ An individual metric name │ │ names │ string │ Comma-separated list of metric names │ │ pmid │ pmID │ Numeric orpmIDStr(3) metric identifier │ │ pmids │ string │ Comma-separated numeric orpmIDStr(3) pmIDs │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴────────┴────────────────────────────────────────────────┘ This request fetches (samples) current values for given metrics. 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 con‐ text (see section on InDom profiles below). $ curl -shttp://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 } ] } ] } The response fields map directly to fields from the underlyingpmFetch(3) sampling interface. 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. 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.GET/pmapi/children-pmGetChildren(3),pmGetChildrenStatus(3) ┌─────────────┬────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ prefix │ string │ Metric namespace component as inPMNS(5) │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴────────┴────────────────────────────────────────────────┘ Thechildren endpoint provides iterative namespace traversal for a context. If no parameters are supplied, the response will de‐ scribe the direct descendants of the Performance Metrics Name Space (PMNS) root. Theprefix parameter can be used to specify a subtree of the PMNS for traversal. The server response is a JSON document that provides the set of leaf and non-leaf nodes below the given namespace node or root. $ curl -shttp://localhost:44322/pmapi/children?prefix=mem | pmjson { "context": 348734, "name": "mem", "leaf": [ "physmem", "freemem" ], "nonleaf": [ "util", "numa", "vmstat", "buddyinfo", "slabinfo", "zoneinfo", "ksm" ] }GET/pmapi/indom-pmGetInDom(3),pmNameInDom(3),pmLookupInDom(3) ┌─────────────┬─────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼─────────┼────────────────────────────────────────────────┤ │ iname │ string │ Comma-separated list of instance names │ │ indom │ pmInDom │ Numeric orpmInDomStr(3) instance domain │ │ instance │ number │ Comma-separated list of instance numbers │ │ match │ string │ Pattern matching style (exact, glob or regex) │ │ name │ string │ An individual metric name │ ├─────────────┼─────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴─────────┴────────────────────────────────────────────────┘ 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 met‐ ric. The request can be further qualified with a comma-separated list of the instances to report on, either by name or number, using theinstance andiname parameters. In the case of instance name qualifiers, these will be matched by exact string comparison by default. Alternatively, the match pa‐ rameter can be used to specify that regular expression or glob pattern matching should be used instead. The response is a JSON document that provides the instance domain metadata as an array. $ curl -shttp://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": { ... }, } ] }GET/pmapi/profile-pmAddProfile(3),pmDelProfile(3) ┌─────────────┬─────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼─────────┼────────────────────────────────────────────────┤ │ iname │ string │ Comma-separated list of instance names │ │ indom │ pmInDom │ Numeric orpmInDomStr(3) instance domain │ │ instance │ number │ Comma-separated list of instance numbers │ │ expr │ string │ One of "add" or "del" (mandatory). │ │ match │ string │ Pattern matching style (exact, glob or regex) │ ├─────────────┼─────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴─────────┴────────────────────────────────────────────────┘ Some PMAPI operations can be performed with an active instance do‐ main profile which restricts (filters) the set of resulting in‐ stances returned, as described onpmAddProfile(3). $ curl -shttp://localhost:44322/pmapi/profile?expr=add,indom=60.2,iname=1%20minute { "context": 348734, "success": true }GET/pmapi/store-pmStore(3) ┌─────────────┬────────┬────────────────────────────────────────────────┐ │ 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 │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴────────┴────────────────────────────────────────────────┘ Some performance metrics allow their value to be modified, for ex‐ ample to re-initialize counters or to modify control variables. This operation takes a single metricname to modify, and optional‐ ly specificinstances. The mandatoryvalue will be interpreted according to the type of the metric being modified. If successful, the response from these requests is a JSON document of the form: $ curl -shttp://localhost:44322/pmapi/store?name=pmcd.control.timeout&value=10 { "context": 348734, "success": true }GET/pmapi/derive:pmAddDerived(3) ┌─────────────┬────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ expr │ string │ Derived metric expression │ │ name │ string │ New derived metric name │ ├─────────────┼────────┼────────────────────────────────────────────────┤ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ context │ number │ Web context number (optional like hostspec) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴────────┴────────────────────────────────────────────────┘ Create a new derived metric, as defined by thepmAddDerived(3) metric interface. Derived metrics are associated with the named context, or a new context is created and returned in the result. 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). $ curl -shttp://localhost:44322/pmapi/derive?name=blkio.avgsz&expr=disk.all.blktotal/disk.all.total | pmjson { "context": 348734, "success": true } $ curl -shttp://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 } ] } ] }GET/pmapi/metrics:pmLookupDesc(3),pmLookupLabels(3),pmFetch(3) ┌─────────────┬─────────┬────────────────────────────────────────────────┐ │ Parameters │ Type │ Explanation │ ├─────────────┼─────────┼────────────────────────────────────────────────┤ │ names │ string │ Comma-separated list of metric names │ │ times │ boolean │ Append sample times (milliseconds since epoch) │ ├─────────────┼─────────┼────────────────────────────────────────────────┤ │ context │ number │ Web context number (optional like hostspec) │ │ hostspec │ string │ Host specification as described inPCPIntro(1) │ │ polltimeout │ number │ Seconds of inactivity before context closed │ │ client │ string │ Request identifier sent back with response │ └─────────────┴─────────┴────────────────────────────────────────────────┘ This request is a subset of the style described in the ``OPEN MET‐ RICS AND OPEN TELEMETRY'' section, allowing a web context identi‐ fier 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.ARCHIVE WEBHOOK - LOGARCHIVE(5) %%%SH%%% Remote archive push functionality is available via thepmlogger(1) andpmlogpush(1) utilities. This is achieved through a series of HTTP POST operations to the API endpoints described here. All requests in this group can be accompanied by an optionalclient 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. [1mGET/logger/ping Basic liveness test for clients to check whether the server is up and supports the/logger API. [1mPOST/logger/label The body of this API is the machine-agnostic binary (on-disk) rep‐ resentation of a PCP archive label as described inLOGARCHIVE(5). Either version 2 and 3 are accepted, and thevolume field of this stucture will be ignored - one API call suffices for all of the volumes of an archive,pmproxyensures correct content is written for each. This API returns a numeric token (LOGID) that must be used in all subsequent API interactions for this archive as described below. [1mPOST/logger/meta/LOGID The request body contains metadata file records as described inLOGARCHIVE. [1mPOST/logger/index/LOGID The request body contains temporal index records as described inLOGARCHIVE. [1mPOST/logger/volume/VOLID/LOGID The request body contains timestamped metric value samples, as de‐ scribed inLOGARCHIVE. The numeric volume (VOLID) to which these records is to be written is a mandatory part of the API endpoint.For the REST APIs, errors generally result in HTTP-level error re‐ sponses. Wherever possible, any PMAPI error string will also be provided in a message along with the response. 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 re‐ sponses whenever the client indicates appropriate support. AnAccess-Control-Allow-Origin: * header is added to all REST API responses.
PCPIntro(1),curl(1),pmcd(1),pmdaopenmetrics(1),pminfo(1),pmjson(1),pmlogger(1),pmlogpush(1),pmproxy(1),pmseries(1),PCPIntro(3),PMAPI(3) andLOGARCHIVE(5)
This page is part of thePCP (Performance Co-Pilot) project. In‐ formation 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 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) 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 isnot part of the original manual page), send a mail to man-pages@man7.orgPerformance Co-Pilot PCPPMWEBAPI(3)Pages that refer to this page:pcpcompat(1), pmdaopenmetrics(1), pmfind(1), pmjson(1), pmlogpush(1), pmproxy(1), pmseries(1), pmapi(3), pmda(3), pmdiscoversetup(3), pmhttpnewclient(3), pmsearchinfo(3), pmsearchsetup(3), pmsearchtextindom(3), pmsearchtextquery(3), pmsearchtextsuggest(3), pmseriesdescs(3), pmseriesquery(3), pmseriessetup(3), pmwebtimerregister(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |