#summary How to configure VisualVM to connect to WebSphere

= Prerequisites =

  * An installation of [http://visualvm.java.net/ VisualVM]. The procedure described in this document has been tested with VisualVM 1.3.2 and 1.3.3, but should work for older versions as well.

= Adding the XM4WAS JMX client connector JARs (Required) =

Add the following JARs to the `platform/lib` folder in the VisualVM installation directory:
  * `jmx-client-connector-<version>.jar` from the XM4WAS distribution.
  * The following JARs from a WAS 7.0 installation:
    * `runtimes/com.ibm.ws.admin.client_7.0.0.jar`
    * `runtimes/com.ibm.ws.ejb.thinclient_7.0.0.jar`
    * `runtimes/com.ibm.ws.orb_7.0.0.jar`
    * `java/jre/lib/ibmpkcs.jar`
    * `java/jre/lib/ext/ibmkeycert.jar`
    * `java/jre/lib/ext/ibmjceprovider.jar`

= Setting system properties (Required) =

Open the `etc/visualvm.conf` file and add the following option to the `default_options` property:

{{{
-J-Djmx.remote.protocol.provider.pkgs=com.googlecode.xm4was.jmx.client
}}}

= Installing the com.googlecode.xm4was.jmx plugin on WAS (Optional) =

VisualVM is typically used to monitor the JVM. However, the platform MXBeans that give access to the relevant data are not registered in !WebSphere's MBean server. Install the [JmxPlugin com.googlecode.xm4was.jmx plugin] to register these MBeans and to enable JVM monitoring in VisualVM.

This should enable CPU, heap, class and thread monitoring as shown in the following screenshot:

http://xm4was.googlecode.com/svn/wiki/visualvm-monitor-was.png

= Installing the VisualVM-MBeans plugin (Optional) =

!WebSphere exposes a rich set of MBeans that allow to monitor and manage various parts of the server. To get access to these MBeans, install the [http://visualvm.java.net/mbeans_tab.html VisualVM-MBeans] plugin. This plugin integrates JConsole's MBeans tab functionality into VisualVM, as shown in the following screenshot:

http://xm4was.googlecode.com/svn/wiki/visualvm-mbeans-was.png

= Creating connections to !WebSphere =

To add a !WebSphere instance to VisualVM, simply create a remote JMX connection that uses a JMX service URL with of one of the forms described in the [JmxClientConnector documentation] of jmx-client-connector:

http://xm4was.googlecode.com/svn/wiki/visualvm-add-jmx-connection.png

Note that when security is enabled, the signer certificate for the !WebSphere instance must be added to the trust store. If RMI is used as protocol, then the connector will propose to add the certificate automatically:

http://xm4was.googlecode.com/svn/wiki/signer-exchange.png

This is not supported with SOAP. In that case, the certificate must be added manually. Alternatively, add an RMI connection first so that the certificate is added automatically (the same certificate is used for RMI and SOAP).

= Known issues =

  * CPU sampling is not available with VisualVM 1.3.3, but works with 1.3.2.