/resin-admin web-app

Configuring /resin-admin

Since /resin-admin is just a web-app implemented with Quercus/PHP, enabling it is just adding an appropriate <web-app> tag.

To enable the /resin-admin, you'll need to create an admin user and password.

1. Create an admin user following the prompt at /resin-admin.
2. Copy the conf/admin-users.xml.generated to conf/admin-users.xml.
3. Change the resin_admin_external to true if you need access from a non-local IP address.
4. Browse /resin-admin with an HTML 5 browser.

The steps are for security reasons. Copying the admin-users.xml verifies that you have access to the server. And the default resin_admin_external=false makes sure you're not exposing the /resin-admin to the internet.

<resin:AdminAuthenticator xmlns="http://caucho.com/ns/resin"
                          xmlns:resin="urn:java:com.caucho.resin">
  <user name="admin" password="{SSHA}h5QdSulQyqIgYo7BIJ3YfnRSY56kD847"/>
  <user name="resin" password="{SSHA}J0y0dlG2uRKT83g3OfzEjFNTIaTHVsA9"/>
</resin:AdminAuthenticator>

<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="urn:java:com.caucho.resin">

  ...

  <web-app id="/resin-admin" root-directory="${resin.root}/doc/admin">
     <prologue>
        <!-- allow access from any IP address -->
        <resin:set var="resin_admin_external" value="true"/>
        <resin:set var="resin_admin_insecure" value="true"/>
     </prologue>
  </web-app>

</host>
</cluster>
</resin>

/resin-admin summary tab

The summary tab provides a basic overview of the Resin instance. Resin-Pro users can see the summary page of each server in a cluster.

The overview section shows basic configuration information like the server-id, Resin version, Resin home, memory information, and how long the instance has been up. It's useful as a basic check to verify the configuration and see if the server is having any problems.

/resin-admin config tab

The config tag summarizes Resin's internal configuration. This tab can be useful to double-check that the values in the resin.xml and web.xml match the expected values.

/resin-admin threads tab

The threads tab is a critical debugging tab. It shows the state and stack trace of every thread in the JVM, grouped by functionality. If the server ever freezes or moves slowly, use the thread tab as your first resource for figuring out what's going on in the system.

All Resin users should familiarize themselves with the thread dump for their application. It's very important to understand the normal, baseline status, so if something does go wrong, you'll know what looks different.

In particular, any freeze or slowness of Resin should immediately suggest looking at the thread page.

/resin-admin cpu profile tab

The cpu profile tab lets you gather basic profiling information on a running Resin server. Because the overhead is low, it's even possible to run a profile on a deployment server, which will give much better information about the performance of your system than any artificial benchmarks.

With Resin's integrated profiling, there's no excuse to skip the profiling step for your application.

/resin-admin heap dump tab

The heap dump tab lets you gather a heap memory information at any time, giving you critical information at times when you may not have a dedicated profiler available.

/resin-admin Custom Configuration

Admin topics

Interpreting the proxy cache hit ratio

The proxy cache is Resin's internal proxy cache (in Resin Pro). The hit ratio marks what percentage of requests are served out of the cache, i.e. quickly, and which percentage are taking the full time.

The proxy cache hit ratio is useful for seeing if you can improve your application's performance with better caching. For example, if you had a news site like www.cnn.com, you should have a high hit rate to make sure you're not overtaxing the database.

If you have a low value, you might want to look at your heavily used pages to see if you can cache more.

Resin's JMX Interfaces

JMX Instrumenting Beans

Instrumenting a bean

Resin will automatically register any servlet which implements an MBean interface. By default, the JMX name will be:

resin:name=name,type=type,Host=name,WebApp=name

The domain is web-app, the type property is calculated from the MBean class name and the name property is the value of <name>.

JMX clients will use the name to manage the bean. For example, a client might use the pattern web-app:type=Foo,* to retrieve the bean.

package test;

public interface MyServiceMBean {
  public int getCount();
}

package test;

import java.io.*;
import javax.servlet.*;

public class MyService implements MyServiceMBean
{
  private int _count;

  public int getCount()
  {
    return _count;
  }

  public void doStuff()
  {
    _count++;
  }
}

PHP: Displaying and Managing Resources

The easiest way to display and manage JMX is with PHP. The /resin-admin web-app provides several examples of getting JMX data.

<php?

$mbean_server = new MBeanServer();

$service = $mbean_server->query("resin:*,type=MyService");

echo "Service.count: " . $service[0]->Count . "\n";

?>

JMX Console

SNMP

Enabling SNMP support in Resin

To enable Resin's SNMP service, you'll need to add an SNMP protocol tag to your resin.xml under the <server> tag:

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="">
    <server-default>
    
      <protocol class="com.caucho.server.snmp.SnmpProtocol" port="161"/>
      
    <server-default/>
    
    ...
    
  <cluster/>
<resin/>

This opens up a port that listens for SNMP requests and responds to them with an SNMP response. Currently, Resin can only respond to TCP SNMP get-pdu requests.

By default, the SNMP community string is "public". It can be changed with:

<protocol class="com.caucho.server.snmp.SnmpProtocol" port="161">
  <init community="insert_password_here"/>
<protocol/>

MIB Variables

Internally, Resin stores a mapping from SNMP MIB variables to MBean attributes. Requests for a specific MIB variable are simply retrievals for the corresponding MBean attribute. The available MIB mappings are hard-coded in Resin and they are:

Defining your own SNMP to MBean mappings

To define your own MIB variables, you'll need to extend the com.caucho.server.snmp.SnmpProtocol class and then use that class name in the <protocol> tag:

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="">
    <server-default>
    
      <protocol class="example.MySnmpProtocol" port="161"/>
      
    <server-default/>
    
    ...
    
  <cluster/>
<resin/>

package example;

import com.caucho.server.snmp.*;
import com.caucho.server.snmp.types.*;

public class MySnmpProtocol extends SnmpProtocol
{
  public MySnmpProtocol()
  {
    super();
  
    addOid(new Oid("1.2.3.4.5",
                   "my_mbean_object_name",
                   "my_mbean_attribute",
                   SnmpValue.OCTET_STRING));
  }
}

"1.2.3.4.5" is the SNMP ID you choose to give to your mapping. It should be in dot notation. SnmpValue.OCTET_STRING is the type Resin should return for that attribute. An abbreviated list of the available types are:

For a more complete list, see com.caucho.server.snmp JavaDoc.