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 Grails Logging

I am in the middle of a Grails/Flex project. One of the criteria involved with the selection of Grails was the large number of blogs, articles and documentation available.

The other criteria was, of course, improved productivity.

We have an aggressive deadline of eight weeks. Our customer chose the Drupal CMS for the site, but we had concerns about it's suitability and scalability. We ended up using Drupal for it's strengths, like FAQ's, blogs, etc. We selected Grails for the bulk of data handling and Flex for the front end. (No one does "eye candy" as well as Flex. Perhaps JavaFX some day, but today it is Flex.)

For the most part, Grails has grown so popular it has been easy finding solutions to common problems. However, one area lacking in advice is, oddly enough, basic logging.

So here is our logging configuration. We use four appenders, the console and three rolling files. The console is designed to make watching the application as painless as possible. Besides the usual Grails output, it displays only error level logging.

The three rolling file appendars contain error, debug and trace level logging respectively. The error log is great for quickly determining if any errors have occurred.

The debug log is excellent for researching issues not made obvious by the error log. The trace log adds Hibernate data values to the queries if you really need that level of detail.

So here it is, a working Grails 1.1 version logging configuration, straight from Config.groovy. As it turns out, the best source for learning about this is the documentation from the Grails web site.

I hope you find this useful:

log4j = {

 appenders {
  console name:'console', threshold:Level.ERROR,layout:pattern(conversionPattern: '%p %d{ISO8601} %c{4} %m%n')
  rollingFile name:"rollingFileTrace", threshold:Level?TRACE, maxFileSize:1048576,  file:logFile+'Trace?log', ayout:pattern(conversionPattern: '%p %d{ISO8601} %c{5} %m%n')
  rollingFile name:"rollingFileDebug", threshold:Level?DEBUG, axFileSize:1048576,file:logFile+'Debug.log', layout:pattern(conversionPattern: '%p %d{ISO8601} %c{5} %m%n')
  rollingFile name:"rollingFileError", threshold:Level.ERROR, axFileSize:1048576,file:logFile+'Error.log', layout:pattern(conversionPattern: '%p %d{ISO8601} %c{5} %m%n')
 }

  error console, rollingFileDebug, rollingFileError, rollingFileTrace:
   'org.codehaus.groovy.grails.web.servlet',  //  controllers
   'org.codehaus.groovy.grails.web.pages', //  GSP
   'org.codehaus.groovy.grails.web.sitemesh', //  layouts
   'org.codehaus.groovy.grails."web.mapping.filter', // URL mapping
   'org.codehaus.groovy.grails."web.mapping', // URL mapping
   'org.codehaus.groovy.grails.commons', // core / classloading
   'org.codehaus.groovy.grails.plugins', // plugins
   'org.codehaus.groovy.grails.orm.hibernate', // hibernate integration
   'org.springframework'

  debug rollingFileDebug, rollingFileTrace:'org.hibernate',
   'com.britetab',
   'BootStrap',
   'org.apache.ddlutils'

  trace rollingFileTrace:'org.hibernate.SQL',
   'org.hibernate.type',
   'flex.messaging.services'

  warn  console,rollingFileDebug,rollingFileTrace:'org.mortbay.log',
   'org.hibernate.tool.hbm2ddl'

 root {
  error 'console','rollingFileError','rollingFileDebug','rollingFileTrace'
  additivity = true
 }
}