English | Japanese


Komuso2.0

Introduction

Komuso is a very simple MBean server monitoring tool.
With Komuso, you can monitor any MBean server including WebLogic Server, Tomcat, JBoss, Oracle Application Server, WebSphere and just JVM locally or remotely. Komuso is unique for its simplicity. Komuso consists of only 150 lines of code.
This makes Komuso easier to understand and customize.

System Requirements

OS: Windows or any flavor of Unix that supports Java.
JVM: Java5 or later
Application Server: Any application server that supports JMX Remote API(JSR160).

JBoss AS 4.0.2 or later, and WebLogic Server 9.0 or later support JMX Remote API.
You can use Komuso 1.0 for WebLogic 8.1 or prior versions which don't support JMX Remote API.

How To Use
  1. Configuring Komuso

    2. Edit setEnv.sh/cnd to point your JAVA_HOME propertly.

  2. Configuring your application

    • Configuring standalone application
      • You can get your application JMX Remote ready by just adding following two system properties: 
      -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8999 -Dcom.sun.management.jmxremote.authenticate=false

    • Configuring JBoss
      • Follow the example below to make JBoss MBeans monitorable.
      e.g. Windows 
      @echo off
rem -------------------------------------------------------------------------
rem JBoss Bootstrap Script for Win32
rem -------------------------------------------------------------------------
set JAVA_OPTS="%JAVA_OPTS% -Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl"
set JAVA_OPTS="%JAVA_OPTS% -Djboss.platform.mbeanserver"
set JAVA_OPTS="%JAVA_OPTS% -Dcom.sun.management.jmxremote"
set JAVA_OPTS="%JAVA_OPTS% -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8999 -Dcom.sun.management.jmxremote.authenticate=false"

rem $Id: run.bat 64751 2007-08-21 21:00:53Z dbhole $
      e.g. Unix 
      #!/bin/sh
### ====================================================================== ###
##                                                                          ##
##  JBoss Bootstrap Script                                                  ##
##                                                                          ##
### ====================================================================== ###
JAVA_OPTS="$JAVA_OPTS -Djavax.management.builder.initial=org.jboss.system.server.jmx.MBeanServerBuilderImpl"
JAVA_OPTS="$JAVA_OPTS -Djboss.platform.mbeanserver"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote"
JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8999 -Dcom.sun.management.jmxremote.authenticate=false"

### $Id: run.sh 70962 2008-03-18 20:38:16Z dbhole $ ###
    • Configuring WebLogic Server
      • There's nothing you need to configure on the server side. But you need to copy weblogic.jar to lib/ directory to make Komuso t3 protocol aware.

    • Configuring Tomcat
      • Add one single line in your startup.bat/sh as following:
      e.g. Windows 
      @echo off
if "%OS%" == "Windows_NT" setlocal
rem ---------------------------------------------------------------------------
rem Start script for the CATALINA Server
rem
rem $Id: startup.bat 302918 2004-05-27 18:25:11Z yoavs $
rem ---------------------------------------------------------------------------
set CATALINA_OPTS="-Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8999 -Dcom.sun.management.jmxremote.authenticate=false"
      e.g. Unix 
      #!/bin/sh
# -----------------------------------------------------------------------------
# Start Script for the CATALINA Server
#
# $Id: startup.sh 385888 2006-03-14 21:04:40Z keith $
# -----------------------------------------------------------------------------
export CATALINA_OPTS="-Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8999 -Dcom.sun.management.jmxremote.authenticate=false"

  3. Preparing a properties file

    4. Prepare a text file whose name ends with ".properties" as below.
    Each property should be written without any line break.
    Komuso is shipped with sample properties files named "komuso.properties" for Tomcat / standalone JVM, "komuso-wls.properties" for WebLogic. 

    jmx.remote.protocol.provider.pkgs=JMX Remote protocol provier package name
JMXServiceURL=JMX Service URL
java.naming.security.principal=User ID for the connection
java.naming.security.credentials=Password for the connection
    e.g. A standalone JVM is running with an MBean Server listening on 8999 and authentication is disabled. 
    jmx.remote.protocol.provider.pkgs=
JMXServiceURL=service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi
java.naming.security.principal=
java.naming.security.credentials=
    e.g. WebLogic Server is listening on port 7001 and admin userID/password combination is weblogic/gumby1234 
    jmx.remote.protocol.provider.pkgs=weblogic.management.remote
JMXServiceURL=service:jmx:t3://localhost:7001/jndi/weblogic.management.mbeanservers.domainruntime
java.naming.security.principal=weblogic
java.naming.security.credentials=gumby1234

  4. Generating MBeanDoc

    5. MBeanDoc is a JavaDoc like HTML document which describes all MBean instances / attributes deployed on the JMX Server.
    You can generate MBeanDoc by issuing mbeandoc.cmd/sh.
    MBeanDoc will be generated under the KOMUSO_HOME/mbeandump/ directory and automatically opened with the default web browser(Win/Mac only).
    You can find a sample MBeanDoc here. 

    Usage: mbeandoc.cmd/sh [YOUR_KOMUSO.properties]

    fig.1 MBeandoc Generation

  5. Selecting MBean attributes

    6. MBeanDoc has two tabs. On the "MBeanDoc" tab, you choose MBean attributes you want to monitor. On the "Settings" tab, you confirm the chosen ones.
    You can also set the CSV header of each attribute on the tab.
    A complete setting is generated in real time right below the "Generated Settings" label.
    Unfortunately MBeanDoc doesn't automagically store the setting into the properties file.
    You need to manually override the existing properties file with the generated setting.


    fig.2 Selecting attributes to be monitored

    fig.3 Confirm Settings
  6. Monitoring

    7. It's all set! You can monitor the JMX Service by just running komuso.cmd/sh.

    Usage: komuso.cmd/sh [YOUR_KOMUSO.properties ...]

    fig.4 Monitoring
    Sampled MBean attribute values will be written into standard output and "komuso.csv" in CSV format by default.
    Komuso will also report the status of the connection, caught exceptions to "komuso_status.log" separately.
    Log files will be rolled over every midnight and the latest 10 files will be kept.
    Komuso uses Logback to write messages.
    You can edit "logback.xml" to configure logging policy.
    For more information, please visit the Logback Documentation page.

Download

 Download
komuso2.0.3.zip
komuso2.0.3.tar.gz

Source Code

The archive contains jar file along with source code.
You can access the project repository via http://yusuke.homeip.net/fisheye/browse/svn/komuso/trunk
Or you can check out the latest source code anonymously with a subversion client as follows: 

svn checkout http://yusuke.homeip.net/svn/komuso/trunk komuso

Mailing list

Any comment, bug report, feature request or patch is highly welcomed.
Feel free to post your comments to the mailing list.
Google Groups
Subscribe to Komuso ML
Email:
Visit this group

Known issues are filed in Jira.

Atlassian JIRA

License

 Komuso 2.0 is released under the BSD license.
Komuso 2.0 bundles Apache Velocity which is released under the Apache Software License .
Komuso 2.0 bundles Logback which is released under GNU Lesser General Public License.
Copyright (c) 2007-2008, Yusuke Yamamoto
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the Yusuke Yamamoto nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY Yusuke Yamamoto ``AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL Yusuke Yamamoto BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Pricing

 Komuso is an opensourced software and free of charge.
You can use Komuso freely for any commercial or non-commercial project.
If you feel Komuso makes your life easier, please do consider making a donation!

Changes