<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Chapter&nbsp;13.&nbsp;JMX</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty : The Definitive Reference"><link rel="up" href="administration.html" title="Part&nbsp;III.&nbsp;Jetty Administration Guide"><link rel="prev" href="using-annotations-embedded.html" title="Using Annotations with Jetty Embedded"><link rel="next" href="jetty-jconsole.html" title="Jetty JConsole"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.3.0.v20150612</span></td><td style="width: 50%"><script type="text/javascript">  (function() {
            var cx = '016459005284625897022:obd4lsai2ds';
            var gcse = document.createElement('script');
            gcse.type = 'text/javascript';
            gcse.async = true;
            gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
            '//www.google.com/cse/cse.js?cx=' + cx;
            var s = document.getElementsByTagName('script')[0];
            s.parentNode.insertBefore(gcse, s);
            })();
          </script><gcse:search></gcse:search></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;13.&nbsp;JMX</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using-annotations-embedded.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;III.&nbsp;Jetty Administration Guide<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jetty-jconsole.html">Next <i class="icon-chevron-right"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
 scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
      </p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="jmx-chapter"></a>Chapter&nbsp;13.&nbsp;JMX</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="jmx-chapter.html#using-jmx">Using Java Management Extensions (JMX)</a></span></dt><dt><span class="section"><a href="jetty-jconsole.html">Jetty JConsole</a></span></dt><dt><span class="section"><a href="jetty-jmx-annotations.html">Jetty JMX Annotations</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="using-jmx"></a>Using Java Management Extensions (JMX)</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jmx-chapter.html#configuring-jmx">Configuring JMX</a></span></dt></dl></div><p>The <a class="link" href="[http://java.sun.com/products/JavaManagement/" target="_top">Java
  Management Extensions (JMX) API</a> is a standard API for managing and
  monitoring resources such as applications, devices, services, and the Java
  virtual machine.</p><p>Typical uses of the JMX technology include:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Consulting and changing application configuration.</p></li><li class="listitem"><p>Accumulating and making available statistics about application
      behavior.</p></li><li class="listitem"><p>Notifying of state changes and erroneous conditions.</p></li></ul></div><p>The JMX API includes remote access, so a remote management program can
  interact with a running application for these purposes.</p><p>Jetty JMX integration uses the platform MBean server implementation
  that Java VM provides. The integration is based on the ObjectMBean
  implementation of DynamicMBean. This implementation allows you to wrap an
  arbitrary POJO in an MBean and annotate it appropriately to expose it via
  JMX. See <a class="xref" href="jetty-jmx-annotations.html" title="Jetty JMX Annotations">Jetty JMX Annotations</a>.</p><p>TheMBeanContainer implementation of the Container.Listener interface
  coordinates creation of MBeans. The Jetty Server and it's components use a
  <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/util/component/Container.html" target="_top">Container</a>
  to maintain a containment tree of components and to support notification of
  changes to that tree. The MBeanContainer class listens for Container events
  and creates and destroys MBeans as required to wrap all Jetty
  components.</p><p>You can access the MBeans that Jetty publishes both through built-in
  Java VM connector via JConsole, or by registering a remote JMX connector and
  using a remote JMX agent to monitor Jetty.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-jmx"></a>Configuring JMX</h3></div></div></div><p>This guide describes how to initialize and configure the Jetty JMX
    integration.</p><p>To monitor an application using JMX, perform the following
    steps:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Configure the application to instantiate an MBean
        container.</p></li><li class="listitem"><p>Instrument objects to be MBeans.</p></li><li class="listitem"><p>Provide access for JMX agents to MBeans.</p></li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="accessing-jetty-mbeans"></a>Using JConsole to Access Jetty MBeans</h4></div></div></div><p>The simplest way to access the MBeans that Jetty publishes is to
      use the <a class="link" href="http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html" target="_top">JConsole
      utility</a> the Java Virtual Machine supplies. See <a class="xref" href="jetty-jconsole.html" title="Jetty JConsole">Jetty JConsole</a> for instructions on how to configure JVM for
      use with JConsole.</p><p>To access Jetty MBeans via JConsole, you must:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Enable the registration of Jetty MBeans into the platform
          MBeanServer.</p></li><li class="listitem"><p>Enable a JMXConnectorServer so that JConsole can connect and
          visualize the MBeans.</p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="registering-jetty-mbeans"></a>Registering Jetty MBeans</h4></div></div></div><p>Configuring Jetty JMX integration differs for standalone and
      embedded Jetty.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="jmx-standalone-jetty"></a>Standalone Jetty</h5></div></div></div><p>JMX is enabled by default in the jetty-9 distribution. If you
        are having difficulties validate that the section in the
        jetty.home/start.ini file is uncommented.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="jmx-embedded-jetty"></a>Embedded Jetty</h5></div></div></div><p>When running Jetty embedded into an application, create and
        configure an MBeanContainer instance as follows:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[

Server server = new Server();

// Setup JMX
MBeanContainer mbContainer=new MBeanContainer(ManagementFactory.getPlatformMBeanServer());
server.addEventListener(mbContainer);
server.addBean(mbContainer);

// Add loggers MBean to server (will be picked up by MBeanContainer above)
server.addBean(Log.getLog());

          ]]>
        </script></div><p>Notice that Jetty creates the MBeanContainer immediately after
        creating the Server, and immediately after registering it as an
        EventListener of the Server object (which is also a Container object).</p><p>Because logging is initialized prior to the MBeanContainer (even
        before the Server itself), it is necessary to register the logger
        manually via <code class="code">server.addBean()</code> so that the loggers may
        show up in the JMX tree</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="jmx-using-jetty-maven-plugin"></a>Using the Jetty Maven Plugin with JMX</h4></div></div></div><p>If you are using the <a class="link" href="jetty-maven-plugin.html" title="Configuring the Jetty Maven Plugin">jetty
      maven plugin</a> you should copy the <code class="filename">
      etc/jetty-jmx.xml</code> file into your webapp project somewhere,
      such as <code class="filename">src/etc,</code> then add a
      <code class="code">&lt;jettyconfig&gt;</code> element to the plugin
      <code class="code">&lt;configuration&gt;</code>:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
          <![CDATA[

<plugin>
  <groupid>org.eclipse.jetty</groupid>
  <artifactid>jetty-maven-plugin</artifactid>
  <version>9.3.0.v20150612</version>
  <configuration>
    <scanintervalseconds>10</scanintervalseconds>
    <jettyXml>src/etc/jetty-jmx.xml</jettyXml>
  </configuration>
</plugin>

        ]]>
        </script></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="enabling-jmxconnectorserver-for-remote-access"></a>Enabling JMXConnectorServer for Remote Access</h4></div></div></div><p>There are two ways of enabling remote connectivity so that
      JConsole can connect to visualize MBeans.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Use the <code class="code">com.sun.management.jmxremote</code> system
          property on the command line. Unfortunately, this solution does not
          play well with firewalls and it is not flexible.</p></li><li class="listitem"><p>Use Jetty's <code class="code">ConnectorServer</code> class. To enable use
          of this class, uncomment the correspondent portion in
          <code class="filename">etc/jetty-jmx.xml,</code> like this:</p></li></ul></div><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
          <![CDATA[

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

        ]]>
        </script></div><p>This configuration snippet starts 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.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="securing-remote-access"></a>Securing Remote Access</h5></div></div></div><p>JMXConnectorServer several options to restrict access. For a
        complete guide to controlling authentication and authorization in JMX,
        see <a class="link" href="https://blogs.oracle.com/lmalventosa/entry/jmx_authentication_authorization" target="_top">Authentication
        and Authorization in JMX RMI connectors</a> in Luis-Miguel
        Alventosa's blog.</p><p>To restrict access to the JMXConnectorServer, you can use this
        configuration, where the <code class="filename"> jmx.password</code> and
        <code class="filename">jmx.access</code> files have the format specified in the
        blog entry above:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false">
          <![CDATA[

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

          ]]>
        </script></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="custom-monitor-applcation"></a>Custom Monitor Application</h4></div></div></div><p>Using the JMX API, you can also write a custom application to
      monitor your Jetty server. To allow this application to connect to your
      Jetty server, you need to uncomment the last section of your <code class="filename">
      etc/jetty-jmx.xml</code> configuration file and optionally modify
      the endpoint name. Doing so creates a JMX HTTP connector and registers a
      JMX URL that outputs to the <code class="code">Stderr</code> log.</p><p>You should provide the URL that appears in the log to your monitor
      application in order to create an <code class="code"> MBeanServerConnection.</code>
      You can use the same URL to connect to your Jetty instance from a remote
      machine using JConsole. See the <a class="link" href="http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/tree/jetty-jmx/src/main/config/etc/jetty-jmx.xml" target="_top">configuration
      file</a> for more details.</p></div></div></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using-annotations-embedded.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="administration.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jetty-jconsole.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Using Annotations with Jetty Embedded&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Jetty JConsole</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/jetty-project/jetty-documentation">Contribute to this documentation at
                <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-06-15T13:18:22-05:00)</i></span></div></p><script xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-1149868-7']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
    </script></body></html>