You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2014/02/01 00:19:21 UTC
svn commit: r1563336 - in /qpid/trunk/qpid/doc/book/src/java-broker:
Java-Broker-Configuring-And-Managing-JMX.xml commonEntities.xml
images/JMX-Connect-MBeans.png images/JMX-Connect-Remote.png
Author: kwall
Date: Fri Jan 31 23:19:21 2014
New Revision: 1563336
URL: http://svn.apache.org/r1563336
Log:
QPID-5525: [Java Broker Documentation] Add simple JMX documentation: simple guide to connecting with jconsole,
simple jmx client example and MBean summary with links to interfaces source files.
Added:
qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-MBeans.png
qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-Remote.png
Modified:
qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml
qpid/trunk/qpid/doc/book/src/java-broker/commonEntities.xml
Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml?rev=1563336&r1=1563335&r2=1563336&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml Fri Jan 31 23:19:21 2014
@@ -1,4 +1,8 @@
<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE entities [
+<!ENTITY % entities SYSTEM "commonEntities.xml">
+%entities;
+]>
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -25,29 +29,293 @@
<section id="Java-Broker-Configuring-And-Managing-JMX-Management-Introduction">
<title>Introduction</title>
- <para>
- The brokers JMX Management Plugin provides the support for creating JMX MBeans for broker objects such as Queues, Exchanges, Connections etc.
- </para>
- <para>
- It is included into the brokers Initial Configuration by default, and is responsible for servicing the RMI and JMX_RMI ports configured on the broker, with the former serving as the RMI Registry used to advertise the actual JMX Connector Server started on the latter.
- </para>
+ <para>The JMX management plugin provides a series of managed beans (MBeans) allowing you to
+ control and monitor the Broker via an industry compliant interface. This provides a
+ convenient intergration point for a variety of Infrastructure Monitoring Solutions,
+ tools such as Jconsole and VisualVM, as well as custom Java programs and scripts.</para>
+ <para>The following sections describe how to connect to JMX, the configuration of the JMX
+ plugin covering topis including securing with SSL, programmatically interacting with
+ Qpid MBeans and finally a summary of all the MBeans made available from by the
+ plugin.</para>
+ <important>
+ <para>For new development work, the reader is directed towards the strategic <link
+ linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management
+ Console</link> and the <link
+ linkend="Java-Broker-Configuring-And-Managing-REST-API">REST API</link>. Use the
+ Web/REST interfaces in preference to JMX whenever possible. The JMX interface may be
+ withdrawn in a future release.</para>
+ </important>
</section>
+ <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-DefaultConfiguration">
+ <title>Default Configuration</title>
+ <para>By default, the Broker is shipped with JMX enabled.</para>
+ <para>The RMI registry port runs on port <literal>8999</literal> and the JMX connector on
+ port <literal>9099</literal>. The connector is not SSL protected. Qpid will use the
+ <ulink
+ url="&oracleJdkDocUrl;java/lang/management/ManagementFactory.html#getPlatformMBeanServer()"
+ >Platform MBeanServer</ulink>.</para>
+ <para>To change these settings, use the <link
+ linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management
+ interface</link>.</para>
+ </section>
+
+ <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX">
+ <title>Connecting to JMX</title>
+ <para>The following example uses Jconsole to illustrates how to connect to JMX and assume
+ the defaults described above. Jconsole is a management tool that comes with the JDK. It
+ provides a very simple view of the MBeans, but requires no special configuration to be
+ used with Qpid.</para>
+ <para>For full details of Jconsole itself refer to Oracle's <ulink url="&oracleJconsole;"
+ >JConsole Guide</ulink>.</para>
+ <para>Jconsole can be used to connect to local or remote Java processes. On startup, it
+ presents a list of all the Java processes running on the local host and also allows you
+ to specify a service url to connect to a Java process running on a remote host.</para>
+ <para>To start Jconsole on the command line, type:</para>
+ <programlisting><![CDATA[jconsole]]></programlisting>
+ <section
+ id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-Local">
+ <title>Local</title>
+ <para>To connect to a Broker running locally, simply select the process from the list.
+ You can identify the Broker by looking for its classname
+ <literal>org.apache.qpid.server.Main</literal>.</para>
+ </section>
+ <section
+ id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-Remote">
+ <title>Remote</title>
+ <para>To connect to a broker running remotely, provide the hostname and port number of
+ the <emphasis>RMI registry port</emphasis> (e.g. <literal>hostname:8999</literal>)
+ and a valid username and password.</para>
+ <para>You can also provide a service url in the form
+ <literal>service:jmx:rmi:///jndi/rmi://hostname:8999/jmxrmi</literal></para>
+ <figure>
+ <title>Making a remote JMX connection to a Broker using jconsole</title>
+ <graphic fileref="images/JMX-Connect-Remote.png"/>
+ </figure>
+ </section>
+ <para>Once you are connected expand the tree of nodes marked
+ <literal>org.apache.qpid</literal> to begin to interact with the Qpid MBeans.</para>
+ <figure>
+ <title>Qpid MBean hierarchy</title>
+ <graphic fileref="images/JMX-Connect-MBeans.png"/>
+ </figure>
+ <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-SSL">
+ <title>Connecting to a remote Broker protected by SSL</title>
+ <para>If you are connecting to a remote Broker whose JMX connector port has been secured
+ with SSL certificate signed by a private CA (or a self-signed certificate), you will
+ need to pass a trust store and trust store password to Jconsole. If this is
+ required, start jconsole with the following options:</para>
+ <programlisting><![CDATA[jconsole -J-Djavax.net.ssl.trustStore=jmxtruststore.jks -J-Djavax.net.ssl.trustStorePassword=password]]></programlisting>
+ </section>
+ </section>
+
+ <section id="Java-Broker-Configuring-And-Managing-JMX-Example-Client">
+ <title>Example JMX Client</title>
+ <para>The following java snippet illustrates a JMX client that connects to Qpid over JMX
+ passing a userid and password, looks up the <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/ManagedBroker&qpidSrcSuffix;"
+ >ManagedBroker</ulink> object corresponding to the <literal>myvhost</literal>
+ virtualhost, then invokes a method on the virtualhost to create a new queue.</para>
+ <para>A full introduction to custom JMX clients is beyond the scope of this book. For this
+ the reader is directed toward Oracle's <ulink url="&oracleJmxTutorial;">JMX
+ tutorial.</ulink></para>
+ <example id="Java-Broker-Configuring-And-Managing-JMX-Example-Client-Code">
+ <title>JMX Client illustrating the creation of a new queue</title>
+ <programlisting language="java">
+Map<String, Object< environment = new HashMap<String, Object>();
+environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"});
+// Connect to service
+JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi");
+JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment);
+MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();
+// Object name for ManagedBroker mbean for virtualhost myvhost
+ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost=\"myvhost\"");
+// Get the ManagedBroker object
+ManagedBroker managedBroker = JMX.newMBeanProxy(mbsc, objectName, ManagedBroker.class);;
+
+// Create the queue named "myqueue"
+managedBroker.createNewQueue("myqueue", null, true);</programlisting>
+ </example>
+ <para>The Qpid classes required for a custom JMX client are included in the
+ <literal>qpid-management-common</literal> artefact.</para>
+ </section>
+
+ <section id="Java-Broker-Configuring-And-Managing-JMX-Management-MBeans">
+ <title>The MBeans</title>
+ <para>The following table summarises the available MBeans. The MBeans are self-describing:
+ each attribute and operation carry a description describing their purpose. This
+ description is visible when using tools such Jconsole. They are also available on
+ Management interfaces themselves (linked below).</para>
+ <table>
+ <title>Qpid Broker MBeans</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Management Interface</entry>
+ <entry>Object Name</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/ManagedBroker&qpidSrcSuffix;"
+ >ManagedBroker</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost="<replaceable>virtualhostname</replaceable>"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>MBean corresponding to the named virtualhost. Allows operations
+ such as the creation/deletion of queues and exchanges on that
+ virtualhost and virtualhost levell statistics.</para>
+ </entry>
+ </row>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/ManagedQueue&qpidSrcSuffix;"
+ >ManagedQueue</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=VirtualHost.Queue,VirtualHost="<replaceable>virtualhostname</replaceable>",name="<replaceable>queuename</replaceable>"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>MBean corresponding to the named queue on the given virtualhost.
+ Allows queue management operations such as view message, move
+ message and clear queue. Exposes attributes such as queue depth and
+ durability.</para>
+ </entry>
+ </row>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/ManagedExchange&qpidSrcSuffix;"
+ >ManagedExchange</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=VirtualHost.Exchange,VirtualHost="<replaceable>virtualhostname</replaceable>",name="<replaceable>amq.direct</replaceable>",ExchangeType=<replaceable>type</replaceable></literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>MBean corresponding to the named exchange on the given
+ virtualhost. Allows exchange management operations such as the
+ creation and removal of bindings. The supported exchange types are
+ exposed by the <literal>exchangeTypes</literal> attribute of the
+ virtualhost.</para>
+ </entry>
+ </row>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/ManagedConnection&qpidSrcSuffix;"
+ >ManagedConnection</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=VirtualHost.Connection,VirtualHost="<replaceable>virtualhostname</replaceable>",name="<replaceable>/peerid:ephemeralport</replaceable>"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>MBean representing a active AMQP connection to the named virtual
+ host. Name is formed from the IP and ephemeral port of the peer.
+ Attributes include the client version and connection level
+ statistics.</para>
+ </entry>
+ </row>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/UserManagement&qpidSrcSuffix;"
+ >UserManagement</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=UserManagement,name="UserManagement-<replaceable>authentication
+ manager name</replaceable>"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>When using <link
+ linkend="Java-Broker-Security-PlainPasswordFile-Provider">Plain
+ password provider</link> or <link
+ linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
+ >Base 64 MD5 password provider</link>, permits user operations
+ such creation and deletion of users. and password changes.</para>
+ </entry>
- <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-Configuration">
- <title>JMX Management Plugin Configuration</title>
+ </row>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/ServerInformation&qpidSrcSuffix;"
+ >ServerInformation</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=ServerInformation,name=ServerInformation</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>Exposes broker wide statistics, product version number and JMX
+ management API version number.</para>
+ </entry>
- <para>
- The JMX Management Plugin can be configured through the <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>
- and underlying REST management interface. By double-clicking on the JMX Management Plugin name in the object tree a tab for the plugin
- is displayed with its current settings, which can be changed by clicking on the "Edit" button.
-
- The following attributes can be set on the JMX Management Plugin:
- <itemizedlist>
- <listitem><para><emphasis>Use Platform MBean Server</emphasis>. The JMX Management Plugin can start its own MBean Server or it can use the JVMs 'Platform MBean Server'.
- By default this is true, and the Platform MBean Server is used.</para></listitem>
- </itemizedlist>
- NOTE: Changes to the "Use Platform MBean Server" attribute only take effect at broker restart.
- </para>
+ </row>
+ <row>
+ <entry morerows="1">
+ <para>
+ <ulink
+ url="&qpidManagementCommonSrc;org/apache/qpid/management/common/mbeans/LoggingManagement&qpidSrcSuffix;"
+ >LoggingManagement</ulink>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>org.apache.qpid:type=LoggingManagement,name=LoggingManagement</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>MBean permitting control of the Broker's logging. Exposes
+ operations allow the logging level to be controlled at runtime
+ (without restarting the Broker) and others that allow changes to be
+ written back to the log4j.xml logging configuration file, or the
+ contents of the log4.xml file to be re-read at runtime.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</section>
</section>
Modified: qpid/trunk/qpid/doc/book/src/java-broker/commonEntities.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/commonEntities.xml?rev=1563336&r1=1563335&r2=1563336&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/commonEntities.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/commonEntities.xml Fri Jan 31 23:19:21 2014
@@ -36,6 +36,7 @@
<!ENTITY oracleJdkDocUrl "http://docs.oracle.com/javase/6/docs/api/">
<!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/">
<!ENTITY oracleKeytool "http://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html">
+<!ENTITY oracleJconsole "http://java.sun.com/javase/6/docs/technotes/guides/management/jconsole.html">
<!-- Oracle BDB JE-->
<!ENTITY oracleJeDownloadUrl "http://www.oracle.com/technetwork/products/berkeleydb/downloads/index.html?ssSourceSiteId=ocomen">
@@ -44,3 +45,8 @@
<!ENTITY oracleBdbJavaDocUrl "http://docs.oracle.com/cd/E17277_02/html/java/">
<!ENTITY oracleBdbProductVersion "5.0.97">
+<!ENTITY oracleJmxTutorial "http://docs.oracle.com/javase/tutorial/jmx/">
+
+<!ENTITY qpidSrc "http://svn.apache.org/viewvc/qpid/trunk/qpid/java/">
+<!ENTITY qpidManagementCommonSrc "&qpidSrc;management/common/src/main/java/">
+<!ENTITY qpidSrcSuffix ".java?view=co">
Added: qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-MBeans.png
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-MBeans.png?rev=1563336&view=auto
==============================================================================
Files qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-MBeans.png (added) and qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-MBeans.png Fri Jan 31 23:19:21 2014 differ
Added: qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-Remote.png
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-Remote.png?rev=1563336&view=auto
==============================================================================
Files qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-Remote.png (added) and qpid/trunk/qpid/doc/book/src/java-broker/images/JMX-Connect-Remote.png Fri Jan 31 23:19:21 2014 differ
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org