Latest revision as of 00:00, 21 March 2013

Custom REST Pages

Resin actually provides 2 REST interfaces; a newer REST service which enables administration that mirrors Resin's command-line interface, and older customizable REST pages as part of the resin-admin web application.

The newer REST interface is documented thoroughly in the Resin documentation and usage examples are on the Wiki also.

rest.php

rest.php, located at doc/admin/rest.php is a component of resin-admin that allows you to easy extend and customize resin-admin. Resin admin actually uses it to enable part of the graphing capability.

rest.php requires one parameter "q", which is the name of a rest page to display. rest pages are located in resin-admin's WEB-INF/php/ directory and named with the extension ".rest".

resin-admin as packaged includes 2 .rest pages for your use, or you can add your own additional .rest pagesto this directory.

mod_status.rest

http://127.0.0.1:8080/resin-admin/rest.php?q=mod_status

This .rest page produces output similar to Apache's mod_status.

graph.rest

http://127.0.0.1:8080/resin-admin/rest.php?q=graph

This .rest page produces an interactive graph drawn using javascript. It's intended to be embeddable in your own pages or can just be used as an example of how to write .rest pages.

With no parameters, graph.rest will produce no graph. The parameters are as follows:

• checks: a comma separated list of Resin meter name to graph (required)
• servers: a comma separated list of Resin server cluster indexes, typically 00 though xx (defaults to the local server)
• width: graph width (defaults to 640)
• height: graph height (defaults t 480)
• canvas: name of html 5 canvas DIV on to draw on (defaults to generated named)
• period: graph domain, in seconds since the current time (defaults to 60)

For example, this URL will produce a graph of the number of JVM threads over the last hour for the current server:

http://127.0.0.1:8080/resin-admin/rest.php?q=graph&checks=JVM|Thread|JVM%20Thread%20Count&period=3600

Each Resin server in a cluster actually has access to the stats from the other servers, making cluster graphing possible, as shown in this example:

http://127.0.0.1:8080/resin-admin/rest.php?q=graph&checks=JVM|Thread|JVM%20Thread%20Count,Resin|Thread|Thread%20Count&servers=00,01

The "checks" parameter accepts the names of a Resin Meters. Resin tracks many metrics while running, and stores these in an internal database. They are named hierarchy with keys from least to most specific, separated with a "|" (pipe) character. So in the example above the metric key was "JVM|Thread|JVM Thread Count". There is also a "Resin|Thread|Thread Count". Refer to the Meters page in resin-admin for a more comprehensive list.

Writing a custom REST page

resin-admin only accesses data via JMX. To gather JMX data, you'll create a custom REST page, which is just a PHP page accessing JMX. The page has the extension .rest and can be named whatever you like, e.g. mypage.rest. Put the my-app.rest page in WEB-INF/php/mypage.rest.

Location of mypage.rest

The mypage.rest can be put directly in WEB-INF/php or in a custom location given by "resin_admin_ext_path. We recommend using resin_admin_ext_path so you can keep your extensions distinct from Resin's standard pages. The resin_admin_ext_path is configured in the resin.xml like:

<web-app id="/resin-admin" root-directory="${resin.root}/doc/admin">
 <prologue>
   <resin:set var="resin_admin_external" value="false"/>
   <resin:set var="resin_admin_insecure" value="true"/>
   <resin:set var="resin_admin_ext_path"
              value="/var/resin/admin/php"/>
</prologue>
</web-app>

mypage.rest sample code

The code for a REST page will look like:

<?php

header("Content-Type: text/plain; charset=utf-8");

$mbean_server = new MBeanServer();

$jvm_thread = $mbean_server->lookup("java.lang:type=Threading");

printf("JvmThreadCount: %d\n", $jvm_thread->ThreadCount);

?>

The $mbean_server is a Resin's PHP interface to Java JMX MBeanServer. The lookup($name) method looks up a MBean by its ObjectName. The field reference is a JXM attribute.