Caucho Technology
documentation
examples
changes

overview
quick start
installation
command-line
configuration
admin
amber
clustering
caching
database
deployment
ejb 3.0
embedding
filters
hessian
hmtp
ioc
jsp
logging
messaging
performance
quercus/php
remoting
scheduled tasks
security
server push
servlets
third-party
troubleshooting
virtual hosting
watchdog
webapp
xml and xslt

resin administration


The /resin-admin web-app provides an administration overview of a Resin server. Resin-Pro users can obtain information across the entire cluster, profile a running Resin instance, and obtain thread dumps and heap dumps.

All Resin users should familiarize themselves with the thread dump, profile, and heap capabilities.

/resin-admin web-app

The /resin-admin web-app provides an administration overview of a Resin server. Resin-Pro users can obtain information across the entire cluster, profile a running Resin instance, and obtain thread dumps and heap dumps.

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.

For security, you will also need to add a <user> to the <management> section of the resin.conf. The password will be a MD5 hash. By default, the /resin-admin web-app provides a form for generating the hash codes. You will need to copy the generated password into the resin.conf. This guarantees that you have access to the resin.conf itself to add any users. In other words, the configuration is very cautious about security issues to enable the administration.

resin.conf /resin-admin configuration
<resin xmlns="http://caucho.com/ns/resin"
       xmlns:resin="http://caucho.com/ns/resin/core">

  <management>
     <user name="harry" password="MD5HASH=="/>
  </management>

<cluster id="">
<host id="">

  <web-app id="/resin-admin" root-directory="${resin.home}/php/admin">
     <prologue>
        <resin:set var="resin_admin_external" value="false"/>
        <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.

Thread pool

The thread pool give the current state of Resin's threads.

TCP ports

The TCP ports gives information about the HTTP, HTTPS, and cluster ports, showing how many threads are active and also how many connections are in various keepalive states.

Server Connectors - Load Balancing

The Server Connectors section is the main section for load balancing. It will give an overview of any failures in connecting to the backend servers, showing the latency and load.

Connection pools - Database pooling

The connection pool section shows the state and history of the database pools.

WebApps

The WebApps shows the current state of the active web-apps for each virtual host. In particular, it will show the time and number of any 500 errors, letting you track down errors in the log files.

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

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

See com.caucho.management.server JavaDoc.

JMX Instrumenting Beans

Resin's IoC container can register the application's services with JMX automatically. The registered beans will then be available in a JMX application like jconsole or through PHP or Java.

  1. For a class MyFoo, create an interface MyFooXMBean with the management interface.
  2. Class MyFoo needs to implement the MyFooMBean interface.
  3. When Resin handles the <bean> tag, it will register MyFoo with the JMX server.

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
ObjectName attributes
ATTRIBUTEVALUE
typeThe FooMBean name minus the MBean, e.g. "Foo"
namethe bean's name value
Hostthe virtual host name
WebAppthe web-app's context path

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.

MyServiceMBean.java
package test;

public interface MyServiceMBean {
  public int getCount();
}
MyServlet.java
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: Getting the Count attribute
<php?

$mbean_server = new MBeanServer();

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

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

?>

JMX Console

JDK 5.0 includes a JMX implementation that is used to provide local and remote administration of a Resin server. The JVM will expose JMX if it's started with appropriate -D system properties. For example, -Dcom.sun.management.jmxremote will expose JMX to the local machine.

To configure the JVM arguments for Resin, you'll add a <jvm-arg> to the resin.conf. When Resin's Watchdog process starts Resin, it will pass along the configured arguments, enabling JMX administration.

Start Resin and allow local JMX administration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>
Start jconsole
win> jconsole.exe
unix> jconsole

Choose Resin's JVM from the "Local" list.
Start Resin and allow remote JMX administration
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote.port=9999</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>

Without some configuration effort, the previous command will not work. Password configuration and SSL configuration is required by the JDK implementation of remote JMX. Detailed instructions are included in the JDK documentation.

The following is useful for testing, but should be done with caution as the port is not protected by password or by SSL, and if not protected by a firewall is accessible by anyone who can guess the port number.

Start Resin and remote JMX - disable password checking and SSL
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote.port=9999</jvm-arg>
    <jvm-arg>-Dcom.sun.management.jmxremote.ssl=false</jvm-arg>
    <jvm-arg>-Dcom.sun.management.jmxremote.authenticate=false</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>
Start jconsole
win> jconsole.exe
unix> jconsole

Enter the host name and port number (9999) on the "Remote" tab
Setting a password for remote JMX access
$ cd $JAVA_HOME/jre/lib/management
$ cp jmxremote.password.template jmxremote.password
$ chmod u=rw jmxremote.password
$ vi jmxremote.password

Set a password for "monitorRole" and "controlRole":

monitorRole 12monitor
controlRole 55control
Start Resin and remote JMX - disable SSL
<resin xmlns="http://caucho.com/ns/resin">
<cluster id="">

  <server-default>
    <jvm-arg>-Dcom.sun.management.jmxremote.port=9999</jvm-arg>
    <jvm-arg>-Dcom.sun.management.jmxremote.ssl=false</jvm-arg>
  </server-default>

  ...

</cluster>
</resin>
Start jconsole
win> jconsole.exe
unix> jconsole

Enter the host name and port number (9999) on the "Remote" tabEnter the username and password on the "Remote" tab

stat-service

Resin 3.1.6 adds a new <stat-service> to the <management tag. The <stat-service periodically checks the status of Resin and the JVM and can act if certain thresholds are exceeded. The default check rate is every 60s.

The primary statistic that <stat-service> observes is the CPU load of the server. You can set thresholds so Resin will log a thread dump if the CPU gets high, e.g. to find and debug a runaway thread. If necessary, you can also have Resin restart if the CPU load gets too high. The configuration is documented in <management> in the resin-tags section.

Example: CPU thresholds
<resin xmlns="http://caucho.com/ns/resin">
  <management>
    <stat-service>
      <cpu-load-exit-threshold>10.0</cpu-load-exit-threshold>
      <cpu-load-log-info-threshold>1.0</cpu-load-log-info-threshold>
      <cpu-load-log-warning-threshold>2.0</cpu-load-log-warning-threshold>
      <cpu-load-thread-dump-threshold>2.0</cpu-load-thread-dump-threshold>
      <sample-period>15s</sample-period>
      <thread-dump-interval>10m</thread-dump-interval>
    </stat-service>
  </management>

</resin>

SNMP

Since 3.1.5, Resin has built-in support for SNMP (Simple Network Management Protocol). This allows Resin to be managed just like any network device (e.g. routers) from an SNMP manager application.

Enabling SNMP support in Resin

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

resin.conf
<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:

SNMP to MBean mappings
SNMP OBJECT IDSNMP TYPEMBEANMBEAN ATTRIBUTE
1.3.6.1.2.1.1.1Octet Stringresin:type=ResinVersion
1.3.6.1.2.1.1.3Time Ticksjava.lang:type=RuntimeUpTime
1.3.6.1.2.1.1.5Octet Stringresin:type=Host,name=defaultURL
1.3.6.1.4.1.30350.1.1Gaugeresin:type=ServerKeepaliveCountTotal
1.3.6.1.4.1.30350.1.2Gaugeresin:type=ServerRequestCountTotal
1.3.6.1.4.1.30350.1.3Gaugeresin:type=ServerRuntimeMemory
1.3.6.1.4.1.30350.1.4Gaugeresin:type=ServerRuntimeMemoryFree
1.3.6.1.4.1.30350.1.5Gaugeresin:type=ServerThreadActiveCount
1.3.6.1.4.1.30350.1.6Gaugeresin:type=ServerThreadKeepaliveCount
1.3.6.1.4.1.30350.2.1Gaugeresin:type=ThreadPoolThreadActiveCount
1.3.6.1.4.1.30350.2.2Gaugeresin:type=ThreadPoolThreadCount
1.3.6.1.4.1.30350.2.3Gaugeresin:type=ThreadPoolThreadIdleCount
1.3.6.1.4.1.30350.2.4Gaugeresin:type=ThreadPoolThreadIdleMax
1.3.6.1.4.1.30350.2.5Gaugeresin:type=ThreadPoolThreadIdleMin
1.3.6.1.4.1.30350.2.6Gaugeresin:type=ThreadPoolThreadMax
1.3.6.1.4.1.30350.3.1Gaugeresin:type=ProxyCacheHitCountTotal
1.3.6.1.4.1.30350.3.2Gaugeresin:type=ProxyCacheMissCountTotal

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

SNMP TYPESDESCRIPTION
SnmpValue.OCTET_STRING8-bit String
SnmpValue.INTEGERsigned 32-bit integer
SnmpValue.COUNTERunsigned 32-bit integer that only increases, wraps around when overflows
SnmpValue.GAUGEunsigned 32-bit integer that may increase and decrease
SnmpValue.TIME_TICKSunsigned 32-bit integer representing time measured in hundredths of a second
SnmpValue.IP_ADDRESSIP address

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


Copyright © 1998-2008 Caucho Technology, Inc. All rights reserved.
Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.