Apache Solr is an open source enterprise search service from the Lucene project. Solr is written in Java and runs as a standalone full-text search server within a servlet container such as Tomcat.

Like any service or component in your architecture, you’ll want to monitor it to ensure that it’s available and gather performance data to help with tuning.

In this post, we’ll look at how we can monitor Solr, what performance metrics we might want to gather and how we can easily achieve this with Opsview.

A check list for service checks

Solr is built on Lucene so follows the same layout, an index contains documents that are comprised of fields. As part of the search service value add over Lucene, Solr provides a number of useful ways of obtaining health status / monitoring metrics:

1. Health-check status using the /admin/ping handler
2. The admin statistics page /admin/stats.jsp (XML styled with XSL)
3. JMX MBeans

The list of applicable checks could be defined by whether it is a health check or a data gathering check – but this would lead to a lot of overlap. Instead the list is divided into the checks that can be performed remotely (without an installed agent on the server) and those that are best performed locally to the Solr server.

Remote (agent-less) checks

What should we look for over the network?

Firstly we can have a host-level check which may perform a network level ping. Next we can check TCP connectivity to the servlet container port and then make an HTTP GET request to the Solr ‘front page’ and check for a known string (e.g. Welcome to Solr).

Now we’ve made it up to the application layer so can start to perform Solr specific checks.

Items to monitor may include (delete as applicable):

1. Ping status
2. Number of docs
3. Number of queries / queries per second
4. Average response time
5. Number of updates
6. Cache hit ratios
7. Replication status
8. Synthetic queries

Agent-based checks

Installing an Opsview agent on the Solr server means we can run additional checks over NRPE (Nagios Remote Plugin Executor). This could be operating system level checks such as memory/disk utilisation or CPU load, or the following:

1. Java servlet container process is running
2. JMX checks e.g. heap memory or custom MBeans
3. File age
4. Log parsing for exceptions

The Solr wiki describes how to configure JMX support: http://wiki.apache.org/solr/SolrJmx.

Opsview configuration

For the rest of this article you’ll need to have Opsview installed (or the Opsview VMWare appliance) and have completed the Quick Start.

Solr-specific Plugin

Install the Solr plugin at https://github.com/rbramley/Opsview-solr-checks into /usr/local/nagios/libexec/

The check_solr plugin was developed using Perl, so that it could be contributed back to Opsview. It requires the CPAN XML::XPath module (sudo cpan -i XML::XPath).

The plugin includes usage instructions, check_solr -h which can also be viewed in Opsview by selecting the ‘Show Plugin Help‘ link beneath the Plugin drop down (see Figure 1). The -u option can be used to specify the URL path for multi-core set-ups.

Service check setup

Figure 1 gives an example of a service check configuration.

Figure 2 shows the agentless service check group with plugins and their arguments.

Host configuration

Figure 3 shows a simplistic host setup with a ping check.

Figure 4 is an extract from the Monitors tab, where we select the checks we want performed for the current host.

Viewing output

The check results shown in Figure 5 are visible by navigating through the host group hierarchy.

If you click on the graph icon of Solr Cache Hit Ratios this will drill down onto the graph shown in Figure 6.

Clicking on the graph icon for Solr Avg Response Time – standard will take you to the graphs in Figure 7.

If you shutdown Solr, then the check results will start to turn critical and show in red as per Figure 8.

Alternatives

There are a few other plugins available for monitoring Solr from Opsview, depending on your needs:

• http://code.google.com/p/nagios-plugins-shamil – provides ping, replication status and num docs
• http://code.google.com/p/solr-nagios-check – provides QPS, response time and num docs

Also, chapter 8 of the recently published Apache Solr 3 Enterprise Search Server book includes a section on Monitoring Solr Performance.

Summary

Using check_solr in conjunction with Opsview allows you to ensure that your Solr server is available and provides you with metrics that can help you tune your Solr configuration.

This can be complemented with additional agent-based operating system and JMX checks to give you a full picture view.

Hindsight is a wonderful thing.

In hindsight, Opsview would have always had access controls for objects at the role level – since roles also define which parts of the Opsview application you can get to, it would make sense to also put all the host and service objects into this definition.

(In our defence, we wanted to make it as obvious as possible for a contact when you were changing access information.)

The downside of our design decision many years ago is that Opsview administrators who have lots of their users – or contacts in Opsview terms – with the same sort of access and were having to change each user individually. This was painful and error prone if you had 40 “similar” users.

So Opsview Enterprise 3.12.0 now has access information in the role definition. You change access at the role level and it automatically affects all users of that role. Even better, we ensure that a user’s notification profile only has references to the objects they are allowed – change the role definitions and object references will be automatically removed from all aspects of that contact.

Now you can administer users in a much simpler way.

Hindsight – we wish we had more of it.

But the next best thing to hindsight – migratability.

Migratability?

The Opsview configuration database is normalised and models the data as it is. Some application designers like to use key-value pairs to describe their data, which is nice from an expandable point of view, but rubbish when it comes to actually accessing that data in a meaningful way. When it comes to modelling our data, we model it – we don’t “meta-model” it.

We care a lot about people’s data because we build up a trust with our users that they can upgrade and bring their platform right up to date with the latest versions of Opsview. So we spend a lot of time getting the upgrade scripts just right.

If you are upgrading to Opsview 3.12, here’s what the upgrade scripts do:

• for each contact, it will see if this contact’s role has access information applied
• if it hasn’t, it will use this contact’s access information to populate the role
• if the role already has access information (from another contact), then it will compare all the current roles with their access information and if there is a match, this role is used
• if it isn’t exactly the same, then a new role is created called “old role name – contact”

So for example, let’s say you have 4 contacts – John, Paul, George and Ringo – all using the “Liverpool administrators” role.

The first three have their access information the same, but Ringo has missed out the Production – Slicehost Servers host group he should have had access to.

After the upgrade, the first three would still have the role of Liverpool administrators, but Ringo would have the role of a newly created Liverpool administrators – ringo. You could easily tell from this that Ringo should belong to the Liverpool administrators, so you can set him to this. Otherwise, maybe he is different after all, so you can rename the role to Liverpool drummers.

This means that most of the configuration for this new functionality is done for you automatically and you can think of your users in their role groups, rather than individually. Another step to making Opsview easier to use.

Opsview Community 3.11 - Free distributed monitoring

One of Opsview’s great features is distributed monitoring, which we’ve had for over 5 years now. From the web user interface, you can assign hosts to a slave system and Opsview will take care of all the configuration work for you: from the slave configuration files, to the slave results sent to the master, to the master configuration with freshness checking.

We do all the system integration work, so you don’t have to.

However, there are some limitations in our chosen technologies. We use NSCA, which is the most common method in the Nagios® world, and while we’ve made improvements to it that have gone back upstream, there are some baked-in limitations:

• Only the first 511 bytes of plugin output was returned to the master, limiting the usefulness of the information you could display
• Only the 1st line of data was returned, meaning you had to cram output together
• NSCA communication used fixed size packets which were inefficient
• While results were sent, Nagios would wait for completion, introducing a bottleneck
• If there was a communication problem with the master, results were dropped

Sometimes to move forward, you have to leave the past behind.

So we did that – we ripped out NSCA from Opsview’s slave communications and we’ve addressed every one of these limitations – and added a few nice extras too!

We’ve chosen NRD (Nagios Result Distributor) as our core technology. This is a library, written by one of our partners, CAPSiDE. There are many reasons we chose this, but the top four are:

• It is based on perl, which is our language of choice
• It has taken the test suite we developed for NSCA and enhanced it, demonstrating a mature approach to code development
• The client and server code is a thin shim over the libraries, which means you can easily create your own clients
• We have a good relationship with CAPSiDE and they have given us access to their code repository

We’ve spent some time understanding the core NRD code, enhancing it, fixing some issues and adding in some great new features. CAPSiDE have also released it on CPAN for wider consumption.

So Opsview’s new process for sending results from a slave is:

A couple of other amazing features we’ve squeezed in:

• A known Nagios limitation is the named pipe to submit results. We’ve overcome this by writing directly to the checkresults spool directory – this reduces a Nagios processing cycle on the Opsview master
• We’ve implemented transactions in the results, so if the client has a failure communicating to the server, the client will back off and retry again in 5 seconds. This guarantees you do not have duplicated results
• The nrd daemon on the master will dynamically add more servers as workload increases, thanks to the features of Net::Server
• As all communication between master and slaves is over a tunnelled SSH session, we’ve updated our Opsview check scripts to restart these tunnels if the slave is exhibiting communication errors

With all this extra capabilities, you would think there is a cost in performance. But in fact, our testing shows that performance has got better!

(Based on sending 2016 results in a single transaction over an SSH tunnel from a slave to a master. Times measured on the client.)

This shows that we are getting an average 62% improvement in all aspects of slave communication back to the master!

We are thrilled we’ve added this major new functionality into Opsview and have taken distributed monitoring another huge step further over any of our competitors.

But the best thing is: this is available immediately with our Opsview Community 3.11 release. Install the VM, add a slave and you will get this new architecture setup as part of the process. And if you are an existing Opsview user, you get a silky smooth switch-over. We’ve done a lot of testing to ensure that as part of the upgrade, Opsview will automatically switch any slaves to this architecture and start sending results in the new NRD way.

We’ve just fixed a bug in Nagios® which an Opsview user had raised to us. A change made to Nagios in version 3.2.2 caused an issue where service alerts were being raised in the nagios.log file for every result that came back from a host that was down. This had the impact of adding lots of extra alerts that were overwhelming Opsview’s event views.

To reproduce the problem in Nagios 3.2.3:

1. Create a host with 2 service checks
2. Let this run normally
3. Shutdown the host
4. The first service check will notice the state change and set the host to be checked. It will go into a SOFT state and the service will go into a check attempt of 2 and continue into a hard state correctly
5. The 2nd service check will see that the host is DOWN and force a hard state failure with check attempt 1 of a maximum 4. However, this hard state change did not set the last_hard_state flag correctly, which meant every subsequent check was considered to be a new hard state failure and hence a SERVICE ALERT was raised every time in nagios.log

This took a long time to track down, but we’ve found the problem and fixed it. Our fix is pushed to Nagios already.

While this bug is annoying, we’re upset that this had an impact on a customer system. We make it our principle to keep as up to date with Nagios as possible because Opsview is a shallow fork of Nagios – we make only the changes that are necessary to support our customers and we push our changes back upstream where we can.

We’ve developed a lot of trust with our users – we make the upgrade process for Opsview as easy as possible because we want all our users to get to the latest version (in fact, we’ve just had one user update their Opsview from 4 years ago, right up to the latest version, going through over a hundred database changes!).

One thing we do to make sure our systems work as expected, is to continuously test our latest versions of Opsview. We use Hudson to test Opsview on every change – currently this runs 5269 individual tests, taking 1 hour 46 minutes.

We want to bring this level of quality assurance to Nagios – included in our fix is a test case that checks exactly this issue. Running tests on Nagios will now show that this problem is fixed forever and our nightly builds of Opsview includes these too.

So now everyone can sleep easier knowing that this problem is never going to happen again.

Please note: Nagios, the Nagios logo, and Nagios graphics are the servicemarks, trademarks, or registered trademarks owned by Nagios Enterprises

We present the 2nd part to our Catalyst advent calendar entry about internationalising your Catalyst application, complete with some really neat scripts such as automatically translating your string using Google! See it here. Enjoy!

I thought it might be interesting if I provided some insight into how we decide which features are included in each Opsview release cycle.

The long and winding roadmap

We are very lucky to have a committed user community and this is a great source of feedback and ideas. Part of my role is to work with customers and prospective customers to figure out how to get the most out of Opsview in their IT environments. This is another extremely valuable source of feedback about how existing features could be developed and which new features we should be considering. One of our biggest challenges is taking all of these great ideas and figuring out which ones the product development team should work on.

Ideas are captured in our Atlassian JIRA system and this forms the feature backlog. For a feature to move from the backlog to the product roadmap it goes through a scoring and review process. This allows us to work out what the relative priorities are and how much effort will be involved in developing the feature. The scoring system takes into account the following factors:

• Opsview Enterprise customer feedback
• Opsview Community feedback
• Feedback from pre-sales discussions with potential customers
• Input from the Opsview team
• Where the feature sits in terms of our long term product strategy
• The level of complexity involved in developing the feature

The resulting score helps us to narrow down the feature backlog to a roadmap covering the next year of releases. Usually this comprises three Community release cycles with corresponding Enterprise releases. The roadmap is under constant refinement and there is always scope to insert features or change priorities. This allows us to remain flexible and responsive.

If a feature is sponsored it will usually take priority. Features requested by our customers receive a higher weighting however the features appearing top on the roadmap are usually those where there is a high level combined of interest from customers, pre-sales and community users.

From concept to code

Customer / Community (User) feedback is our primary source of feature ideas since this means we’re always addressing ‘real’ issues. Our challenge is to translate ideas into more concrete feature specifications and then into code. This is where the Opsview team’s creativity is involved, spotting related threads, designing solutions that will work for everyone and figuring out the tricky details.

In Part 2: How our recent Customer Survey has influenced the Product Roadmap

So, what’s up in the Opsview’s world?

We’re comparing APIs. A user was asking how Opsview’s API compares to Icinga’s API. We spent a bit of time investigating what the competition are up to.

What’s an API?

According to Wikipedia, an Application Programming Interface is a way of having two programs talk to each other, in a known and consistent way.

So what does Icinga’s API do?

Looking at their documentation, they have two APIs: a plugins API and a status API (which they call the Icinga API). The contents of the plugins API document looks almost exactly the same as the Nagios document – it looks like some liberties were taken there.

But the main point is that anything that calls itself “Nagios-compatible” will use the same Nagios Plugins API, in order to reach into the large number of plugins that are available. Opsview also uses the Nagios Plugins API – we just don’t make much noise about it.

So it’s nothing special?

Correct.

You said there were two APIs?

Their 2nd API is a status API, a way of getting host and service state information. It looks like it is just a thin layer to getting information from their recommended data store using IDOUtils. IDOUtils is based on NDOUtils, which Opsview has been using for the last 4 years (where we’ve also sent back lots of fixes and enhancements back upstream). The type of status information available in the database is very rudimentary: is this host up or down? Is this service critical or not?

So how does it stack up next to Opsview?

Here’s why I think the Opsview API is superior:

• Our API is a webservice, so anything that can talk HTTP can communicate with it. Our community have written dynamic web pages which present the data in a different way and we have a perl module on cpan to easily get data back. We’ve even prototyped a dashboard app to prove its functionality
• Our API requires authentication, so users only see what they are allowed to see. Icinga’s API is wide open, which means the responsibility for security falls onto programmers rather that the system itself
• Our status APIs aggregate data, so you can get information like in the host group hierarchy pages which gives summarised totals for host and service states based on hierarchical information. The Icinga API will not scale to thousands of hosts because a program would need to count each state itself

Opsview Community: Host Group Hierarchy

Here’s the XML that describes the data on that page:

<opsview>
  <data name="hostgroup">
    <list name="Development Systems" downtime="2" hostgroup_id="19">
      <hosts handled="38" total="38" unhandled="0">
        <unreachable handled="1" />
        <up handled="37" />
      </hosts>
      <services handled="279" highest="critical" total="283" unhandled="4">
        <critical handled="7" unhandled="4" />
        <ok handled="263" />
        <warning handled="9" />
      </services>
    </list>
    <list name="Production Systems" downtime="2" hostgroup_id="18">
      <hosts handled="15" total="16" unhandled="1">
        <unreachable unhandled="1" />
        <up handled="15" />
      </hosts>
      <services handled="82" highest="critical" total="82" unhandled="0">
        <critical handled="4" />
        <ok handled="77" />
        <warning handled="1" />
      </services>
    </list>
    <summary handled="414" total="419" unhandled="5">
      <host handled="53" total="54" unhandled="1" unreachable="2" up="52" />
      <service critical="15" handled="361" ok="340" total="365" unhandled="4" warning="10" />
    </summary>
  </data>
</opsview>

Wow, that’s neat!

Yes, because it decouples the data from the presentation. But the biggest advantage with our API is that it includes the ability to make configuration changes.

Why is changing your configuration via an API useful?

It’s for automating changes. We have users that write scripts to talk to the API to add and delete hosts as part of their build process. Some users hook Opsview to their central configuration databases. As nice as our web UI is, you don’t want to be doing regular changes all the time in the browser.

So Opsview comes out on top?

Yes, but I think this is because API is a bit of a loose term. Icinga’s use of API is “how to write programs to get status information”. Opsview considers “API” to mean “getting status data and making changes via a webservice”. On those grounds, I think its a bit unfair to compare the APIs at the moment because the Opsview API is doing much more, at a much higher level.

Got any plans for the future?

Definitely! But I’ll tell you about them later

Update: 24th September 2010

What’s this? Someone trying to defend themselves?

Yes, I think the Icinga chaps have got a little bit twitchy! I especially like the link to the documentation for the REST Adapter API which is titled The Hidden Documentation – clearly they don’t think it is worth making it official.

But it’s good, right?

It’s a start

Since Grails incorporated the testing plugin into core it provides good unit & integration testing support (via the test-app script). There are also additional plugins to support BDD tools (e.g. EasyB) and functional testing (e.g. Canoo WebTest).

One of the useful roles that Hudson fulfils is helping to manage quality. Consequently it has plugins available for most of the popular testing tools (we saw an example of the Violations plugin in part 1 of this series).

We’ll start with the standard unit & integration tests, then add in test coverage and functional tests.

Unit tests Assuming you already have unit/integration tests in your Grails project – we need to add the targets into the Grails builder options. clean compile "test-app -unit -integration"

Notice how the server port has been set to prevent port collision with the servlet container running Hudson.

Tip: you’ll need to set this differently on each job too.

Then set the post-build action:

After a couple of builds (so that there is a trend), Hudson will show:

With blue for tests that passed and red for failed tests. You can also drill into the test results just as with the standard HTML junit reports.

Test coverage As we’re looking to use Hudson to help ensure the quality of the software project, we’ll also inspect the level of test coverage as one of our quality metrics.

Warning: determining test coverage isn’t foolproof and high levels of coverage don’t guarantee good code or good tests. It is possible to achieve a high percentage with poor tests (I’m writing a separate post on this topic).

For this post, we’ll be using Cobertura to check the code coverage. There are other options, but we’ll be using Cobertura because:

1. There is a Grails plugin
2. There is a Hudson plugin too.

Install the Grails code-coverage plugin grails install-plugin code-coverage

You may want to configure additional exclusions in BuildConfig.groovy, e.g. to avoid testing 3rd party code such as a plugin taglib that isn’t used. (the plugin scripts/_Events.groovy includes a default list)

Install the Hudson Cobertura plugin This follows the same process that we covered in part 2 of this series (we’ll omit the screenshots this time):

1. From the main Hudson dashboard, click on the “Manage Hudson” menu item
2. Click on “Manage plugins”
3. Go to the available tab, find & select Cobertura, click on the install button.
4. When the plugin has downloaded and installed, you will need to restart Hudson (you can use the button provided).

Configure your Hudson job There are 2 things that need to be done here:

1. Set up the Grails build action
2. Enable the post-build action for Cobertura

1. This is a case of adding “-coverage -xml” into the build targets within the test-app double quoted section. 2. Enable the Cobertura post-build processing, tell it where the XML report is and set thresholds:

Leverage the information

Watch the trends:

and drill down to see the in-context coverage:

When you have the insight as to where you are missing coverage, then you can take the appropriate action to remedy the situation…

Functional tests There are a number of options for functional testing your application. We’ll cover Canoo WebTest in this post for the following reasons:

1. WebTest is htmlunit based – portable across different environments
2. Canoo have written a Firefox WebTest Recorder add-on – allowing less technical users to create the basis of the tests
3. There is also a WebTest Presenter plugin for Hudson.

Note that as WebTest isn’t browser-based, you may encounter some issues with JavaScript on particular test scenarios.

Install the Grails webtest plugin grails install-plugin webtest If you are using older versions of Grails, you may need to do an interactive plugin install on the Hudson server (the plugin used to download a WebTest bundle, rather than having it as a managed dependency).

Install the Firefox WebTest Recorder add-on You can install the WebTest Recorder in Firefox from: https://www.canoo.com/webtestrecorder-dist/webtestrecorder.xpi

Create some web tests You can come back to this bit later

The process we’ll follow here uses the WebTest Recorder to create the initial test steps.

1. Run “grails create-webtest name” e.g. grails create-webtest HomepageLogin

This plugin script will create us the placeholder test file under test/webtest.

2. grails run-app

3. Bring up Firefox 4. Navigate to the starting page for your test scenario. 5. Enable the WebTest Recorder Sidebar (Tools > Webtest Recorder Sidebar) 6. Click on the Groovy tab.

This should already contain “invoke http://localhost:8080/YourGrailsApp/” (you’ll probably want to trim this down to just a relative path e.g. /YourGrailsApp/)

Using the Webtest Recorder Sidebar, you can click around the site and also easily add verification of content on pages (as a test isn’t a test if you don’t verify that the output is correct for the given input). This can then be placed into a method in the groovy file we created earlier (note: you may need to trim some instructions e.g. where the recorder has created different versions for the same input field). For more information using Webtest, see the manual.

I’d strongly advise you to run your tests locally first before checking them in – in the interests of time/space we’ll assume you’ve done that using: grails test-app -functional

Install the Hudson WebTest presenter plugin This follows the same process as the Cobertura plugin above (see part 2 of this series for screenshots):

1. From the main Hudson dashboard, click on the “Manage Hudson” menu item
2. Click on “Manage plugins”
3. Go to the available tab, find & select WebTest Presenter, click on the install button.
4. When the plugin has downloaded and installed, you will need to restart Hudson (you can use the button provided).

Configure your Hudson job There are 2 things that need to be done here:

1. Set up the Grails build action
2. Enable the post-build action for the WebTest Presenter

1. This is a case of adding “-functional -headless” into the build targets within the test-app double quoted section (The headless option tells Webtest to not run the test monitor nor to load the test results into the browser).

2. The Webtest Presenter post-build action needs enabling and telling where to find the results

After the Hudson job has executed your webtests, you’ll see that these have been included in your overall test count (and may even have improved your test coverage if you’ve followed the Cobertura section above).

If you click onto an individual build, the left hand menu will now have “Webtest Results”

This will give you an overview report:

and a detailed step-by-step report for each test (including resulting pages and any errors):

So there you go, a whistle stop tour of setting up test execution, coverage analysis and result reporting with trends.

Next in the series, we move into using Hudson for continuous deployment of Grails projects.

Ok, so you’ve decided that you want to use Hudson to build your Grails projects (or have read part 1 and want to use CodeNarc too). If you don’t know where to start, you’ve come to the right place.

The basic steps (and we’ll go into more detail on each one) are:

1. Download Hudson
2. Run Hudson
3. Download Hudson plugins
4. Configure Hudson
5. Create a Hudson job
6. Watch the trends

This post will get you started and subsequent posts in the series will add even more power to your CI process.

Step 1 – Download Hudson

Hudson is packaged as a Java web application archive (war file) and can be downloaded from hudson-ci.org. The 1.373 war is available from here.

Debian/Ubuntu users can install Hudson using ‘apt-get install hudson‘ (but if you’re on stable, it isn’t the latest version).

Step 2 – Install/run Hudson

Before we dive into the installation, you’ll need some pre-requisites installed:

• Java JDK (6 is best)
• Grails (whichever version you’re using)

As previously mentioned, Hudson comes as a war file and so it can be deployed to a servlet container such as Tomcat. The Hudson war file also includes the lightweight Winstone servlet container so can be run using: java -jar hudson.war

Note that Hudson uses ~/.hudson as a working directory by default.

Key folders are: jobs - job configuration, the workspace and builds are stored here plugins - plugin .hpi files are unpacked to directories beneath this war - the Hudson war file is unpacked here

Step 3 – Download Hudson plugins

Once you’ve got Hudson running – we’ll start by getting the Grails plugin.

Click on the “Manage Hudson” menu item

Click on “Manage plugins”

Go to the available tab, find & select Grails, click on the install button.

When the plugin has downloaded and installed, you will need to restart Hudson (you can use the button provided).

Note: you can also manually install downloaded/compiled Hudson plugin .hpi files into ~/.hudson/plugins

Step 4 – Configure Hudson

Now we need to set-up the JDK and Grails – so have their paths handy.

Click on the “Manage Hudson” menu item

Click on “Configure System”

Step 4.1 Set-up the JDK

1. Give it a name
2. Set the JAVA_HOME

Step 4.2 Set-up Grails

1. Give it a name
2. Set the GRAILS_HOME

Congratulations, you’re now ready to set-up your first Hudson job.

Step 5 – Create a Hudson job

If you have lots of Grails projects, you’ll only need to do this from scratch the first time as Hudson allows you to copy existing jobs.

Click on the “New Job” link

1. Enter a job name (Tip: Hudson will use this for a directory name – so be careful what characters you use)
2. Select “Build a free-style software project”
3. Click “Ok”

For the first pass at the configuration, let’s assume that you have a working copy of the code locally (you can always come back to set-up the Source Code Management settings).

We need to add the Grails build step, so click on “Add Build Step”

This will give you an option list – select “Build With Grails”

You can now perform the basic configuration of the Grails step. Let’s set it to do a clean, followed by execution of the unit tests: clean "test-app -unit"

Unless you’ve set up the SCM configuration, you’ll want to specify the root of the Grails application in the “Project Base Directory” too.

Finally, we want Hudson to publish the unit test results (this is relative to the workspace under ~/.hudson/job/Example/workspace).

If the working copy is clean, Hudson may complain that the XML results or the target directory do not exist – this can be safely ignored for now.

Now ‘Save’ the job using the Save button at the bottom of the form and test it using the “Build Now” link.

If the build passes, it will be marked as blue (this can be changed to green balls with a plugin).

If the build fails, then click on the failed job

and look at the error message under “Console Output”.

E.g. If you select Subversion as an SCM option, but leave the form blank:

Step 6 – Watch the trends

Assuming you’ve got it all working – after you’ve performed a few builds, Hudson will start to show build trends on the job page…

We’ll add more statistics to this view in later posts in the series.

The first part of a series of posts on Grails and Hudson leading up to a presentation at the London Groovy & Grails User Group. Subsequent instalments will include testing (unit, integration, functional), test coverage, automatic war deployment and monitoring Hudson with Opsview Enterprise.

Grails has a rich plugin eco-system with over 400 hundred plugins – so it’s easy to miss something useful. If you’re serious about software craftsmanship, then using static code analysis tools should be part of your quality regime as it gives further insight into the code base (and if you insist, yes it’ll help with your Technical Debt management).

CodeNarc provides static code analysis for Groovy and the CodeNarc plugin for Grails allows you to perform this analysis with the “grails codenarc” script. Behind the scenes this uses the CodeNarc ant task and settings from grails-app/conf/Config.groovy and produces an HTML report by default.

Until recently, if you used the codenarc target within a continuous integration server such as Hudson – then the HTML report would be generated and sit in the workspace waiting for a diligent developer to check it. You can imagine how often that happens in practice with all the other demands of a project!

However, I’ve now integrated the CodeNarc XML output with the Hudson Violations plugin so that an overview trend line is shown against the Hudson job. Then the team quickly fixed the violations…

You can also get a breakdown by priority:

And in-context views of the violations so you know what to fix:

This is how you do it…

Grails config.groovy codenarc { reportName = 'target/test-reports/CodeNarcReport.xml' reportType = 'xml' // any further settings like maxPriority1Violations=0 }

Hudson

Set up your Grails build step – normally you’d add the ‘codenarc’ target:

The codenarc.properties file can be used to configure specific exclusions, the location of this file can be passed in as a system property (shown above).

You need to have installed the violations plugin (Manage Hudson > Manage Plugins > Available and search for Violations). As this is a recent addition, I’m using a patched version of the Violations plugin, though the patch has been integrated into trunk (I’ll update when it is released). Configure violations:

Note the ‘Faux project path’ – you may need to set this to get an in-context view working properly due to path (e.g. if your code is checked out to workspace/trunk)

I also had a contribution to CodeNarc accepted at the weekend to add aninlineXml report type – this will, with a minor tweak to the CodeNarc parser, allow the Hudson Violations plugin to give the rule description on the pop-up message.