👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

CentOS 7.0 - man page for pmwebapi (centos section 3)

PMWEBAPI(3)									      PMWEBAPI(3)

NAME
       PMWEBAPI - introduction to the Performance Metrics Web Application Programming Interface

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.

CONTEXT CREATION: pmNewContext
       To create a new web context identifier, a web client invokes:

       /pmapi/context?local=ANYTHING
	      Creates a PM_CONTEXT_LOCAL PMAPI context.

       /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 authentica-
	      tion credentials with matching userid/password.

       /pmapi/context?archivefile=ARCHIVE
	      Creates a PM_CONTEXT_ARCHIVE PMAPI context with the given file name.

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

PMAPI OPERATIONS
       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, pmTraversePMNS_r
       The general form of the requests is as follows:

       /pmapi/NNNNN/_metric
	      Traverse the entire 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  exam-
       ple:

	      { "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.

       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.

       The  response  is  a JSON document that provides the values for all requested metrics, for
       all their instances.

	      { "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 in-
       teger 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 exam-
       ple:

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

   INSTANCE PROFILE: pmAddProfile, pmDelProfile
       /pmapi/NNNN/_profile_reset?
	      These are not currently supported.

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

   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.  Instead, the pmwebd timeout is used to automati-
	      cally free unused contexts.

SEE ALSO
       PCPIntro(1), PCPIntro(3), pmwebd(3), and PMAPI(3)

Performance Co-Pilot			       PCP				      PMWEBAPI(3)


All times are GMT -4. The time now is 02:04 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password