Installing and configuring Coherence JMX and the Coherence JVisualVM Plug-In

Overview

Purpose

The intended purpose of this tutorial is to guide the learner in configuring Coherence to support JMX reporting, and the installation and use of the Coherence JVisualVM plug-in.

This tutorial covers in detail:

  • Configuration of standalone Coherence for use with JMX enabled consoles.
  • Installation, configuration and use of JVisualVM plug-in with Coherence.
Time to Complete: Approximately 1 hour.

Introduction

Coherence exposes a large amount of system information using Java Management EXtensions(JMX) and their supporting technology Management Beans(MBeans).  This tutorial uses the power of Coherence JMX support along with the ease of use of JVisualVM application with the Coherence Plug-In to monitor a Coherence cluster .

Hardware and Software Requirements (Optional)

The following is a list of hardware and software requirements:

  • Java JDK 1.7u40 or later.
  • Coherence 12c standalone or with WebLogic (12.1.2 or later) which can be downloaded here.
  • Simulation code, which can be downloaded from here, which starts a Coherence cluster which can then be monitored and examine.
  • Coherence JVisualVM Plug-In, which is provided with the Coherence 12.1.3 and can be downloaded for Coherence 12.1.2 here.  Note: Coherence 12.1.3 includes the plug-in. See the section on installing the plug-in.
  • This tutorial should run on any platform which supports Coherence 12c, however all scripts where written for Linux/Bash.

Prerequisites

Before starting this tutorial, you should:

  • Have a basic working knowledge of Linux commands and command line syntax, including the Bourne Again Shell (/bin/bash).
  • Have access to or have Installed JDK 1.7u40 or later. The Oracle JDK kits and associated products can be found here. Installation of JDK is outside the scope of this OBE. For more information, see the JDK download and installation pages. Note: Oracle installers do NOT support the use of OpenJDK or its variants regardless of version number.
  • Have access to or have installed Oracle Coherence.  For this tutorial Oracle Coherence is assumed to be installed to /opt/coherence.
  • Have downloaded and unpacked the OBE sample code. This code is designed to run on Linux and similar operating systems but can be adapted to Windows if required. 

Before running this tutorial, you should download and install Oracle Coherence 12.1.2 or greater and the associated example source code. The following steps review the installation process of Coherence 12.1.2 or 12.1.3, as well as the expected installation locations.  Note that if you have previously installed Coherence  you may skip this step.

    This Oracle By Example(OBE) uses a set of sample sources which provide a simple Coherence cluster and a background simulation.  The example can be found here

  1. Using the link in the section above, accept the license agreement and download Coherence 12.1.2(3).  This tutorial uses the Coherence quick installer
      and it is assumed that files are downloaded to/tmp/.  and installed into /opt.

  2. Unzip and extract the software.  For convenience the Coherence quick installer was used to install to /opt/coherence12.1.2. A soft link was then used to make Coherence appear to have been installed into /opt/coherence. This solution can be used when multiple versions of different products need to coexist in a single root directory.

    $ unzip ofm_coherence_quick_generic_12.1.2.0.0_disk1_1of1.zip
    $ java -jar coherence_quick_121200.jar -force ORACLE_HOME=/opt/coherence12.1.2
    $ ln -s /opt/coherence12.1.2/coherence/ /opt/coherence

    Image of unzip of the Coherence quick installer
    . . .
    Image of executing the Coherence quick installer
    . . .
    Image of executing the soft link command

    Results of unzipping, installing and soft linking Coherence 12.1.2 as /opt/coherence.

  3. Download the example and unzip OBE simulation sources and scripts.

    $ cd /opt
    $ unzip JVVM.OBE.zip

    Imaging of unzip of JVVM.OBE.zip
    . . .
    Imaging of unzip of JVVM.OBE.zip

    Part of the results of unzipping the OBE sources.

  4. Configure the simulation environment

    A simulation has been provided to simplify the testing of the JVisualVM plug in.  These scripts depend on certain environment variable settings.
    Appropriate defaults have been provided for these variables, which if correct need not be changed.  The scripts assume:

    • Coherence has been installed at /opt/coherence
    • The OBE source has been unzipped to /opt/JVVM.OBE.

  5. If either of these values is incorrect, follow the instructions below.

    1.  In a command prompt window, ensure that you are in the directory where the OBE source was unpacked.
      cd {OBE source directory}

    2. In your favorite editor, open the bin/set-env.sh script.
      gedit bin/set-env.sh

    3. Near the top of the script are two export statements specifying the locations of both the OBE source and Coherence.
      Un-comment the two variables and set them to the appropriate values for your environment.

      If the default values of /opt/coherence and /opt/JVVM.OBE are used, no changes are required.

      #!/bin/bash
      export OBE_HOME=/my.obe.location
      export COH_HOME=/my.coherence.location

    4. Save your changes, and exit the editor

Configure Coherence to support JMX reporting

To configure Coherence instances to support JMX reporting a single managing instance and multiple server instances must be configured.  A manager instance performs the operations of collecting JMX statistics from managed instances, of which is may itself be one, and providing this information to consuming applications, for example JVisualVM. The next several steps configure the provided OBE sources to use both managed and manager Coherence instances.

This tutorial uses a simulation to interact with Coherence and cause activity.  The simulation is started via the start-sim.sh script. The start simulation script starts several instance of an example application which interacts with Coherence. The simulation must be JMX enabled in order to be used with JVisualVM

Hints

    The following hints are intended assist the learner in attempting to configure the simulation without following the step by step instructions. Others may wish to use these instructions as a reference.  Note that the simulation is starting using the bin/start-sim.sh script and contains appropriate comments detailing where to add command line overrides.

  • Management instances must specify -Dcom.sun.management.jmxremote to enable basic JMX reporting support.

  • Management instances must enable remote JMX Management using either an XML operational override or a command line override.  The XML operational override is specified as:
    <coherence>
        <mananagement-config>
           <managed-nodes>all</managed-nodes>
      
       </management-config>
    </coherence>

    The command line override is specified using -Dtangosol.coherence.management=all

  • Managed Instances must allow remote management, which can be enabled using an XML override or a command line overide.  The XML override is specified as:
    <coherence>
        <management-config>
            <allow-remote-management>false</allow-remote-management>
       
    </management-config>
    </coherence>

    The command line override using -Dtangosol.coherence.management.remote=true

  • Simulation is started, stopped and managed using several scripts:
    • bin/start-sim.sh - Starts the simulation, which is comprised of three instances of Coherence and code to generate activity.
    • bin/stop-sim.sh - Stops the simulation if still running.
    • bin/build.sh - Rebuilds the simulation if required.
    • bin/set-env.sh - Configures the simulation. 
    • Other scripts not used by this OBE.

Steps

    Note: A completed version of the simulation script can be found in {OBE_HOME}/completed/start-sim.sh.
  1. Open a command prompt and change directory to the location of the OBE sources

    $ cd /opt/JVVM.OBE/bin

  2. Using your favorite editor open the file start-sim.sh.
    $ gedit start-sim.sh

  3. At roughly line 46 is the beginning of a loop which starts instances. The loop contains an if statement which treats instance 0 differently from instances 1-N.
    Inside the if [ $p -eq 0 ] section, beneath the # Enter management instance comments update the MGMT_OPTS variable to add overrides appropriate for the management instance.  The results should resemble (with additions shown in bold):

     MGMT_OPTS="-Dtangosol.coherence.management=all"
     MGMT_OPTS="${MGMT_OPTS} -Dcom.sun.management.jmxremote"

  4. Inside the else portion of the statement add appropriate parameters for the managed nodes.  The result should resemble:

    MGMT_OPTS="-Dtangosol.coherence.management=all"
    MGMT_OPTS="${MGMT_OPTS} -Dtangosol.coherence.management.remote=true"

  5. Save your changes and exit the editor.

Installing and configuring the Coherence JVisualVM Plug-in

    Note: The Coherence-JVisualVM plug-in is a design-time tool that is intended to monitor a single Coherence clusters during development and testing. Enterprise-level management products, such as Oracle Enterprise Manager, should be used for monitoring, managing, and alerting in production environments.
  1. Download the JVisualVM Plug-in.

    The JVisualVM plugin for Coherence is packaged with Coherence 12.1.3 (both stand alone and when packaged with WebLogic Server)
    The plugin is also available for download from Maven Repository when being used with an earlier version of Coherence (for example 12.1.2).

    If required download the plugin from the repository at Maven.org found here. Click the nbm link and save the file.

    Download NMB
  2. Start JVisualVM using a command similar to:
    $ jvisualvm &
    The splash screen will briefly display.

    JVisualVM Splash 
  3. Choose Tools > Plugins from the main menu. The Plugins dialog will display.

    JVisualVM Splash
    . . .
    JVisualVM Splash 
  4. Select the Downloaded tab and then click Add Plugins.

    Download NMB
  5. Navigate to the directory where the plugin was downloaded or to
    the {COH_HOME}/plugins/jvisualvm directory and select the plugin.
    Click Open.
    Note: Newer versions of the plugin will become available over time.
    As of this writing 12.1.0 is the most recent version.
    Download NMB
  6. Once selected click Install and the install plug in wizard will begin.
    1. In the Welcome dialog click Next.
    2. In the License Agreement dialog, scroll to the bottom and check I accept and click Install
    3. If a validation warning displays saying the plug-in is not signed click Continue.
      The plug in will then begin to install.
    4. When complete click Finish

  7. Close the Plugins dialog by clicking Close
  8. Exit JVisualVM

Start and Monitor a Coherence Cluster

  1. Open a command prompt and change directory to the OBE source directory

    $ cd /opt/JVVM.OBE

  2. Start the simulation

    $ bin/start-sim.sh

    Which should produce output similar to: 
    Starting the simulation 
  3. Pause as simulation starts.
    The simulations each will pause for approximately 30 seconds so that all may start before generating data.  Using a command similar to:
    $ tail -f sim.0.log
    Wait for data to be generated which should produce output similar to that shown below:
    Tailing a simulation log 
  4. Start JVisualVM

    $ jvisualvm

  5. Connect to the management instance
    The simulation scripts start the management instance as the first instance and as a result the instance has the lowest PID.
    1. In the Applications  pane
    2. Expand Local
    3. Double click the lowest numbered PID.
    Selecting an instance to monitor 

    Notice that the right pane changes to include a tab for the newly selected PID
  6. In right pane select the Oracle Coherence tab

    Selecting the oracle tab  

  7. In the Coherence pane, notice that there are several sub panes. Select Cluster Overview.

  8. Mouse over any of the displayed tables. Note that each is a running timeline of the live system.

    Selecting the oracle tab 


  9. Using the Members tab Can you answer the following questions?

    Question Hint
    What is the current license mode? Answer is either Production or Development.
    How many members are in the cluster? Does this match the total number started in the simulation?
    How many ports are in use? What is the starting port? Ports are listed with each node id.

  10. Using the Caches tab Can you answer the following questions?

    Question Hint
    What caches are in use? What are their types? There is only one cache, which contains Person objects.
    How many entries are in the cache? Total entries and size in bytes and MB are also listed.

  11. Using the Machines tab Can you answer the following questions?

    Question Hint
    How many total machines are in use? This value will vary considerably in real world scenarios but should be 1 for the simulation
    How much Physical Memory does the machine have? This should match the physical machine you are testing on.

  12. Exit JVisualVM
  13. Shut down the simulation using the provided stop-sim.sh script.
    $ bin/stop-sim.sh

Summary

In this tutorial students have learned to configure Coherence instances to support JMX management as well as install and use the JVisualVM Coherence plug-in.

In this tutorial, you learned to:
  • Specify required command line overrides to start a Coherence instance as a JMX management node.
  • Specify required command line overrides to start a Coherence instance as a JMX managed node.
  • Download and install the Coherence Plug-In for JVisualVM.
  • Examine a running Coherence cluster using JVisualVM and the Coherence Plug-In.

Resources

Credits

  • Lead Curriculum Developer: Albert J Saganich
  • Other Contributors: Joe Ruzzi, Coherence documentation. Brian Oliver Coherence Architect

To navigate this Oracle by Example tutorial, note the following:

Topic List:
Click a topic to navigate to that section.
Expand All Topics:
Click the button to show or hide the details for the sections. By default, all topics are collapsed.
Hide All Images:
Click the button to show or hide the screenshots. By default, all images are displayed.
Print:
Click the button to print the content. The content that is currently displayed or hidden is printed.

To navigate to a particular section in this tutorial, select the topic from the list.