diff options
Diffstat (limited to 'man/man3/pmwebapi.3')
| -rw-r--r-- | man/man3/pmwebapi.3 | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/man/man3/pmwebapi.3 b/man/man3/pmwebapi.3 new file mode 100644 index 0000000..e4ad6f4 --- /dev/null +++ b/man/man3/pmwebapi.3 @@ -0,0 +1,252 @@ +'\" t macro stdmacro +.\" +.\" Copyright (c) 2013-2014 Red Hat, Inc. All Rights Reserved. +.\" +.\" 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 + +.de SAMPLE +.br +.RS +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.SH OVERVIEW + +The PMWEBAPI interface is a binding of a subset of the PMAPI to the +web. It uses HTTP as transport, REST as organizational style for +request/parameter encoding (the GET and POST methods are +interchangeable), and JSON as response encoding. A context identifier +is used as a persistent way to refer to PMAPI contexts across related +web requests. These context identifiers expire after a configurable +period of disuse. Errors generally result in HTTP-level error responses. +An +.nh +.B Access-Control-Allow-Origin: * +.hy +header is added to all JSON responses. + +.SH CONTEXT CREATION: pmNewContext + +To create a new web context identifier, a web client invokes: +.TP +.B /pmapi/context?local=ANYTHING +Creates a PM_CONTEXT_LOCAL PMAPI context. +.TP +.B /pmapi/context?hostname=STRING +.TP +.B /pmapi/context?hostspec=STRING +Creates a PM_CONTEXT_HOST PMAPI context with the given host name and/or extended +specification. If the host specification contains a userid/password combination, +then the corresponding pmapi context operations will require HTTP Basic authentication +credentials with matching userid/password. +.TP +.B /pmapi/context?archivefile=ARCHIVE +Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file name. +.PP +In addition, the web client may add the parameter +.B &polltimeout=MMMM +for a maximum interval (in seconds) between expected accesses to the +given context. This value is limited by pmwebd configuration, and is +a courtesy to allow pmwebd to free up memory earlier in case of sudden +web application shutdown. + +If successful, the response from these requests is a JSON document of the form: + +.SAMPLE +{ "context" : NNNNN } +.ESAMPLE + +The number (a 32-bit unsigned decimal) is then used in all later operations. + +.SH PMAPI OPERATIONS + +The general form of the requests is as follows: +.B /pmapi/NNNNN/OPERATION +where +.TP +.B /pmapi +is the fixed prefix for all PMWEBAPI operations, +.TP +.B NNNNN +is a PMWEBAPI context number returned from a context-creation call, or +assigned permanently at pmwebd startup, and +.TP +.B OPERATION?PARAM1=VALUE2&PARAM2=VALUE2 +identifies the operation and its URL-encoded parameters. Some +parameters may be optional. + +.SS METRIC METADATA: pmLookupName, pmLookupDesc, pmTraversePMNS_r + +The general form of the requests is as follows: +.TP +.B /pmapi/NNNNN/_metric +Traverse the entire PMNS. +.TP +.B /pmapi/NNNNN/_metric?prefix=NAME +Traverse the subtree of PMNS with the prefix NAME. +.PP +The response is a JSON document that provides the metric metadata +as an array. For example: + +.SAMPLE +{ "metrics": [ + { "name":"foo.bar", "pmID":PPPP, "indom":DDDD, + "type":"32", "sem":"instant", "units":"MHz", + "text-oneline":"foo bar", "text-help":"blah blah blah" }, + { "name":"foo.bar2", ... } + ... + ] } +.ESAMPLE + +Most of the fields are self-explanatory. +.TP +PPPP +the PMID +.TP +DDDD +the instance domain +.TP +type +from pmTypeStr +.TP +units +from pmUnitsStr +.TP +sem +an abbreviation of the metric semantic: +.TS +l l. +PM_SEM_COUNTER "counter" +PM_SEM_INSTANT "instant" +PM_SEM_DISCRETE "discrete" +.TE + +.SS METRIC VALUE: pmFetch + +The general form of the requests is as follows: +.TP +.B /pmapi/NNNNN/_fetch?names=NAME1,NAME2 +Fetch current values for given named metrics. +.TP +.B /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2 +Fetch current values for given PMIDs. +.PP +The response is a JSON document that provides the values for +all requested metrics, for all their instances. + +.SAMPLE +{ "timestamp": { "s":SEC, "us":USEC }, + "values": [ + { "pmid":PPPP1, "name":"NAME1", + "instances:" [ + { "instance":IIII1, "value":VALUE1 } + { "instance":IIII2, "value":VALUE2 } + ... + ] }, + { "pmid":PPPP2, "name":"NAME2", ... } + ... + ] } +.ESAMPLE + +Most of the fields are self-explanatory. Numeric metric types +are represented as JSON integer or floating-point values. Strings +are passed verbatim, except that non-ASCII values are replaced +with a Unicode 0xFFFD REPLACEMENT CHARACTER code. Event type metrics +are not currently supported. + +.SS INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom + +The general form of the requests is as follows: +.TP +.B /pmapi/NNNN/_indom?indom=DDDD +List instances of the given instance domain. +.TP +.B /pmapi/NNNN/_indom?name=NAME +List instances of the instance domain belonging to the named metric. +.PP +In addition, either query may be suffixed with: +.TP +.B &instance=IIII,JJJJ +Restrict listings to given instance code numbers. +.TP +.B &iname=INAME1,INAME2 +Restrict listings to given instance names. +.PP + +The response is a JSON document that provides the metric metadata +as an array. For example: + +.SAMPLE +{ "indom":DDDD, + "instances": [ + { "instance":IIII, "name":"INAME" } + ... + ] } +.ESAMPLE + +.SS INSTANCE PROFILE: pmAddProfile, pmDelProfile + +.TP +.B /pmapi/NNNN/_profile_reset? +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_reset?indom=DDDD +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ +These are not currently supported. +.TP +.B /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2 +These are not currently supported. + +.SS DERIVED METRICS: pmRegisterDerived + +.TP +.B /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION +These are not currently supported. + +.SS CONTEXT COPY: pmDupContext + +.TP +.B /pmapi/NNNNN/copy +These are not currently supported. + +.SS CONTEXT CLOSE: pmDestroyContext + +.TP +.B /pmapi/NNNNN/destroy +This is not likely to be supported, as it is destructive and would offer +a tempting target to brute-force attackers. Instead, the pmwebd timeout +is used to automatically free unused contexts. + +.SH SEE ALSO +.BR PCPIntro (1), +.BR PCPIntro (3), +.BR pmwebd (3), +and +.BR PMAPI (3) |