NAME | OVERVIEW | CONTEXT CREATION: pmNewContext | PMAPI OPERATIONS | GRAPHITE | SEE ALSO | COLOPHON

PMWEBAPI(3)               Library Functions Manual               PMWEBAPI(3)

NAME         top

       PMWEBAPI  -  introduction  to the Performance Metrics Web Application
       Programming Interface

OVERVIEW         top

       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 Access-
       Control-Allow-Origin: * header is added to all JSON responses.

CONTEXT CREATION: pmNewContext         top

       To create a new web context identifier, a web client invokes:

       /pmapi/context?hostname=STRING

       /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.

       /pmapi/context?archivefile=ARCHIVE
              Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file
              name.  Only metrics from the given archive are available.

       In addition, the web client may add the parameter &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:

              { "context" : NNNNN }

       The number (a 32-bit unsigned decimal) is then used in all later op‐
       erations.

PMAPI OPERATIONS         top

       The general form of the requests is as follows:
       /pmapi/NNNNN/OPERATION where

       /pmapi is the fixed prefix for all PMWEBAPI operations,

       NNNNN  is a PMWEBAPI context number returned from a context-creation
              call, or assigned permanently at pmwebd startup, and

       OPERATION?PARAM1=VALUE2&PARAM2=VALUE2
              identifies the operation and its URL-encoded parameters.  Some
              parameters may be optional.

   METRIC METADATA: pmLookupName, pmLookupDesc, pmLookupText,
       pmTraversePMNS_r
       The general form of the requests is as follows:

       /pmapi/NNNNN/_metric
              Traverse the entire Performance Metrics Name Space (PMNS).

       /pmapi/NNNNN/_metric?prefix=NAME
              Traverse the subtree of PMNS with the prefix NAME.

       The response is a JSON document that provides the metric metadata as
       an array.  For example:

              { "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", ... }
                  ...
                ] }

       Most of the fields are self-explanatory.

       name   A name for the metric as defined in the PMNS.  If the PMNS
              contains multiple names associated with the metric's Perfor‐
              mance Metric Identifier (PMID), one of these will be returned
              via name, but there is no way to determine which of the dupli‐
              cate names this will be.

       PPPP   the PMID

       DDDD   the instance domain

       type   from pmTypeStr

       units  from pmUnitsStr

       sem    an abbreviation of the metric semantic:

              PM_SEM_COUNTER  "counter"
              PM_SEM_INSTANT  "instant"
              PM_SEM_DISCRETE "discrete"

   METRIC VALUE: pmFetch
       The general form of the requests is as follows:

       /pmapi/NNNNN/_fetch?names=NAME1,NAME2
              Fetch current values for given named metrics.

       /pmapi/NNNNN/_fetch?pmids=PPPP1,PPPP2
              Fetch current values for given PMIDs.

       If any of the names/pmids are valid, the response is a JSON document
       that provides the values for all requested metrics, for all their in‐
       stances.

              { "timestamp": { "s":SEC, "us":USEC },
                "values": [
                      { "pmid":PPPP1, "name":"NAME1",
                        "instances:" [
                             { "instance":IIII1, "value":VALUE1 }
                             { "instance":IIII2, "value":VALUE2 }
                             ...
                        ] },
                      { "pmid":PPPP2, "name":"NAME2", ... }
                      ...
                ] }

       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.

   INSTANCE DOMAINS METADATA: pmGetInDom, pmNameInDom, pmLookupInDom
       The general form of the requests is as follows:

       /pmapi/NNNN/_indom?indom=DDDD
              List instances of the given instance domain.

       /pmapi/NNNN/_indom?name=NAME
              List instances of the instance domain belonging to the named
              metric.

       In addition, either query may be suffixed with:

       &instance=IIII,JJJJ
              Restrict listings to given instance code numbers.

       &iname=INAME1,INAME2
              Restrict listings to given instance names.

       The response is a JSON document that provides the metric metadata as
       an array.  For example:

              { "indom":DDDD,
                 "instances": [
                    { "instance":IIII, "name":"INAME" }
                    ...
                 ] }

   INSTANCE PROFILE: pmAddProfile, pmDelProfile
       The general form of these requests is as follows:

       /pmapi/NNNN/_profile_reset?indom=DDDD
              These are not currently supported.

       /pmapi/NNNN/_profile_add?indom=DDDD&instance=IIII,JJJJ
              These are not currently supported.

       /pmapi/NNNN/_profile_add?indom=DDDD&iname=IIII,JJJJ
              These are not currently supported.

       /pmapi/NNNN/_profile_del?indom=DDDD&instance=JJJJ
              These are not currently supported.

       /pmapi/NNNN/_profile_del?indom=DDDD&iname=INAME1,INAME2
              These are not currently supported.

   METRIC STORE: pmStore
       The general form of these requests is as follows:

       /pmapi/NNNN/_store?name=NAME&value=VALUE
              Store a new value for given named metrics.

       /pmapi/NNNNN/_store?pmid=PPPP&value=VALUE
              Store a new value for given performance metric identifier
              (PMID).

       In addition, either query may be suffixed with:

       &instance=IIII,JJJJ
              Restrict store to given instance code numbers.

       &iname=INAME1,INAME2
              Restrict store to given instance names.

       If successful, the response from these requests is a JSON document of
       the form:

              { "success" : true }

   DERIVED METRICS: pmRegisterDerived
       /pmapi/NNNNN/_derive?name=NAME&expr=EXPRESSION
              These are not currently supported.

   CONTEXT COPY: pmDupContext
       /pmapi/NNNNN/copy
              These are not currently supported.

   CONTEXT CLOSE: pmDestroyContext
       /pmapi/NNNNN/destroy
              This is not likely to be supported, as it is destructive and
              would offer a tempting target to brute-force attackers.  In‐
              stead, the pmwebd timeout is used to automatically free unused
              contexts.

GRAPHITE         top

       When enabled, pmwebd can emulate a subset of the graphite web-api to
       allow web applications like graphite and grafana to extract data from
       all archives under the configured -A directory.  The graphite
       namespace is constructed from the PCP archives using a simple mapping
       that encodes the Cartesian product of archives, metrics, and
       instance-domain instances into dot-separated strings.  Some
       metacharacter-quoting is employed to encode general strings into
       components.  Only numeric PCP metrics are exposed; COUNTER semantic
       values are rate-converted.

           ┌─────────┬────────┬─────────────────────────────────────────┐
           │position │ number │                 purpose                 │
           ├─────────┼────────┼─────────────────────────────────────────┤
           │   1     │   1    │ the pathname of the archive .meta file  │
           │   2     │   N    │ the N components of the pcp metric name │
           │  N+2    │   1    │ instance name of the metric (if any)    │
           └─────────┴────────┴─────────────────────────────────────────┘
       Since glob wildcarding is supported within metric name components,
       using them in the first component (an encoding of the archive name)
       is a good way to identify machines, or to match multiple archives
       spanning times of interest.

       We list here only the broadest outline of the supported calls.
       pmwebd does not support every graphite web-api option, so many
       querystring parameters may be ignored.  Arithmetic/statistical
       functions on metrics are not supported.

       /graphite/render?format=json&target=FOO&from=TIME&until=TIME
              Return a series of values of the given metrics, between the
              two times, sampled every 60 seconds.

       /graphite/rawdata?target=FOO.BAR&from=TIME&until=TIME
              Same, with a slightly different result encoding.

       /graphite/render?format=png&target=FOO&from=TIME&until=TIME&....
              Same, but render the curves into a PNG image file.  Several
              color- and rendering-control-related parameters are supported.

       /graphite/metrics/find?query=FOO.BAR.*
              Provide incremental metric-tree traversal using wildcards.

       /graphite/graphlot/findmetric?query=FOO+BAR
              Search through metrics with space-separated regular
              expressions.

       /graphite/browser/search?q=FOO+BAR
              Same, with a slightly different result encoding.

SEE ALSO         top

       PCPIntro(1), PCPIntro(3), pmwebd(1), http://graphite.readthedocs.org/ 
       and PMAPI(3)

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information 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@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion 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 is not part of the original man‐
       ual page), send a mail to man-pages@man7.org

Performance Co-Pilot                 PCP                         PMWEBAPI(3)

Pages that refer to this page: pmwebd(1)pmhttpnewclient(3)