This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
sketch of possible web pmapi
- From: "Frank Ch. Eigler" <fche at redhat dot com>
- To: pcp at oss dot sgi dot com
- Cc: systemtap at sourceware dot org
- Date: Tue, 22 Mar 2011 13:53:45 -0400
- Subject: sketch of possible web pmapi
Hi -
I've finally jotted down some rough ideas about how a hypothetical web
api might look for pcp. It exposes only a subset of the PMAPI (not
sure whether pmns* should be added) in the form of http get operations
that even a plain web browser can use. Let me know if you agree this
is worth prototyping.
* model:
XMLRPC
web client -+-> apache / mod_proxy (reverse-proxying) -+
(javascript) +-> (or directly) -+-> pmxmlrpc
PMAPI
pmxmlrpc -+-> network pmcd
+-> network pmproxy -> pmcd
+-> local pmda
* general idea:
- Exposing meaty subset of PMAPI
- A plain web browser speaking http should be able to
- navigate metric namespace
- view metric metadata
- view metric values, including enqueued events
- GET requests produce XML results, with a minimal linked
XSLT->HTML renderer
- A plain wget should also work
* API outline
- create a context
/context?local
/context?hostname=HOSTNAME
/context?archivefile=FILENAME
?poll-timeout=SECONDS
/context/CONTEXT/copy
- list/describe metrics
/context/CONTEXT/metric?glob=GLOB
/context/CONTEXT/metric?pmids=ID1,ID2,ID3
- fetch metric values
/context/CONTEXT/value?pmids=ID1,ID2,ID3
/context/CONTEXT/value?pmids=ID1,ID2,ID3&time=TIME
- list/describe/modify instance profile
/context/CONTEXT/domain?ids=ID1,ID2
/context/CONTEXT/domain?profile=add&ids=ID1,ID2
/context/CONTEXT/domain?profile=delete&ids=ID1,ID2
* operation outline:
1) browse http://pmwebapisrv:8234/, authenticate, get html form to select
connection context: local (or) hostname=HOSTNAME
(or) archivefile=FILENAME,
optional poll-timeout=NUMBER. Each per-context request
restarts the timeout. If it expires, the web proxy will disconnect
from the PCPD/PMDA / pmDestroyContext().
2) submit GET /context? form to return an XML document denoting the
creation of a context:
<? ... ?>
<?xml-stylesheet ... href="context.xsl"?>
<pcp:context name="CONTEXTNAME" expires="TIMESTAMP"/>
The context.xsl stylesheet renders this XML to HTML, noting how long
the context will remain open without a refresh, and listing navigation
options such as:
/context/CONTEXTNAME/copy -> to generate a new dup context; back to 2)
a form /context/CONTEXTNAME/metric?glob=GLOB ; and
a form /context/CONTEXTNAME/metric?id=PMID,PMID,PMID ; to jump to metric
metadata
3) the list of metric metadata is another XML document, from pmLookupDesc()
<? ... ?>
<?xml-stylesheet ... href="metrics.xsl"?>
<pcp:metrics expires="TIMESTAMP">
<pcp:metric name="METRICNAME" id="PMID">
<pcp:type number="NUM" name="TYPENAME"/>
<pcp:indom number="NUM" name="INDOMNAME"/>
<pcp:counter/> or <pcp:instant/> or <pcp:discrete/>
<pcp:units space="NUM" time="NUM" count="NUM"
scalespace="STRING" scaletime="STRING" scalecount="NUM"/>
</pcp:metric> ...
</pcp:metrics>
which is to render to a lovely HTML table, describing the metric
metadata, plus providing links to metric-value and domain-instance
views below:
4) the list of metric values is another XML document served by
/context/CONTEXT/value?pmids=ID1,ID2,ID3 [&time=TIME]
<? ... ?>
<?xml-stylesheet ... href="values.xsl"?>
<pcp:values time="TIMESTAMP" expires="TIMESTAMP">
<pcp:value pmid="PMID">
<pcp:result inst="NUM">9999</pcp:value> # if printable?
#or <pcp:result inst="NUM" encoding="base64Binary">base64-text
</pcp:value>
#or <pcp:event inst="NUM" time="TIMESTAMP">
<pcp:result ...><pcp:result ...> ...
</pcp:event>
</pcp:value>
</pcp:values>
The xslt widget would render the values into a tabular form, with
a refresh link. This is the one that a web application or
browser would want to fetch frequently.
5) domain instance metadata from pmGetInDom() would be served by
/context/CONTEXT/domain?ids=ID1,ID2,ID3 :
resulting in:
<? ... ?>
<?xml-stylesheet ... href="domains.xsl"?>
<pcp:domains expires="TIMESTAMP">
<pcp:domain name="NAME" id="ID">
<pcp:domain-instance name="NAME" id="ID"/>
...
</pcp:domain> ...
</pcp:domains>
This would be rendered into HTML that allows invidual domain-instances to
be pmAddProfile/pmDelProfile'd to the CONTEXT, via
/context/CONTEXT/domain?profile=add&ids=ID1,ID2,ID3
/context/CONTEXT/domain?profile=add&ids=all
/context/CONTEXT/domain?profile=delete&ids=ID1,ID2,ID3
/context/CONTEXT/domain?profile=delete&ids=all
which would return the same sort of XML as above, after adjusting
the context. XXX: is there a way to query PMAPI as to the
current pmAddProfile active instances?