Top Most JAMon plugin for Grails: Part 4 of 4

In this series we completed steps 1-4 of our task list:

1. Add jamon.jar to the application classpath
2. Use JAMon's datasource proxy to monitor SQL
   
3. Implement the JAMonServletFilter to monitor page hits
   
4. Leverage Spring AOP via Spring's JamonPerformanceMonitorInterceptor class to monitor services
5. Add a Spring filter to monitor Grails controllers

Now lets complete step #5: Add a Spring filter to monitor Grails controllers. Spring filters are different than Servlet filters, although the details are beyond the scope of this article. Grails makes it easy to add Spring filters. Read the Grails documention for the details.

Create a package structure under grails-app/conf. I used org/grails/plugins/filters. Create a file named JamonFilters and add the following code:

package org.grails.plugins.filters

import com.jamonapi.MonitorFactory
import com.jamonapi.Monitor
import org.codehaus.groovy.grails.commons.ConfigurationHolder
/**
 * @author eric weimer
 */
 class JamonFilters {
    
    Monitor monitor, viewMonitor, previewMonitor
    def skipControllers = (ConfigurationHolder.config.jamon.controllersToExclude)? ConfigurationHolder.config.jamon.controllersToExclude: []
    def filters = {

         monitorController(controller: "*", action: "*") {
             before = {
                 if (!(controllerName in skipControllers)) {
                     def monName = "Controller.${controllerName}.${actionName}"
                     monitor = MonitorFactory.start("${monName}")
                     previewMonitor = MonitorFactory.start("${monName}.noview")
                 }
                 true
             }
             after = {
                 if (previewMonitor) {
                     previewMonitor.stop()
                     def monName = "Controller.${controllerName}.${actionName}.view"
                     viewMonitor = MonitorFactory.start("${monName}")
                 }
                 true
              }
             afterView = {
                 if (monitor) monitor.stop()
                 if (viewMonitor) viewMonitor.stop()
                 true
              }
         }
     }
}

This code calls JAMon methods to start and stop timings. Note the variable skipControllers. This allows users of the plugin to easily define a list of controllers NOT to monitor by adding the variable
jamon.controllersToExclude to groovy.config.

This is all you need to do! Grails will add this filter to the application when you install the plugin.

To allow users to provide additional customizations to the plugin, we document some configuration settings they can set, and then access those settings in our plugin. For example, in the application's Config.groovy class, let's allow users to specify the following:

jamon.monitorControllers = true
jamon.monitorServices = true
jamon.servicesToExclude = ['consoleService']
jamon.controllersToExclude = []
jamon.additionalBeans = ['com.eweimer.terrapin.util.MediaAccess','com.eweimer.terrapin.util.Key']

These settings will allow users to turn off monitoring for Controllers or Services, and specify services NOT to monitor as well as additional Spring beans classes to include.

To access these values in our JamonGrailsPlugin, we'll import:

import org.codehaus.groovy.grails.commons.ConfigurationHolder

To perform a safe test on a boolean value we can use the following code to default to true when the user does not specify a value:

def skipServices = application.config.jamon.servicesToExclude ?: []

Put together, the code now looks like this:

def monBeanNames = []
def skipServices = application.config.jamon.servicesToExclude ?: []
  
if (application.config.jamon.monitorServices ?: true) {
   monBeanNames = application.serviceClasses.collect{ it.shortName[0].toLowerCase() + it.shortName[1..-1] }
   monBeanNames -= skipServices
}
if (application.config.jamon.additionalBeans) {
   monBeanNames += application.config.jamon.additionalBeans
}

By using this logic we can allow users to easily customize the behavior of our jamon plugin.

The final step is to deploy your plugin. Type "grails package-plugin" in the root of your plugin project and Grails will create a .zip file. Then go to your Grails application and type "grails install-plugin path-to-your-zip-file", and you are ready to go.

Deploy the jamon.war that comes with the JAMon distribution to your web server then point your browser to /jamon/menu.jsp to view the results. Viola!

I hope you enjoyed this series. I'll add one more installment about testing your plugin when I have the chance. Meanwhile, have fun!

Top Most JAMon plugin for Grails: Part 3 of 4

In this series we completed steps 1-3 of:

1. Add jamon.jar to the application classpath
2. Use JAMon's datasource proxy to monitor SQL
   
3. Implement the JAMonServletFilter to monitor page hits
   
4. Leverage Spring AOP via Spring's JamonPerformanceMonitorInterceptor class to monitor services
5. Add a Spring filter to monitor Grails controllers.

Let's move on to step 4 : "Leverage Spring AOP via Spring's JamonPerformanceMonitorInterceptor class to monitor services."

We'll add this to the doWithSpring closure. First we'll define a jamonInterceptor bean. It accepts a prefix attribute, which can be set to anything you like:

def doWithSpring = {
   jamonInterceptor( org.springframework.aop.interceptor.JamonPerformanceMonitorInterceptor, true, true ) {
      prefix="Class."
   }
}

Next we need to get a list of beans to intercept. Service class beans are named by the class name with the first character set to lower case. Grails provides a list of service classes via the application object:

def monBeanNames = application.serviceClasses.collect{ it.shortName[0].toLowerCase() + it.shortName[1..-1] }

Finally we use Springs BeanNameAutoProxyCreator to add the jamon interceptor to the service classes:

if (monBeanNames) {
   autoProxyCreator( org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator ) {
      proxyTargetClass="true"
      interceptorNames=["jamonInterceptor"]
      beanNames=monBeanNames as String[]
   }
}

Put it all together, it looks like this:

def doWithSpring = {
   def monBeanNames = application.serviceClasses.collect{ it.shortName[0].toLowerCase() + it.shortName[1..-1] }

   if (monBeanNames) {
      jamonInterceptor(org.springframework.aop.interceptor.JamonPerformanceMonitorInterceptor, true, true) {
      prefix="Class."
      }

      autoProxyCreator(org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator) { 
      proxyTargetClass="true"
      interceptorNames=["jamonInterceptor"]
      beanNames=monBeanNames as String[]
   }
}

In part 4 of this series, we'll complete task #5 and deploy our JAMon plugin.

Top Most JAMon plugin for Grails: Part 2 of 4

In part 1 we discussed four tasks needed to create a JAMon plugin. The first task was completed simply by adding jamon.jar to our plugin's lib folder. To review, the steps are:

1. Add jamon.jar to the application classpath
2. Use JAMon's datasource proxy to monitor SQL
   
3. Implement the JAMonServletFilter to monitor page hits
   
4. Leverage Spring AOP via Spring's JamonPerformanceMonitorInterceptor class to monitor services
5. Add a Spring filter to monitor Grails controllers.

As I mentioned previously, our plugin project has a file named: JamonGrailsPlugin.groovy. This is where we'll implement steps 2-5.

JamonGrailsPlugin.groovy comes with a series of closures pre-defined. To change the datasource we add code to the doWithSpring closure. This closure allows you to update your Spring configuration.

We need to change the driverClassName to "com.jamonapi.proxy.JAMonDriver" and alter the url by adding "jamon:" after "jdbc:" and appending a parameter named "jamonrealdriver".

First lets add an import:

import javax.sql.DataSource

Then code the closure:

def doWithSpring = {
   def config = application.config
   def orgUrl = config.dataSource.url
   def driverClassName = config.dataSource.driverClassName
   
   String appendUrl = (orgUrl.contains('?')? '&': '?') + 'jamonrealdriver=' + driverClassName
   if (orgUrl.contains("oracle:")) appendUrl = 'jamonrealdriver=' + driverClassName
   def url = orgUrl.replace("jdbc:","jdbc:jamon:") + appendUrl

   config.dataSource.url = url
   config.dataSource.driverClassName = "com.jamonapi.proxy.JAMonDriver"
}

Step 3 is "implement the JAMonServletFilter to monitor page hits."

The doWithWebDescriptor closure will allow us to add our filter to the application. We need to append to both the <filter> and <filter-mapping> sections. Note that this is typical Grails builder code. The 'filter-mapping' node needs to be in quotes due to the hyphen in it's name:

def doWithWebDescriptor = { webXml ->
   def filters = webXml.filter
   filters + {
      filter {
         'filter-name'("jAMonServletFilter")
         'filter-class'("com.jamonapi.http.JAMonServletFilter")
      }
   }

   def filterMappings = webXml.'filter-mapping'
      filterMappings + {
         'filter-mapping' {
            'filter-name'("jAMonServletFilter")
            'url-pattern'("/*")
          }
      }
   }

} 

In part 3 we'll move on to step #4.

Top Most Jamon plugin for Grails: Part 1 of 4

JAMon is a popular, flexible, lightweight open source Java performance monitor. I won't cover all the features here, but in short JAMon can monitor performance, memory, number of users, basically any quantity you can access in Java.

To view the statistics JAMon provides a WAR file that you can deploy to your server along with your application. The war provides a set of JSP pages allowing you to view and export the data you are monitoring.

Another option is to incorporate the WAR into your application. It requires a little more work but you can enhance it to your hearts content.

Adding JAMon to Grails is really quite simple. What required some time was to experiment with the different methods JAMon can be inserted into your application. I prefer automation over hard-coded solutions.

Here are the tasks needed to get JAMon set up with an initial set of monitors:

1. Add jamon.jar to the application classpath
2. Use JAMon's datasource proxy to monitor SQL
   
3. Implement the JAMonServletFilter to monitor page hits
   
4. Leverage Spring AOP via Spring's JamonPerformanceMonitorInterceptor class to monitor services
5. Add a Spring filter to monitor Grails controllers.
   

Ideally it would be nice to separate this code in a way that JAMon could be applied to any Grails project. In fact, I found that to be the simplest approach! This solution just cries out for a Grails plugin.

I won't go into all the details regarding plugins. Good references are available here, here and here.

Fist download the JAMon distribution and unzip it.

Assuming you have a target application, let's assume you'll be creating your plugin in the same workspace (i.e. directory). Open a command prompt in that folder and type:

grails create-plugin jamon

If you've never created a plugin before you'll notice that Grails creates a typical Grails application with one additional file in the top directory: JamonGrailsPlugin.groovy.

This file is where we'll be doing most of the work.

To complete task #1 (add jamon.jar to the classpath), simple copy jamon.jar to jamon/lib. When an application installs the plugin, Grails will add jamon.jar to the classpath. That's all you need to do!

Next time I'll show how to implement the remaining tasks. Stay tuned.

Top Most JAMon

Years ago I discovered a little gem in the world of a free and open source software: JAMon.

Still in use today, JAMon's mind-numbingly simple API provides a wealth of value for minimal effort. JAMon has now spawned competing products, each with its unique pros and cons.

JAMon is called a lightweight monitor. This may disappoint those who prefer large, feature-filled enterprise level commercial products, but the reality is JAMon delivers most of the data you need with minimal impact on performance. I would never consider developing a Java application without JAMon or some other monitoring solution. (JAMon is available for other languages as well.)

Best of all, you can have JAMon up and running in a few hours (or less)!

JAMon excels at timing code execution. Without any code changes you can configure JAMon to monitor SQL, method calls (via Spring AOP), as well as application entry and exit points.

In addition to execution time, JAMon allows you to monitor ANY data that can be expressed numerically. Common usage includes the number of users by hour of the day (to find usage peaks), simultaneous users, memory, heap size, session size, # of active sessions, and so on.

JAMon accumulates statistics rather than details which allows it to minimize its memory footprint. As it turns out, that is an excellent comprimise. JAMon keeps track of the number of invocations, min, max, average and standard deviation, as well as the min, max and average number of simultaneous executions, which is great for bottleneck analysis.

Although criticized for its inability to save statistics to a persistent store, you can do so with a little work if needed. You can persist statistics to a database, log file, expose them via JMX, etc.

You can configure JAMon start and stop monitoring dynamically. JAMon is typically measured at less than one percent overhead while turned on, and much less when turned off.

So if you have no monitoring (or your monitoring solution cannot be run in production), try JAMon or one of it's competitors. Documentation is a bit on the light side but there are plenty of examples on the Web.

And if you are a Grails developer, look for my posts about how to create a simple plugin to enable JAMon in your Grails applications.

Top Most Testing the Grails JAMon Plugin

Previously I wrote about creating a JAMon plugin for Grails. Today I'll add some tests.

Since a plugin is a Grails application, you should add tests to your plugin project. Let's begin with opening a command window in the plugin project (jamon) and creating a test class:

grails create-integration-test JamonGrailsPlugin

Now we edit the class Grails created. We find this class in jamon\test\integration\JamonGrailsPluginTests.groovy.

First we see Grails creates a class that extends GrailsUnitTestCase. Since this is an integration test, we'll change it to extend GroovyTestCase instead. Let's add a few handy imports as well:

import grails.test.*

import org.codehaus.groovy.grails.commons.ApplicationHolder
import org.codehaus.groovy.grails.commons.GrailsApplication
import javax.sql.DataSource

class JamonGrailsPluginTests extends GroovyTestCase {

I'll add a couple variables for brevity sake:

def app = ApplicationHolder.application
def ctx = app.mainContext

Next we'll add the boiler plate setUp and tearDown methods. I like AgileDox naming so I'll override getName() as well:

protected void setUp() {
        super.setUp()
    }

    protected void tearDown() {
        super.tearDown()
    }
    
    public String getName() {
        return super.getName().substring(4).replaceAll("([A-Z])", " \$1").toLowerCase();
    }

This first test will be to verify the dataSources have been updated with the jamon proxy:

void testDataSourcesAreJamonEnabled() {
        ctx.getBeanNamesForType(DataSource).each{ beanName ->
            def bean = ctx.getBean( beanName )
            assertEquals "com.jamonapi.proxy.JAMonDriver", bean.driverClassName
            assert bean.url.startsWith("jdbc:jamon:")
            assert bean.url.contains('jamonrealdriver=')
        }
    }

We make use of the Spring method getBeanNamesForType() to get all beans subclassed from DataSource, then simply test the attributes we attempted to set.

To verify that jamon is configured in the Spring context, we need a class in the plugin, such as a service class, to verify it is included in autoProxyCreatorBean. We can add a service by the grails command 'grails create-service jamonTest'. Of course we do not want the class added to our target applications, so we add the classname to the pluginExcludes variable in JamonGrailsPlugin:

def pluginExcludes = [
     "grails-app/views/error.gsp",
     "grails-app/services/JamonTestService.groovy"
   ]

Now we can code out test:

void testJamonHasSpringAop() {
        assertNotNull ctx.getBean("jamonInterceptor")
        def autoProxyCreatorBean = ctx.getBean("autoProxyCreator")
        assertNotNull autoProxyCreatorBean
        assertArrayEquals (["jamonTestService"].toArray(), autoProxyCreatorBean.beanNames.toArray()) 
    }

The remaining tests can be coded in a similar fashion. It is a good idea to include tests for all the plugin behaviours as well as any bugs that creep up over time.

That is it for the JAMon series. Hope these articles saved you some time. Your comments are encouraged!