Jetty/Reference/jetty-monitor

Introduction

Jetty-monitor module enables developers and system administrators to monitor Jetty-based servers.

• It can run either inside a Jetty process or as a standalone Java application.
• You can use it to monitor both regular and embedded Jetty servers.

Jetty-monitor is a consumer of Jetty JMX integration, allowing it to access MBeans that supply statistical and runtime information about Jetty components and web applications, as well as Java Virtual Machine itself. You can configure it to execute actions if trigger condition(s) that you specify in MBean attribute value(s) are satisfied, as well as to call notifier(s) when it executes such actions. Currently, we provide only one action that calls the configured notifiers, and only logging and console output notifiers out of the box, but you can easily add custom actions and notifiers.

Jetty-monitor includes an integration with Java-monitor service via a custom action. This integration enables posting the data about the server to a Java-monitor account, and using it to monitor the server remotely, as well as gathering information about server performance and outages.

Enabling Jetty Monitor

To use the monitor module, the jetty-monitor jar must be on the classpath and the jetty-monitor.xml file should be included as a configuration file. If using start.jar this can be achieved by adding "monitor" to the OPTIONS either on the command line:

java -jar start.jar OPTIONS=monitor etc/jetty-monitor.xml

or in start.ini:

OPTIONS=Server,jsp,jmx,resources,websocket,ext,monitor
etc/jetty-monitor.xml

Jetty monitor also makes use of jetty-jmx, so it must also be enabled and configured.

Configuring the In-process Monitor

You can configure Jetty-monitor using the standard jetty.xml configuration file syntax. The following is an example of the jetty-monitor configuration file for the in-process monitor. It creates a monitor action (SimpleAction) that executes when the number of idle threads in Jetty's main thread pool is less than or equal to four, or greater than seven. When this action executes, it invokes a console notifier that outputs the message to the console.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
 
<Configure id="Monitor" class="org.mortbay.jetty.monitor.JMXMonitor">
  <Call name="addActions">
    <Arg>
      <Array type="org.mortbay.jetty.monitor.MonitorAction">
        <Item>
          <New class="org.mortbay.jetty.monitor.SimpleAction">
            <Arg>
              <New class="org.mortbay.jetty.monitor.triggers.OrEventTrigger">
                <Arg>
                  <Array type="org.mortbay.jetty.monitor.EventTrigger">
                    <Item>
                      <New
                        class="org.mortbay.jetty.monitor.triggers.LessThanOrEqualToAttrEventTrigger">
                        <Arg>org.eclipse.jetty.util.thread:type=queuedthreadpool,id=0
                        </Arg>
                        <Arg>idleThreads</Arg>
                        <Arg type="java.lang.Integer">4</Arg>
                      </New>
                    </Item>
                    <Item>
                      <New
                        class="org.mortbay.jetty.monitor.triggers.GreaterThanAttrEventTrigger">
                        <Arg>org.eclipse.jetty.util.thread:type=queuedthreadpool,id=0
                        </Arg>
                        <Arg>idleThreads</Arg>
                        <Arg type="java.lang.Integer">7</Arg>
                      </New>
                    </Item>
                  </Array>
                </Arg>
              </New>
            </Arg>
            <Arg>
              <New class="org.mortbay.jetty.monitor.ConsoleNotifier">
                <Arg>%s</Arg>
              </New>
            </Arg>
            <Arg type="java.lang.Long">500</Arg>
          </New>
        </Item>
      </Array>
    </Arg>
  </Call>
</Configure>

Starting the In-process Monitor

To use jetty-monitor inside the Jetty server process, add it to the server classpath by copying it into {jetty.home}/lib/ext directory. To enable jetty-monitor for your server, you can either specify the jetty-monitor configuration file on the command line as follows, or add the name of this file to the end of the start.ini configuration file.

java -jar start.jar <mymonitor.xml>

Configuring the Standalone Monitor

The configuration file for the standalone jetty-monitor uses the same format as the in-process monitor does. For jetty-monitor to be able to connect to the Jetty server you want it to monitor, the configuration file must specify the URL for the remote JMX connector as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
 
<Configure id="Monitor" class="org.mortbay.jetty.monitor.JMXMonitor">
  <Call name="setUrl">
    <Arg>service:jmx:rmi://localhost/jndi/rmi://localhost:1099/jettyjmx</Arg>
  </Call>
  ...
</Configure>

Starting Standalone Application Monitor

To start jetty-monitor as a standalone application, run the following command from the command line. You must specify

• The jetty-monitor configuration file.
• The URL for the remote connector.

java -cp jetty-all-server-[version].jar -jar jetty-monitor-[version].jar org.eclipse.jetty.monitor.JMXMonitor <monitor.xml>

Thread Monitor

The jetty-monitor package also provides the org.eclipse.jetty.monitor.ThreadMonitor class, which can monitor threads for excessive CPU usage and spinning in situ. The default jetty-monitor.xml file is normally setup to contain a ThreadMonitor like:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
  <!-- Create Thread Monitor, and add to the Server as a lifecycle -->
  <Call name="addBean">
    <Arg>
      <New class="org.eclipse.jetty.monitor.ThreadMonitor">
        <Set name="scanInterval">2000</Set>
        <Set name="busyThreshold">90</Set>
        <Set name="stackDepth">5</Set> <!-- how much of the stack trace is compared for spinning check -->
        <Set name="trailLength">4</Set><!-- how many stack traces to log -->
        <!-- To enable logging CPU utilization for threads above specified threshold, -->
        <!-- uncomment the following lines, changing log interval (in milliseconds)  -->
        <!-- and log threshold (in percent) as desired.                              -->
        <Set name="logInterval">10000</Set>
        <Set name="logThreshold">65</Set>
 
        <!-- To enable detail dump of the server whenever a thread is detected as spinning, -->
        <!-- uncomment the following lines. -->
        <Set name="dumpable"><Ref id="Server"/></Set>
      </New>
    </Arg>
  </Call>
</Configure>

Additional Resources

See Jetty JMX tutorial for instructions on how to configure Jetty JMX integration.

See jetty.xml syntax reference for more information on configuration file syntax.