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. 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-adminSince /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> /resin-admin summary tabThe 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. TCP portsThe 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 BalancingThe 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. /resin-admin config tabThe 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 tabThe 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 tabThe 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 tabThe 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. Interpreting the proxy cache hit ratioThe 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.
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.
Instrumenting a beanResin will automatically register any servlet which implements an MBean interface. By default, the JMX name will be: resin:name=,type= ,Host= ,WebApp=
The domain is , 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 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 ResourcesThe 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 system properties. For example, 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" tabEnter 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. Enabling SNMP support in ResinTo 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: <protocol class="com.caucho.server.snmp.SnmpProtocol" port="161"> <init community="insert_password_here"/> <protocol/> MIB VariablesInternally, 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 mappingsTo define your own MIB variables, you'll need to extend the 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)); } } is the SNMP ID you choose to give to your mapping. It should be in dot notation. 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.
|