Chapter 6. Jolokia协议

访问Jolokia最简单的方法是通过发送HTTP GET请求.这些请求的所有参数进行编码后存在于请求URL中。 通常情况下，Jolokia在使用的URL中提取参数的路径信息部分。在路径信息，每部分被一个斜杠（/）分隔。请求URL格式一般为

<base-url>/<type>/<arg1>/<arg2>/..../

The <base-url> 指明要访问的agent. 通常为 http://localhost:8080/jolokia, 但这取决于你的安装部署. 通常, 为部署的agent名称, 默认情况下是基于agent的文件名 (例如jolokia.war). <type> 指明Jolokia支持的操作 (在下一节介绍), 接下来的几个斜杠分割的参数用来指明特定的操作.

例如, the following URL executes a read Jolokia operation on the MBean java.lang:type=Memory for reading the attribute HeapMemoryUsage (see Section 6.2.1, “Reading attributes (read)”). It is assumed, that the agent is reachable under the base URL http://localhost:8080/jolokia:

http://localhost:8080/jolokia/read/java.lang:type=Memory/HeapMemoryUsage

If one of the request parts contain a slash (/) (e.g. as part of you bean's name) it needs to be escaped. An exclamation mark (!) is used as escape character^[8]. A exclamation mark needs to be doubled for escaping. Any other characted preceded by an exclamation mark is taken literally. Table Table 6.1, “转义规则” illustrates the escape rules as used in GET requests.

For example, to read the atrribute State on the MBean named jboss.jmx:alias=jmx/rmi/RMIAdaptor, an access URL like this has to be constructed:

.../read/jboss.jmx:alias=jmx!/rmi!/RMIAdaptor/State

Client libraries like JMX::Jmx4Perl do this sort of escaping transparently.

Escaping can be avoided alltogether if a slightly different variant for a request is used (which doesn't look that REST-stylish, though). Instead of providing the information as path-info, a query parameter p can be used instead. This should be URL encoded, though. For the example above, the alternative is

http://localhost:8080/jolokia?p=/read/jboss.jmx:alias=jmx%2Frmi%2FRMIAdaptor/State

POST requests are the most powerful way to communicate with the Jolokia agent. There are fewer escaping issues and it allows for features which are not available with GET requests. POST requests uses a fixed URL and put their payload within the HTTP request's body. This payload is represented in JSON, a data serialization format originating from JavaScript world.

The JSON format for a single request is a JSON object, which is essentially a map with keys (or attributes) and values. All requests have a common mandatory attribute, type, which specifies the kind of JMX operation to perform. The other attributes are either operation specific as described in Section 6.2, “Jolokia operations” or are processing parameters which influence the overall behaviour and can be mixed in to any request. See Section 6.3, “Processing parameters” for details.

A sample read request in JSON format looks like the following example. It has a type "read" (case doesn't matter) and the three attributes mbean, attribute and path which are specific to a read request.

  {
    "type" : "read",
    "mbean" : "java.lang:type=Memory",
    "attribute" : "HeapMemoryUsage",
    "path" : "used",
  }

Each request JSON object results in a single JSON response object contained in the HTTP answer's body. A bulk request contains multiple Jolokia requests within a single HTTP request. This is done by putting individual Jolokia requests into a JSON array:

 [
  {
    "type" : "read",
    "attribute" : "HeapMemoryUsage",
    "mbean" : "java.lang:type=Memory",
    "path" : "used",
  },
  { 
    "type" : "search"
    "mbean" : "*:type=Memory,*",
  }
 ]

This request will result in a JSON array containing multiple JSON responses within the HTTP response. They are returned in same order as the requests in the initial bulk request.

Responses are always encoded in UTF-8 JSON, regardless whether the requst was a GET or POST request. In general, two kinds of responses can be classified: In the normal case, a HTTP Response with response code 200 is returned, containing the result of the operation as a JSON payload. In case of an error, a 4xx or 5xx code will be returned and the JSON payload contains details about the error occured (e.g. 404 means "not found"). (See this page for more information about HTTP error codes..)

In the non-error case a JSON response looks mostly the same for each request type except for the value attribute which is request type specific.

The format of a single Jolokia response is

 {
   "value": .... ,
   "status" : 200,
   "timestamp" : 1244839118,
   "request": {
               "type": ...,
               ....
              },
   "history":[
               {"value": ... ,
                "timestamp" : 1244839045
               }, ....
             ]
 }

For successful requests, the status is always 200 (the HTTP success code). The timestamp contains the epoch time^[9] when the request has been handled. The request leading to this response can be found under the attribute request. Finally and optionally, if history tracking is switched on (see Section 6.5, “Tracking historical values”), an entry with key history contains a list of historical values along with their timestamps. History tracking is only available for certain type of requests (read, write and exec). The value is specific for the type of request, it can be a single scalar value or a monster JSON structure.

If an error occurs, the status will be a number different from 200. An error response looks like

  {
    "status":400,
    "error_type":"java.lang.IllegalArgumentException",
    "error":"java.lang.IllegalArgumentException: Invalid request type 'java.lang:type=Memory'",
    "stacktrace":"java.lang.IllegalArgumentException: Invalid request type 'java.lang:type=Memory'\n
                  \tat org.cpan.jmx4perl.JmxRequest.extractType(Unknown Source)\n
                  \tat org.cpan.jmx4perl.JmxRequest.<init>(Unknown Source) ...."
  }

For status codes it is important to distinguish status codes as they appear in Jolokia JSON response objects and the HTTP status code of the (outer) HTTP response. There can be many Jolokia status codes, one for each Jolokia request contained in the single HTTP request. The HTTP status code merely reflect the status of agent itself (i.e. whether it could perform the operation at all), whereas the Jolokia response status reflects the result of the operation (e.g. whether the performed operation throws an exception). So it is not uncommon to have an HTTP status code of 200, but the contained JSON response(s) indicate some errors.

I.e. the status has a code in the range 400 .. 499 or 500 .. 599 as it is specified for HTTP return codes. The error member contains an error description. This is typically the message of an exception occured on the agent side^[10]. Finally, error_type contains the Java class name of the exception occured. The stacktrace contains a Java stacktrace occured on the server side (if any stacktrace is available).

For each type of operation, the format of the value entry is explained in Section 6.2, “Jolokia operations”

Before we come to the Jolokia operation, the general concept of inner pathes requires some explanation.

An inner path points to a certain substructure (plain value, array, hash) within a a complex JSON value. Think of it as something like "XPath lite". This is best explained by an example:

The attribute HeapMemoryUsage of the MBean java.lang:type=Memory can be requested with the URL http://localhost:8080/jolokia/read/java.lang:type=Memory/HeapMemoryUsage which returns a complex JSON structure like

 {
   "committed" : 18292736,
   "used" : 15348352,
   "max" : 532742144,
   "init" : 0
 }

In order to get to the value for used heap memory you should specify an inner path used, so that the request http://localhost:8080/jolokia/read/java.lang:type=Memory/HeapMemoryUsage/used results in a response of 15348352. If the attribute contains arrays at some level, use a numeric index (0 based) as part of the inner path if you want to traverse into this array.

For both, GET and POST requests, pathes must be escaped as described in Table 6.1, “Escaping rules” when they contain slashes (/) or exclamation marks (!).

Reading MBean attributes is probably the most used JMX method, especially when it comes to monitoring. Concerning Jolokia, it is also the most powerful one with the richest semantics. Obviously the value of a single attribute can be fetched, but Jolokia supports also fetching of a list of given attributes on a single MBean or even on multiple MBeans matching a certain pattern.

Reading attributes are supported by both kinds of requests, GET and POST.

A read request for multiple attributes on the same MBean is initiated by giving a list of attributes to the request. For a POST request this is an JSON array, for a GET request it is a comma separated list of attribute names (where slashes and exclamation marks must be escaped as described in Table 6.1, “Escaping rules”). If no attribute is provided, then all attributes are fetched. The MBean name can be given as a pattern in which case the attributes are read on all matching MBeans. If a MBean pattern and multiple attributes are requestes, then only the value of attributes which matches both are returned, the others are ignored. Pathes cannot be used with multi value reads, though.

<base-url>/read/<mbean name>/<attribute name>/<inner path>

http://localhost:8080/jolokia/java.lang:type=Memory/HeapMemoryUsage/used

{ 
   "type":"read",
   "mbean":"java.lang:type=Threading",
   "attribute":"ThreadCount"
}

http://localhost:8080/jolokia/read/java.lang:type=Memory/HeapMemoryUsage/

 {
   "value":{
             "init":134217728,
             "max":532742144,
             "committed":133365760,
             "used":19046472
           },
   "status":200,
   "timestamp":1244839118,
   "request":{
               "mbean":"java.lang:type=Memory",
               "type":"read",
               "attribute":"HeapMemoryUsage"
             },
   "history":[{"value":{
                         "init":134217728,
                         "max":532742144,
                         "committed":133365760,
                         "used":18958208
                       },
               "timestamp":1244839045
             }, ....
             ]
 }

{
 "timestamp": 1317151518,
 "status": 200,
 "request": {"mbean":"java.lang:type=Memory","type":"read"},
 "value":{
   "Verbose": false,
   "ObjectPendingFinalizationCount": 0,
   "NonHeapMemoryUsage": {"max":136314880,"committed":26771456,"init":24317952,"used":15211720},
   "HeapMemoryUsage": {"max":129957888,"committed":129957888,"init":0,"used":2880008}
 }
}

{
 "timestamp": 1317151980,
 "status": 200,
 "request": {"mbean":"java.lang:type=*","attribute":"HeapMemoryUsage","type":"read"},
 "value": { 
    "java.lang:type=Memory": { 
      "HeapMemoryUsage": {"max":129957888,"committed":129957888,"init":0,"used":3080912}
    }
 }
}

Writing an attribute is quite similar to reading one, except that the request takes an additional value element.

<base url>/write/<mbean name>/<attribute name>/<value>/<inner path>

http://localhost:8080/jolokia/write/java.lang:type=Memory/Verbose/true

http://localhost:8080/jolokia/write/java.lang:type=ClassLoading/Verbose/true

 { 
   "value":"false",
   "status":200,
   "request": {
                "mbean":"java.lang:type=ClassLoading",
                "type":"write",
                "attribute":"Verbose",
                "value":true
              }
 }

Beside attribute provides a way for the execution of exposed JMX operations with optional arguments. The same as for writing attributes, Jolokia must be able to serialize the arguments. See Section 6.4, “Object serialization” for details. Execution of overloaded methods is supported. The JMX specifications recommends to avoid overloaded methods when exposing them via JMX, though.

<base url>/exec/<mbean name>/<operation name>/<arg1>/<arg2>/....

http://localhost:8080/jolokia/exec/java.lang:type=Memory/gc

{
   "type":"EXEC",
   "mbean":"java.lang:type=Threading",
   "operation":"dumpAllThreads",
   "arguments":[true,true]
}

http://localhost:8080/jolokia/exec/java.util.logging:type=Logging/setLoggerLevel/global/INFO

 {
   "value":null,
   "status":200,
   "request": {
                "type":"exec",
                "mbean":"java.util.logging:type=Logging",
                "operation":"setLoggerLevel",
                "arguments":["global","INFO"]
              }
}

With the Jolokia search operation the agent can be queried for MBeans with a given pattern. Searching will be performed on every MBeanServer found by the agent.

<base-url>/search/<pattern>

http://localhost:8080/jolokia/search/*:j2eeType=J2EEServer,*

{ 
   "type":"SEARCH",
   "mbean":"java.lang:*"
}

http://localhost:8888/jolokia/search/*:j2eeType=J2EEServer,*

 {
   "value": [
              "jboss.management.local:j2eeType=J2EEServer,name=Local"
            ],
   "status":200,
   "timestamp":1245305648,
   "request": {
       "mbean":"*:j2eeType=J2EEServer,*","type":"search"
   }
 }

The list operation collects information about accessible MBeans. This information includes the MBean names, their attributes, operations and noticifactions along with type information and description (as far as they are provided by the MBean author which doesn't seem to be often the case).

<base-url>/list/<inner path>

{ 
   "type":"LIST",
   "path":"java.lang/type=Memory"
}

 { 
  <domain> : 
  {
    <prop list> : 
    {
      "attr" : 
      {
        <attr name> : 
        { 
          "type" : <attribute type>,
          "desc" : <textual description of attribute>,
          "rw"   : true/false
        },
        ....
      }, 
      "op" :
      {
         <operation name> :
         {
           "args" : [
                      { 
                       "type" : <argument type>
                       "name" : <argument name>
                       "desc" : <textual description of argument>
                      },
                      .....
                     ],
           "ret"  : <return type>,
           "desc" : <textual description of operation>
         }, 
         .....
      },
      "not" : 
      {
         "name" : <name>,
         "desc" : <desc>,
         "types" : [ <type1>, <type2> ]
      }
    }, 
    ....
  },
  ....
 }

http://localhost:8080/jolokia/list/java.lang/type=Memory

 {
   "value":
   { 
     "op":
     { 
       "gc":
       {
         "args":[],
         "ret":"void",
         "desc":"gc"
       }
     },
     "attr":
     {
       "NonHeapMemoryUsage":
       {
         "type":"javax.management.openmbean.CompositeData",
         "rw":false,
         "desc":"NonHeapMemoryUsage"
       },
       "Verbose":
       {
         "type":"boolean",
         "rw":true,
         "desc":"Verbose"
       },
       "HeapMemoryUsage":
       {
         "type":"javax.management.openmbean.CompositeData",
         "rw":false,
         "desc":"HeapMemoryUsage"
       },
       "ObjectPendingFinalizationCount":
       {
         "type":"int",
         "rw":false,
         "desc":"ObjectPendingFinalizationCount"
       }
     }
   },
   "status":200,
   "request":
   {
     "type":"list",
     "path":"java.lang\/type=Memory"
   }
 }

The Jolokia command version returns the version of the Jolokia agent along with the protocol version.

<base-url>/version

 {
    "timestamp":1287143106,
    "status":200,
    "request":{"type":"version"},
    "value":{
              "protocol":"4.0",
              "agent":"0.80",
              "info": {
                 product: "glassfish",
                 vendor": "Sun",
                 extraInfo: {
                    amxBooted: false
                 }
             }
 }

protocol in the response value contains the protocol version used, agent ist the version of the Jolokia agent. See Section 6.7, “Jolokia protocol versions” for the various protocol versions and the interoperatibility. If the agent is able to detect the server, additional meta information about this server is returned (i.e. the product name, the vendor and optionally some extra information added by the server detector).

Jolokia can serialize any object into a JSON representation when generating the response. It uses some specific converters for certain well known data type with a generic bean converter as fallback.

The following types are directly supported:

Primitive and simple types (like String) are directly converted into their string presentation. All objects not covered by the list above are serialized in JSON objects, where the keys are the public bean properties of the object and the values are serialized (recursively) as described.

Serialization can be influenced by certain processing parameters given with the request (see Section 6.3, “Processing parameters”). I.e. the recursive process of JSON serialization can be stopped when the data set gets too large. Self and other circular references are detected, too. If this happen, special values indicate the truncation of the generated JSON object.

Serialization in the upstream direction (i.e. when sending values for write operations or arguments for exec operations) differs from from the object serializaton as used as response values which is described in Section 6.4.1, “Response value serialization”. Not all types are supported for upstream serialization ^[11] and the capabilities differ also for POST and GET requests. GET upstream serialization is limited to basic types and simple arrays. POST requests on the other support a much large set of types, including the serialization of Maps, Lists and all Open Types.

The MXBean Framework is availale in the JRE since version 6 and allows for easy creation and registration of own MBeans. MXBeans are some what the successor for standard MBeans and support an annotation driven as well as a naming convention driven programming model. The most important difference to standard MBeans it the restriction of MXBean to reference only open types.

Although to the outside only open types are exposed by the MXBean framework, MXBean themselves can use more complex data types. The framework will translate forth and back between the custom and open types according to certain rules as declared in the MXBean specification. Most of the translations to open types fits naturally to Jolokia's serialization, except for the translation of Map.

When an MXBean references a map, the MXBean framework translates this map into a TabularData with a fixed internal structure, i.e. with an index key and rows with keys key and value. This leads directly to a JSON representation which is quite artificial. E.g a map with two keys kind and hotness will be converted by the MXBean framework to a TabularData object which in turn would be translated by Jolokia to the following JSON struture

{
  "kind" : { 
             "key": "kind",
             "value": "Habanero"
           }, 
  "hotness" : {
                "key": "hotness",
                "value": 10
              }
}

Since this representation of a simple map is unnecessarily complicated, Jolokia treats TabularData of this kind (i.e. one index key and rows with properties key and value) specially in order to translate it back (and forth) to

{
  "kind" : "Habanero", 
  "hotness" : 10
}