Difference between revisions of "Jetty/Tutorial/JMX"

From Eclipsepedia

Jump to: navigation, search
m
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{Jetty Tutorial
 
{{Jetty Tutorial
 
| introduction =
 
| introduction =
This tutorial describes how the Jetty JMX integration can be initialized and configured. The simplest way to access the MBeans that are published by Jetty is to use the [http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html JConsole] utility supplied with Sun's Java Virtual Machine. The steps required to configure Jetty JMX integration will be different depending on the way that Jetty is bootstrapped.
+
This tutorial describes how the Jetty JMX integration can be initialized and configured.
 +
The simplest way to access the MBeans that are published by Jetty is to use the [http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html JConsole] utility supplied with Sun's Java Virtual Machine. See [[Jetty/Howto/Run Jetty_with_JConsole|Run Jetty with JConsole]] for instructions on how to configure JVM for use with JConsole.
 +
 
 
| details =
 
| details =
=== Configure Standalone Jetty   ===
+
=== Configuration ===
 +
There are two main steps that needs to be performed in order to be able to access Jetty's MBeans via JConsole.
 +
 
 +
The first step is enabling the registration of Jetty's MBeans into the platform MBeanServer.
 +
 
 +
The second step is to enable a JMXConnectorServer so that JConsole can connect and visualize the MBeans.
 +
 
 +
=== Enabling Registration of Jetty's MBeans ===
 +
The steps required to configure Jetty JMX integration will be different depending on the way that Jetty is bootstrapped.
  
 +
==== Standalone Jetty  ====
 
When running in standalone mode, the MBeanContainer instance can be configured for a Jetty server by the jetty-jmx.xml configuration file. This can be run with the standard configuration file as follows:
 
When running in standalone mode, the MBeanContainer instance can be configured for a Jetty server by the jetty-jmx.xml configuration file. This can be run with the standard configuration file as follows:
 
  java -jar start.jar OPTIONS=Server,jmx etc/jetty-jmx.xml etc/jetty.xml
 
  java -jar start.jar OPTIONS=Server,jmx etc/jetty-jmx.xml etc/jetty.xml
 
Please make sure that the jetty-jmx.xml is the '''first''' XML file listed in the command line to ensure that all instances of objects that supposed to be registered as MBeans are detected properly.
 
Please make sure that the jetty-jmx.xml is the '''first''' XML file listed in the command line to ensure that all instances of objects that supposed to be registered as MBeans are detected properly.
  
=== Configure Embedded Jetty ===
+
==== Embedded Jetty ====
 
+
 
If Jetty is embedded into an application, the following snippet of code shows how to create and configure an MBeanContainer instance:
 
If Jetty is embedded into an application, the following snippet of code shows how to create and configure an MBeanContainer instance:
 
<source lang="java">
 
<source lang="java">
Line 19: Line 29:
 
_server.getContainer().addEventListener(mbContainer);
 
_server.getContainer().addEventListener(mbContainer);
 
_server.addBean(mbContainer);
 
_server.addBean(mbContainer);
 +
 +
// Register loggers as MBeans
 
mbContainer.addBean(Log.getLog());
 
mbContainer.addBean(Log.getLog());
 
</source>
 
</source>
  
Please note that MBeanContainer is created immediately after the Server is created, and that an MBean is created for it immediately after it is registered as an EventListener of the Server's Container object. Because logging is initialized prior to MBeanContainer, it is necessary to create an MBean for the logger manually as well.
+
Please note that MBeanContainer is created immediately after the Server is created, and immediately after it is registered as an EventListener of the Server's Container object.  
 +
Because logging is initialized prior to the MBeanContainer, it is necessary to register the logger manually - via MBeanContainer.addBean().
  
=== Configure Jetty Maven Plugin  ===
+
==== Jetty Maven Plugin  ====
 
+
If you are using the [http://wiki.eclipse.org/Jetty/Feature/Jetty_Maven_Plugin Jetty Maven plugin] you should copy the etc/jetty-jmx.xml file into your webapp project somewhere, such as src/etc, then add a &lt;jettyconfig&gt; element to the plugin &lt;configuration&gt;:
If you are using the [http://jetty.mortbay.org/maven-plugin/index.html Jetty Maven plugin] you should copy the etc/jetty-jmx.xml file into your webapp project somewhere, such as src/etc, then add a &lt;jettyconfig&gt; element to the plugin &lt;configuration&gt;:
+
  
 
<source lang="xml">
 
<source lang="xml">
Line 35: Line 47:
 
   <configuration>
 
   <configuration>
 
     <scanintervalseconds>10</scanintervalseconds>
 
     <scanintervalseconds>10</scanintervalseconds>
     <jettyconfig>src/etc/jetty-jmx.xml</jettyconfig>
+
     <jettyXml>src/etc/jetty-jmx.xml</jettyXml>
 
   </configuration>
 
   </configuration>
 
</plugin>
 
</plugin>
 
</source>
 
</source>
  
== Custom Monitor Application ==
+
=== Enabling JMXConnectorServer for Remote Access ===
 +
There are two ways of enabling remote connectivity so that JConsole can connect to visualize MBeans.
 +
 
 +
The first way is to use the "com.sun.management.jmxremote" system property on command line.
 +
Unfortunately, this solution does not play well with firewalls and it is not flexible.
 +
 
 +
The second way is to use Jetty's ConnectorServer class.
 +
To enable usage of this class, just uncomment the correspondent portion in etc/jetty-jmx.xml; it will look like this:
 +
 
 +
<source lang="xml">
 +
<New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
 +
  <Arg>
 +
    <New class="javax.management.remote.JMXServiceURL">
 +
      <Arg type="java.lang.String">rmi</Arg>
 +
      <Arg type="java.lang.String" />
 +
      <Arg type="java.lang.Integer"><SystemProperty name="jetty.jmxrmiport" default="1099"/></Arg>
 +
      <Arg type="java.lang.String">/jndi/rmi://<SystemProperty name="jetty.jmxrmihost" default="localhost"/>:<SystemProperty name="jetty.jmxrmiport" default="1099"/>/jmxrmi</Arg>
 +
    </New>
 +
  </Arg>
 +
  <Arg>org.eclipse.jetty.jmx:name=rmiconnectorserver</Arg>
 +
  <Call name="start" />
 +
</New>
 +
</source>
 +
 
 +
This configuration snippet will start an RMIRegistry and a JMXConnectorServer both on port 1099 (by default), so that firewalls should open just that one port to allow connections from JConsole.
 +
 
 +
==== Securing Remote Access ====
 +
JMXConnectorServer comes with the possibility to restrict access in several ways. For a complete tutorial about controlling authentication and authorization in JMX, see [https://blogs.oracle.com/lmalventosa/entry/jmx_authentication_authorization this tutorial].
 +
 
 +
In order to restrict access to the JMXConnectorServer, you can use this configuration, where the "jmx.password" and "jmx.access" files have the format specified in the tutorial above:
 +
 
 +
<source lang="xml">
 +
<New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
 +
  <Arg>
 +
    <New class="javax.management.remote.JMXServiceURL">
 +
      <Arg type="java.lang.String">rmi</Arg>
 +
      <Arg type="java.lang.String" />
 +
      <Arg type="java.lang.Integer"><SystemProperty name="jetty.jmxrmiport" default="1099"/></Arg>
 +
      <Arg type="java.lang.String">/jndi/rmi://<SystemProperty name="jetty.jmxrmihost" default="localhost"/>:<SystemProperty name="jetty.jmxrmiport" default="1099"/>/jmxrmi</Arg>
 +
    </New>
 +
  </Arg>
 +
  <Arg>
 +
    <Map>
 +
      <Entry>
 +
        <Item>jmx.remote.x.password.file</Item>
 +
        <Item>
 +
          <New class="java.lang.String"><Arg><Property name="jetty.home" default="." />/resources/jmx.password</Arg></New>
 +
        </Item>
 +
      </Entry>
 +
      <Entry>
 +
        <Item>jmx.remote.x.access.file</Item>
 +
        <Item>
 +
          <New class="java.lang.String"><Arg><Property name="jetty.home" default="." />/resources/jmx.access</Arg></New>
 +
        </Item>
 +
      </Entry>
 +
    </Map>
 +
  </Arg>
 +
  <Arg>org.eclipse.jetty.jmx:name=rmiconnectorserver</Arg>
 +
  <Call name="start" />
 +
</New>
 +
</source>
 +
 
 +
=== Custom Monitor Application ===
 +
 
 +
You can also write a custom application using JMX API that will monitor your Jetty server. In order for this application to be able to connect to your Jetty server, you will need to un-comment the last section of etc/jetty-jmx.xml configuration file and optionally modify the endpoint name. That will create a JMX HTTP connector and register a JMX URL that it will be output to the Stderr log.
 +
 
 +
You should provide the URL that appears in the log to your monitor application in order to create MBeanServerConnection.
 +
The same URL could also be used to connect to your Jetty instance from a remote machine using JConsole. See the [http://dev.eclipse.org/viewcvs/index.cgi/jetty/trunk/jetty-jmx/src/main/config/etc/?root=RT_Jetty configuration file] for more details.
  
You can also write a custom application using JMX API that will monitor your Jetty server. In order for this application to be able to connect to your Jetty server, you will need to un-comment the last section of etc/jetty-jmx.xml configuration file and optionally modify the endpoint name. That will create a JMX HTTP connector and register a JMX URL that it will be output to the Stderr log. You should provide the URL that appears in the log to your monitor application in order to create MBeanServerConnection. See the [http://dev.eclipse.org/viewcvs/index.cgi/jetty/trunk/jetty-jmx/src/main/config/etc/?root=RT_Jetty configuration file] for more details.
 
 
   
 
   
 
| more =  
 
| more =  
  
See [[Jetty/Howto/Run Jetty_with_JConsole|Run Jetty with JConsole]] for instructions on how to configure JVM for use with JConsole.
+
* See [[Jetty/Howto/Run Jetty_with_JConsole|Run Jetty with JConsole]] for instructions on how to configure JVM for use with JConsole.
 
+
* The [http://code.google.com/p/jminix/ JMiniX] web console for JMX mbeans.
You can also use [http://java-monitor.com/install.html java-monitor] to monitor your Jetty server using JMX. See [[Jetty/Feature/Java-monitor|Jetty java-monitor]] feature guide for more information.
+
* You can also use [http://java-monitor.com/install.html java-monitor] to monitor your Jetty server using JMX. See [[Jetty/Feature/Java-monitor|Jetty java-monitor]] feature guide for more information.
 
| category = [[Category:Jetty Tutorial]]
 
| category = [[Category:Jetty Tutorial]]
 
}}
 
}}

Revision as of 15:32, 22 August 2012



Contents

Introduction

This tutorial describes how the Jetty JMX integration can be initialized and configured. The simplest way to access the MBeans that are published by Jetty is to use the JConsole utility supplied with Sun's Java Virtual Machine. See Run Jetty with JConsole for instructions on how to configure JVM for use with JConsole.

Details

Configuration

There are two main steps that needs to be performed in order to be able to access Jetty's MBeans via JConsole.

The first step is enabling the registration of Jetty's MBeans into the platform MBeanServer.

The second step is to enable a JMXConnectorServer so that JConsole can connect and visualize the MBeans.

Enabling Registration of Jetty's MBeans

The steps required to configure Jetty JMX integration will be different depending on the way that Jetty is bootstrapped.

Standalone Jetty

When running in standalone mode, the MBeanContainer instance can be configured for a Jetty server by the jetty-jmx.xml configuration file. This can be run with the standard configuration file as follows:

java -jar start.jar OPTIONS=Server,jmx etc/jetty-jmx.xml etc/jetty.xml

Please make sure that the jetty-jmx.xml is the first XML file listed in the command line to ensure that all instances of objects that supposed to be registered as MBeans are detected properly.

Embedded Jetty

If Jetty is embedded into an application, the following snippet of code shows how to create and configure an MBeanContainer instance:

Server _server = new Server();
 
// Setup JMX
MBeanContainer mbContainer=new MBeanContainer(ManagementFactory.getPlatformMBeanServer());
_server.getContainer().addEventListener(mbContainer);
_server.addBean(mbContainer);
 
// Register loggers as MBeans
mbContainer.addBean(Log.getLog());

Please note that MBeanContainer is created immediately after the Server is created, and immediately after it is registered as an EventListener of the Server's Container object. Because logging is initialized prior to the MBeanContainer, it is necessary to register the logger manually - via MBeanContainer.addBean().

Jetty Maven Plugin

If you are using the Jetty Maven plugin you should copy the etc/jetty-jmx.xml file into your webapp project somewhere, such as src/etc, then add a <jettyconfig> element to the plugin <configuration>:

<plugin>
  <groupid>org.mortbay.jetty</groupid>
  <artifactid>maven-jetty-plugin</artifactid>
  <version>${project.version}</version>
  <configuration>
    <scanintervalseconds>10</scanintervalseconds>
    <jettyXml>src/etc/jetty-jmx.xml</jettyXml>
  </configuration>
</plugin>

Enabling JMXConnectorServer for Remote Access

There are two ways of enabling remote connectivity so that JConsole can connect to visualize MBeans.

The first way is to use the "com.sun.management.jmxremote" system property on command line. Unfortunately, this solution does not play well with firewalls and it is not flexible.

The second way is to use Jetty's ConnectorServer class. To enable usage of this class, just uncomment the correspondent portion in etc/jetty-jmx.xml; it will look like this:

<New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
  <Arg>
    <New class="javax.management.remote.JMXServiceURL">
      <Arg type="java.lang.String">rmi</Arg>
      <Arg type="java.lang.String" />
      <Arg type="java.lang.Integer"><SystemProperty name="jetty.jmxrmiport" default="1099"/></Arg>
      <Arg type="java.lang.String">/jndi/rmi://<SystemProperty name="jetty.jmxrmihost" default="localhost"/>:<SystemProperty name="jetty.jmxrmiport" default="1099"/>/jmxrmi</Arg>
    </New>
  </Arg>
  <Arg>org.eclipse.jetty.jmx:name=rmiconnectorserver</Arg>
  <Call name="start" />
</New>

This configuration snippet will start an RMIRegistry and a JMXConnectorServer both on port 1099 (by default), so that firewalls should open just that one port to allow connections from JConsole.

Securing Remote Access

JMXConnectorServer comes with the possibility to restrict access in several ways. For a complete tutorial about controlling authentication and authorization in JMX, see this tutorial.

In order to restrict access to the JMXConnectorServer, you can use this configuration, where the "jmx.password" and "jmx.access" files have the format specified in the tutorial above:

<New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
  <Arg>
    <New class="javax.management.remote.JMXServiceURL">
      <Arg type="java.lang.String">rmi</Arg>
      <Arg type="java.lang.String" />
      <Arg type="java.lang.Integer"><SystemProperty name="jetty.jmxrmiport" default="1099"/></Arg>
      <Arg type="java.lang.String">/jndi/rmi://<SystemProperty name="jetty.jmxrmihost" default="localhost"/>:<SystemProperty name="jetty.jmxrmiport" default="1099"/>/jmxrmi</Arg>
    </New>
  </Arg>
  <Arg>
    <Map>
      <Entry>
        <Item>jmx.remote.x.password.file</Item>
        <Item>
          <New class="java.lang.String"><Arg><Property name="jetty.home" default="." />/resources/jmx.password</Arg></New>
        </Item>
      </Entry>
      <Entry>
        <Item>jmx.remote.x.access.file</Item>
        <Item>
          <New class="java.lang.String"><Arg><Property name="jetty.home" default="." />/resources/jmx.access</Arg></New>
        </Item>
      </Entry>
    </Map>
  </Arg>
  <Arg>org.eclipse.jetty.jmx:name=rmiconnectorserver</Arg>
  <Call name="start" />
</New>

Custom Monitor Application

You can also write a custom application using JMX API that will monitor your Jetty server. In order for this application to be able to connect to your Jetty server, you will need to un-comment the last section of etc/jetty-jmx.xml configuration file and optionally modify the endpoint name. That will create a JMX HTTP connector and register a JMX URL that it will be output to the Stderr log.

You should provide the URL that appears in the log to your monitor application in order to create MBeanServerConnection. The same URL could also be used to connect to your Jetty instance from a remote machine using JConsole. See the configuration file for more details.

Additional Resources