4. Instrumenting Applications

This chapter describes how to set up your application to use Instrumented Spring Framework, Web Services, Web Flow, and Security. It outlines the necessary build and configuration steps that will allow Instrumented Spring products to automatically export their components to your application's JMX MBeanServer and enable automatic monitoring of those components. If you do not already use Spring Framework, you can learn more about it from Spring Framework Reference.

4.1. Adding Instrumented JARs to Applications

The JARs that you must add to your application are in the "dist" and "lib" directories of the unpacked spring-<instrumented product>-instrumented-management zip files for Instrumented Spring Framework, Web Services, Web Flow, and Security.

[Note]Note

If you will be replacing open source JARs with corresponding instrumented JARs, your replacements must be of the same maintenance release, that is, a release where the first and second digits of the release numbers are identical. For example, you can replace open source Spring Web Flow 2.0.0 with Instrumented Spring Web Flow 2.0.8. However, you cannot replace open source Spring Framework 2.5.x with Instrumented Spring Framework 3.0.0. You must first upgrade to Spring Framework 3.0.x. To do so, refer to the Spring Framework Upgrade Guide and the 3.0 Spring Framework Reference.

The JARs you need to use depend on the application you are instrumenting. For more information about these JARs, see JAR Components.

  • org.springframework.<module>.instrumented-<version>.jar: Instrumented JARs that are compile-time woven versions of their open source counterparts.

  • com.springsource.management.instrumentation.<instrumentedproduct>.<module>-<version>.jar: Instrumentation JARs that contain the AspectJ aspects used to weave the instrumented JARs at compile time.

  • com.springsource.management.agent.<module>-<version>.jar and com.springsource.management.adapter.<module>-version.jar: Spring Framework JARs that contain the API used to auto-discover Spring beans, export them to JMX, and obtain and store monitoring data.

Adding Instrumented Spring Framework JARs to Applications

Add the instrumented JAR files to your application classpath. If you are already using open source Spring Framework, replace each Spring Framework JAR in your application with the corresponding instrumented JAR in the dist directory. These jars are named org.springframework.<module>.instrumented-<version>.jar. See Mapping Maven Central JAR Names to EBR JAR Names if you originally obtained your non-instrumented Spring JAR files from the Maven Central repository.

[Note]Note

You cannot use both an instrumented JAR file and its open source equivalent. You must remove the open source JAR and add the corresponding instrumented JAR in its place.

For each instrumented JAR that you add to your application, include the matching instrumentation JAR, com.springsource.management.instrumentation.springframework.<module name>-<version>.jar. These instrumentation jars contain the aspects and Java classes used to manage and monitor the components in the instrumented JAR. Make sure you include com.springsource.management.instrumentation.springframework.applicationcontext.jar. It must be present to enable auto-discovery.

Some instrumentation JARs are shared among the instrumented Spring modules. For example, subclasses of AbstractPlatformTransactionManager exist in multiple jars. As such, all of these JARs may have a dependency on the com.springsource.management.instrumentation.springframework.transaction.manager.jar. When in doubt, consult the Import-Packages statement of the instrumented jar Manifest for the required dependencies.

Include the following Management API jars:

  • com.springsource.management.adapter.jmx-<version>.jar

  • com.springsource.management.agent.bootstrap-<version>.jar

  • com.springsource.management.agent.config-<version>.jar

  • com.springsource.management.agent.control-<version>.jar

  • com.springsource.management.agent.discovery.domain-<version>.jar

  • com.springsource.management.agent.discovery.resource-<version>.jar

  • com.springsource.management.agent.inventory-<version>.jar

  • com.springsource.management.agent.monitoring-<version>.jar

Include one of the following, depending on whether you are instrumenting a standalone application or a web application:

  • com.springsource.management.agent.discovery.application.standalone-<version>.jar OR

  • com.springsource.management.agent.discovery.application.web-<version>.jar

Adding Instrumented Spring Web Flow, Web Services, and Security JARs to Applications

Add the instrumented JAR files to your application classpath. If you are using open source versions of these products, replace the JARs in your application with the corresponding instrumented jars in the dist directory of the Instrumented Spring Web Flow, Web Services, and Security components. These jars are named org.springframework.<module>.instrumented-<version>.jar. See Mapping Maven Central JAR Names to EBR JAR Names if you originally obtained your non-instrumented Spring JAR files from the Maven Central repository.

[Note]Note

You cannot use both an instrumented JAR file and its open-source equivalent. You must remove the open-source JAR and add the corresponding instrumented JAR in its place.

[Note]Note

The latest Instrumented Spring Security (2.0.6) does not include instrumented versions of all jars distributed with open source Spring Security 3.0.x. Use the open source Spring Security 3.0 instead of instrumented Spring Security if you need these additional jars. (Spring Security 3.0.x requires Spring Framework 3.0.x.)

For each instrumented JAR that you add to your application, include the matching instrumentation JAR, com.springsource.management.instrumentation.<instrumentedproduct>.<module name>-<version>.jar. These instrumentation jars contain the aspects and Java classes used to manage and monitor the components in the instrumented JAR.

Mapping Maven Central JAR Names to EBR JAR Names

Typically, when you write your Spring applications, you obtain the Spring JAR files from one of the following two repositories:

  • Maven Central, which is the default repository for Maven queries.

  • Enterprise Bundle Repository (EBR), which is run by SpringSource and also hosts all the libraries that integrate with Spring.

However, it is important to note that each repository uses a different naming scheme for the JAR files. The Spring instrumented JAR files are all based on the naming in EBR. This means that if you originally obtained your non-instrumented Spring JAR files from Maven Central, and now want to replace them with instrumented JAR files, you will need to translate the JAR names appropriately.

For example, if your application uses the non-instrumented JAR file from Maven Central called spring-webmvc-version.jar and you want to replace it with the instrumented JAR, you would replace it with the following file: org.springframework.web.servlet.instrumented-version.jar.

The following table lists the most common Spring JAR names, first using their Maven Central names and then their corresponding EBR name.

Table 4.1. Mapping Between Maven Central and EBR JAR Names

Maven Central JAR NameEBR JAR Name
spring-aoporg.springframework.aop
spring-asmorg.springframework.asm
spring-aspectsorg.springframework.aspects
spring-beansorg.springframework.beans
spring-contextorg.springframework.context
spring-context-supportorg.springframework.context.support
spring-coreorg.springframework.core
spring-expressionorg.springframework.expression
spring-instrumentorg.springframework.instrument
spring-jdbcorg.springframework.jdbc
spring-jmsorg.springframework.jms
spring-ormorg.springframework.orm
spring-oxmorg.springframework.oxm
spring-testorg.springframework.test
spring-txorg.springframework.transaction
spring-weborg.springframework.web
spring-webmvcorg.springframework.web.servlet
spring-webmvc-portletorg.springframework.web.portlet