This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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?




Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]