Jolokia JMX connectivity in OSv

Jolokia JMX Connectivity in OSv

By Calle Wilund

OSv is a great way to run Java applications in the cloud, and it recently became just a little bit better. As you are probably aware, OSv exposes quite a bit of information and manageability options through its RESTful API, accessible through the built-in HTTP server. More or less from its inception, this API has exposed various aspects of the JVM and the Java Management Beans provided.

Recently we improved on this a bit by including the Jolokia JMX-via-JSON-REST connector, providing full read/write access to the entire set of Java manageability attributes and operations. Now you no longer need to set up and secure separate JMX-over-RMI connectivity with your Java application to fully manage it.

The Jolokia API is available via the OSv REST server at http[s]://<OSv host>:<port>/jolokia. You can explore this and other API:s via the Swagger UI. For a better understanding of the full Jolokia syntax, I suggest reading through the reference manual. In its simplest form, querying a Java Management Bean value from an OSv instance can be done like this:

1
> curl http://<ip>:<port>/jolokia/read/java.lang:type=Memory/HeapMemoryUsage

With the result of something like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{   
  "timestamp"   :1409065190,
  "status"  :200,
  "request" : {
          "mbean"       :"java.lang:type=Memory",
          "attribute"   :"HeapMemoryUsage",
          "type"        :"read"
          },
  "value"       : {
          "max"     :1839202304,
          "committed"   :1839202304,
          "init"        :1918894080,
          "used"        :192117128
          }
}

Jolokia provides a full syntax for packaging JMX bean information inside JSON objects, including the ability to batch requests. It also provides client connector libraries for Java, Perl and JavaScript to access them easily from (web) applications.

Important note about REST requests and browser security

Most browsers today enforce that resources such as REST queries may only be made to the same domain as the requesting web page. When you want to allow cross-domain requests you need to either turn off this security feature in your browser (for Google Chrome you can run it with --disable-web-security, however if you use Firefox I do not know of any way to do it), or enable CORS in OSv.

To do the latter, you need to provide a httpserver configuration section in your cloud init settings. To simply allow all domains to make requests to the OSv APIs, add this to your configuration:

1
2
httpserver:
    access-allow: '*'

And make this reachable through your cloud-init server. (Or use the EC2 simulator script provided with OSv).

A small demo

A small demo JavaScript application showing how to easily plot various JVM graphs from a running OSv instance can be found at https://github.com/elcallio/jolokia-demo (which is a modified fork of the Jolokia demo created by Tomasz Nurkiewicz.

To test the demo, simply clone the repository and edit the src/js/osvhost.js to match the IP address and port for your OSv instance. (Don’t forget to make sure that your OSv image includes the HTTP server).

Since I am runnning OSv compiled from source, I simply go to my OSv source tree and type:

1
> make image=httpserver,mgmt

…<chug, chug, chug> And when it is done:

1
> ./scripts/run.py --api

This will build and start an almost empty image, containing only the HTTP server, cloud init support and the Java-based shell (not a very interesting appliance, I admit, but you can pick any image you prefer). Running like this, the REST API is available from http://localhost:8000, so this is what I enter into src/js/osvhost.js.

Then load the jolokia-demo/src/index.html in your favourite browser, and you should be greeted by this:

screenshot

As you can see, the demo provides the start of a small management console for Java with just a few lines of Javascript code, most of which actually deal with setting up the charts. Requesting and polling the actual data on the other hand is almost ridiculously easy.

Having Jolokia integrated in the OSv manageability layer means that not only can you access all the JMX attributes parallel with the rest of the exposed OSv aspects, not having to modify Java appliances, but also that you only need to deal with securing a single service point.

This is just one small aspect of all the new and exciting manageability features that are in or coming to OSv. Over the next few months we hope to bring you additional aspects that will further enhance your deployment experience. Stay tuned.

If you have any questions on OSv management, please join the osv-dev mailing list. You can get general updates by subscribing to this blog’s feed, or folllowing @CloudiusSystems on Twitter.

Comments