<document>
<localtoc/>

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.

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 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>

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

See com.caucho.management.server JavaDoc.

- BlockManagerMXBean - performance data for the proxy cache, clustered sessions, and JMS queues.
- ConnectionPoolMXBean - JDBC database pools.
- HostPoolMXBean - virtual host management.
- JmsQueueMXBean - jms queue management.
- JmsTopicMXBean - jms topic management.
- LoggerMXBean - java.util.logging management.
- PortMXBean - http, https, and custom TCP ports.
- ProxyCacheMXBean - Resin's integrated proxy cache.
- ResinMXBean - Parent MXBean for Resin corresponding to the <resin> configuration tag.
- ServerConnectorMXBean - client view of a peer server in a cluster.
- ServerMXBean - information about the JVM server instance.
- SessionManagerMXBean - information about a web-app's session manager.
- ThreadPoolMXBean - information about Resin's internal thread pool.
- WebAppMXBean - information about a Resin web-app.

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.

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

<def> resin:name=name,type=type,Host=name,WebApp=name </def>
Attribute Value
type The FooMBean name minus the MBean, e.g. "Foo"
name the bean's name value
Host the virtual host name
WebApp the 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.

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++; } }

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"; ?>

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.

<resin xmlns="http://caucho.com/ns/resin"> <cluster id=""> <server-default> <jvm-arg>-Dcom.sun.management.jmxremote</jvm-arg> </server-default> ... </cluster> </resin> win> jconsole.exe unix> jconsole Choose Resin's JVM from the "Local" list. <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.

<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> win> jconsole.exe unix> jconsole Enter the host name and port number (9999) on the "Remote" tab $ 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 <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> win> jconsole.exe unix> jconsole

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

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.

<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>

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.

To enable Resin's SNMP service, you'll need to add an SNMP protocol tag to your resin.conf 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: <example> <protocol class="com.caucho.server.snmp.SnmpProtocol" port="161"> <init community="insert_password_here"/> <protocol/>

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 Object ID SNMP type MBean MBean attribute
1.3.6.1.2.1.1.1 Octet String resin:type=Resin Version
1.3.6.1.2.1.1.3 Time Ticks java.lang:type=Runtime UpTime
1.3.6.1.2.1.1.5 Octet String resin:type=Host,name=default URL
1.3.6.1.4.1.30350.1.1 Gauge resin:type=Server KeepaliveCountTotal
1.3.6.1.4.1.30350.1.2 Gauge resin:type=Server RequestCountTotal
1.3.6.1.4.1.30350.1.3 Gauge resin:type=Server RuntimeMemory
1.3.6.1.4.1.30350.1.4 Gauge resin:type=Server RuntimeMemoryFree
1.3.6.1.4.1.30350.1.5 Gauge resin:type=Server ThreadActiveCount
1.3.6.1.4.1.30350.1.6 Gauge resin:type=Server ThreadKeepaliveCount
1.3.6.1.4.1.30350.2.1 Gauge resin:type=ThreadPool ThreadActiveCount
1.3.6.1.4.1.30350.2.2 Gauge resin:type=ThreadPool ThreadCount
1.3.6.1.4.1.30350.2.3 Gauge resin:type=ThreadPool ThreadIdleCount
1.3.6.1.4.1.30350.2.4 Gauge resin:type=ThreadPool ThreadIdleMax
1.3.6.1.4.1.30350.2.5 Gauge resin:type=ThreadPool ThreadIdleMin
1.3.6.1.4.1.30350.2.6 Gauge resin:type=ThreadPool ThreadMax
1.3.6.1.4.1.30350.3.1 Gauge resin:type=ProxyCache HitCountTotal
1.3.6.1.4.1.30350.3.2 Gauge resin:type=ProxyCache MissCountTotal

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:

<deftable>
SNMP types Description
SnmpValue.OCTET_STRING 8-bit String
SnmpValue.INTEGER signed 32-bit integer
SnmpValue.COUNTER unsigned 32-bit integer that only increases, wraps around when overflows
SnmpValue.GAUGE unsigned 32-bit integer that may increase and decrease
SnmpValue.TIME_TICKS unsigned 32-bit integer representing time measured in hundredths of a second
SnmpValue.IP_ADDRESS IP address

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

</document>