Instrumented Spring Reference Guide

The org.springframework.<module>.instrumented JARs are compile-time woven versions of their open-source counterparts. For example, the org.springframework.beans.instrumented JAR file is a drop-in replacement for the org.springframework.beans JAR distributed with open source Spring Framework.

Note

If you will be replacing open source JARs with instrumented JARs, your replacements must be of the same version as the corresponding open source JARs, that is, the first and second digits must be 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.

	Note
	The latest Instrumented Spring Security is version 2.0.6. If you need Spring Security 3.0.x functionality, use the open source Spring Security 3.0.x JARs instead of instrumented Spring Security. Spring Security 3.0.x requires Spring Framework 3.0.x.

The instrumented JARs have compile-time dependencies on the instrumentation JARs described in the next section. Spring Framework instrumented JARs may also have compile-time dependencies on Management API JARs described in Management API JARs.

The instrumentation JARs contain the AspectJ aspects used to weave the aforementioned instrumented JARs at compile time. Thus, an instrumented JAR will likely have a compile-time dependency on 0 to n of its corresponding instrumentation jars. Instrumentation JARs have the format com.springsource.management.instrumentation.<instrumentedproduct>.<module>-<version>.jar.

Spring Web Flow, Web Services, and Security instrumentation JARs have a dependency on Instrumented Spring Framework.

All com.springsource.management.agent.<module> and com.springsource.management.adapter.<module> JARs distributed with instrumented Spring Framework contain the API used to auto-discover Spring beans, export them to JMX, and obtain and store monitoring data. Thus, a Spring Framework instrumentation JAR will likely have a compile-time dependency on 0 to n of these management API jars.

Instrumented Spring Framework automatically discovers applications by advising the refresh method of the AbstractApplicationContext class. Any bean that is created through an AbstractApplicationContext will be discovered as a managed resource if the instrumented components know how to manage and monitor it. See Managed Beans for a list of recognized components. Some components created outside of ApplicationContexts (such as the DispatcherServlet) will also be auto-discovered. When an AbstractApplicationContext is closed, its associated managed resources are undeployed.

After managed resources are auto-discovered, the Spring Framework instrumentation automatically creates JMX ModelMBeans representing each application resource it discovers, and registers these ModelMBeans in an auto-detected MBeanServer. These MBeans contain predetermined attributes that represent metrics or properties of the resource being managed and operations that provide runtime control of the resource being managed.

All MBeans are registered under the domain spring.application. They are segmented by application (using an "application" key property) and contain "type" and "name" key properties. The "type" key property value typically refers to the component class (for example, "DispatcherServlet") and the "name" key property value is usually set to the bean name.

JConsole View of MBeans Automatically Exported by Instrumented Pet Clinic Application

Instrumented Spring Framework monitors most of its managed resources by using a combination of compile-time woven aspects and hooks into existing Spring Framework code. It also uses Spring AOP proxies to monitor the method executions of stereotyped components in your application (marked with @Controller, @Transactional, @Service, @Repository or @Component). This means that Instrumented Spring Framework attempts to create a Java dynamic proxy around your stereotyped component, if your sterotyped component implements an interface. If your stereotyped component does not implement an interface, Instrumented Spring Framework attempts to create a CGLIB proxy around your component. See Spring Framework Reference for more details about Spring AOP proxies. If the component cannot be proxied, it is still exported as an MBean; however, its metrics are never updated.

Instrumented Spring Framework provides visibility into the performance and resource utilization of the Spring container. For example, each ApplicationContext exposes execution time metrics for common operations such as refresh and getBean and provides the names of its bean definitions. Each BeanFactory provides the number of prototype and singleton beans created and the average execution time of the bean creations. Instrumented Spring Framework also provides runtime control of the Spring container. For example, ApplicationContexts allow runtime invocation of their refresh and close methods.

Components marked as @Component (stereotype indicating a generic Spring-managed component) or @Service (stereotype indicating a business service) are automatically exposed to the management model as well. As such, execution time of all the components' public methods will be monitored. This monitoring enables analysis of performance on a per use case basis.

Instrumented Spring Framework provides summary visibility into JDBC operations and transaction management. Spring DAO components expose metrics such as transaction commit and rollback rates, transaction throughput, and JDBC query execution throughput. Additionally, components marked as @Repository or @Transactional are exposed to the management model as services. As such, execution time of all the components' public methods will be monitored.

The object-relational mapping (ORM) integration in Instrumented Spring Framework exposes ORM statistics in a manner consistent with the rest of the application model. Currently, Hibernate and JPA are the only ORMs whose metrics are exposed to the Instrumented Spring Framework model. A number of Hibernate SessionFactory metrics are available, including query execution count and entity fetch count. JPA metrics are currently only related to transaction management. The JpaTransactionManager exposes transaction commit, suspend, resume, and rollback rates.

Instrumented Spring Framework provides visibility into Spring JMS, Java Mail, and thread-pooling integration components.

Instrumented Spring JMS provides data for JMS message senders and receivers. The MessageListenerContainers track the average execution time of message receipt and provide the number of failed message receipts. They expose the number of concurrent and/or scheduled consumer threads and allow you to modify the number of consumers, to help alleviate JMS queue backup at runtime. The JmsTemplate provides average time taken to send and receive messages and number of failed message sends and receipts. It allows runtime modification of the receive timeout.

Instrumented Spring JavaMailSender provides statistics on emails sent and allows you to configure the connection properties of the underlying mail server at runtime.

Instrumented Spring ThreadPoolTaskExecutor exposes thread pool utilization statistics and enables dynamic resizing of the pool and underlying queue at runtime.

Instrumented Spring MVC provides statistics for HTTP requests (via DispatcherServlet), view resolution, and view rendering, as well as Controller performance metrics. Most Spring MVC Controller implementations expose request statistics, and components annotated with @Controller will have execution time metrics exposed for each of their public methods. ViewResolvers and ViewRenderers provide throughput and failure data. DispatcherServlet exposes throughput of HTTP requests and also exposes the number of unhandled Exceptions, allowing you to track how often a stack trace is displayed to your application's end user.

Authentication metrics include the total number of successful and failed authentications, the number of "run as" operations, and the number of switched users. Instrumentation of the ExceptionTranslationFilter reveals the number of authentication entry point redirects and delegations to "Access Denied" handlers.

Instrumented Spring Security also provides visibility into user caches and the performance of user loading operations.

During authorization, the SecurityInterceptor gives performance details for authorization requests. Instrumented Spring Security also provides visibility into the ACL entry cache.

For each Flow Definition used in your application, Instrumented Spring Web Flow automatically tracks the average flow execution time, number of failed and successful flow executions, average flow execution start time, and more. The number of times a flow ended in each possible outcome is tracked as well, providing insight into how your application is used in production (for example, how many times users are starting a flow execution and then canceling before completion). Instrumented Spring Web Flow also monitors how often snapshots are taken during flow executions.

Instrumented Spring Web Flow provides application-level visibility into the Flow Definition Registry, allowing you to inspect its contents at runtime. Additionally, the Flow Execution Repository is instrumented for management and monitoring, exposing the maximum number of snapshots taken in a single flow execution and the maximum number of flow executions created in a single session across the entire application. Runtime controls allow you to adjust the maximum number of allowable snapshots and executions per session at runtime to scale your application in response to these metrics.

If enabled, Instrumented Spring Web Flow exports individual Flow Executions and Flow Execution Snapshots to JMX. This provides a deep level of insight into the behavior of your application to assist in troubleshooting and diagnosing performance or utilization issues. Individual flow executions and their snapshots are represented as JMX MBeans until the flow execution ends or its corresponding HTTP session expires.

Instrumented Spring Web Flow allows you to inspect the current state of the Flow Execution, the execution start times, and the number of snapshots taken during the execution. Each Flow Execution Snapshot MBean exposes the flow state and snapshot creation time and allows you to inspect the entire contents of Flow Scope at the time of the snapshot.

Note to SpringSource AMS users: SpringSource AMS ignores any FlowExecution and FlowExecutionSnapshot MBeans found in the MBeanServer during auto-discovery. These MBeans will not be imported into the AMS inventory model.

Instrumented Spring Web Services provides visibility into the MessageDispatcher as well as each registered endpoint to which messages are dispatched. The MessageDispatcher exposes dispatch throughput statistics. Each endpoint exposes execution time statistics, SOAP attachment size metrics, and SOAP fault information.

Instrumented Spring Web Services monitors most of its managed resources using a combination of compile-time woven aspects and hooks into existing Spring Web Services code. Instrumented Spring Web Services also uses Spring AOP proxies to monitor implementations of EndpointAdapter, the interface that must be implemented in order for each endpoint type to handle a message request. In most cases, Spring Web Services uses its own EndpointAdapter implementations, such as MessageEndpointAdapter or PayloadEndpointAdapter. Thus you should be able to monitor execution of any endpoint known to the MessageDispatcher with no additional configuration required. If you are using a custom EndpointAdapter, Instrumented Spring Web Services will attempt to create a Java dynamic proxy around your component. See Spring Framework Reference for more details about Spring AOP proxies. If the EndpointAdapter cannot be proxied, it is still exported as an MBean; however, its metrics are never updated.

Instrumented Spring Web Services provide information on request execution time per target URL when the URL is routed through the WebServiceTemplate. Each target URL is represented with its own JMX MBean containing request execution statistics. All JMX reserved characters such as ':' are stripped from the URL when the MBean ObjectName is created. The image below depicts a client application making a request to the Spring Travel sample application for hotel listings.

JConsole View of MBeans automatically exported by Web Services client application

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
	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:

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

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
	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
	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.

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

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.

If a WebApplicationContext is detected, the ServletContext is obtained from it. The discovered application name is then set to the value of ServletContext.getServletContextName(), if the servlet context name is set through the display-name attribute of the web.xml. If the context name is not set, the discovered application name is set to the value of ServletContext.getRealPath("/").

Note: WebLogic does not return a value from ServletContext.getRealPath(). If you are using WebLogic, set the display-name attribute in your application's web.xml file to a logical name for your application. This MUST be done in order for the auto-discovery component to export any managed resources.

Application discovery using ServletContext.getRealPath() has been tested on SpringSource tc Server 2.0, the previous version of tc Server, Apache Tomcat 6.0, WebSphere 6.1, and JBoss 4.2; it should work without issue. If you do not see managed resources being exported, set the display-name attribute and redeploy the application. To troubleshoot auto-discovery, see Verifying Auto-Discovery of Deployed Applications.

If any subclass of AbstractApplicationContext other than WebApplicationContext is detected, the application is assumed to be a standalone application. If you are running a standalone application, set the System property: "spring.managed.application.name=<application name>". If this property is not set, managed resources will not be exported.

Any bean that is created through an AbstractApplicationContext is discovered as a managed resource if the instrumented components know how to manage and monitor it. When managed resources are exported, they are named using bean names, so make sure that all beans you want to manage are consistently named. An instance of an anonymous bean could have a different name each time the application is restarted, which causes inconsistencies in data persisted by external management systems such as SpringSource AMS.

A managed resource that represents an ApplicationContext or BeanFactory is named using the display name of the ApplicationContext. This is set consistently by Spring within web applications. However, if you are creating your own ApplicationContext (such as a new ClasspathXmlApplicationContext), it is recommended that you set "refresh" to false, then set the display name on the ApplicationContext before calling "refresh", as follows:

ClassPathXmlApplicationContext applicationContext = new ClassPathXmlApplicationContext(new 
	String[] {"classpath:com/springsource/management/test-context.xml"},false);
applicationContext.setDisplayName("My Application's ApplicationContext");
applicationContext.refresh();

Taking this step ensures that your ApplicationContext and its BeanFactory are named the same each time the application is restarted.

Remote monitoring through JMX is automatically enabled in SpringSource tc Server. Consult the server documentation for additional information.

If you deploy your application in WebLogic 9.1+, Instrumented Spring Framework automatically exports all managed resources to the WebLogic MBeanServer obtained through a JNDI lookup of "java:comp/env/jmx/runtime". See Configuration Properties for options related to WebLogic MBeanServer discovery.

If you deploy your application in WebSphere 5.1+, Instrumented Spring Framework automatically exports all managed resources to the WebSphere MBeanServer obtained through WebSphere's proprietary AdminServiceFactory API. See Configuration Properties for options related to WebSphere MBeanServer discovery.

You need to configure Tomcat to create an MBeanServer and a JSR-160 connector. See http://tomcat.apache.org/tomcat-${product.version}-doc/monitoring.html for further information. The quick start method recommended by Tomcat is as follows:

Add the following properties to $CATALINA_HOME/bin/setenv.sh or setenv.bat:

						
CATALINA_OPTS="-Dcom.sun.management.jmxremote \
	-Dcom.sun.management.jmxremote.port=6969 \
	-Dcom.sun.management.jmxremote.ssl=false \
	-Dcom.sun.management.jmxremote.authenticate=false"
						

A full list of options for configuring JMX remote through these System properties can be found on Sun's website.

If deploying your application in JBoss 3.2+, Instrumented Spring Framework automatically exports all managed resources to the JBoss MBeanServer obtained through lookup of the local MBeanServer. The exported MBeans are also visible from the JBoss JMX Console.

For standalone applications (or possibly other containers not listed above), Instrumented Spring Framework simply exports managed resources to any local MBeanServer it finds. For remote access to this MBeanServer, create a JSR-160 connector. Spring JMX can be used to create a local MBeanServer and JSR-160 connector in your application. See Spring Framework Reference for further information on Spring JMX.

Additionally, you can use the JMX remote system properties. The following system properties create a local MBeanServer and remote connector:

						
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=6969
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false"
						

For a full list of options for configuring JMX remote through these System properties, see Sun's website.

Instrumented Spring Framework, Web Flow, Web Services, and Security use Commons Logging. All logger names begin with "com.springsource.management". Use the log file to verify that your application was discovered on deployment. If the logging level is set to "Info", you should see a message in your log when an application is discovered. For example:

						
INFO [com.springsource.management.agent.discovery.application.DefaultApplicationDiscoverer] - 
	Discovered application: Spring PetClinic
						
						

You can also see each managed resource that is discovered and exported. For example:

						
INFO [com.springsource.management.adapter.jmx.ManagedResourceExporter] - Registered MBean: 
	spring.application:application=Spring PetClinic,type=PlatformTransactionManager,
	name=transactionManager 
						
						

If your container supports it, you can use a tool such as JConsole to verify that Instrumented Spring Framework and Instrumented Spring Web Services, Security, or Web Flow have automatically discovered and exported your application resources. For example, the following is displayed in JConsole upon deploying the Spring Framework Pet Clinic sample application to Tomcat:

JConsole View of MBeans Automatically Exported by Instrumented Pet Clinic Application

You can also verify that your resources are being monitored by inspecting a metric that should be updated during application deployment, such as the Refresh-AverageExecutionTime(ms) metric depicted above.

The following source level metadata types are available for use in Spring JMX.

The following configuration parameters are available for use on these source-level metadata types. They are translated to ModelMBeanInfo fields by the MetadataMBeanInfoAssembler.

The following example uses annotations to automatically export JMX ModelMBeans:

package org.springframework.webflow.samples.booking.messaging;

import java.util.ArrayList;
import java.util.List;

import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.ObjectMessage;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.springframework.webflow.samples.booking.Booking;
import org.springframework.webflow.samples.booking.mail.BookingMailService;


@ManagedResource(objectName = "spring.application:application=swf-booking-mvc,
	type=MessageListener,name=bookingQueueMessageListener")
public class BookingQueueMessageListener implements MessageListener {

	private List messageQueue = new ArrayList();

	private long messageQueueSize=0;

	private boolean sendConfirmationEmail = false;
	
	@ManagedMetric(category="utilization", displayName="Message Queue Size", 
		description="The size of the Message Queue", 
		metricType = MetricType.COUNTER, unit="messages")
	public long getMessageQueueSize() {
		return messageQueueSize;
	}

	@ManagedAttribute(description="Send a confirmation email")
	public boolean isSendConfirmationEmail() {
		return sendConfirmationEmail;
	}
	
	@ManagedOperation
	public void resetMessageQueue() {
		this.messageQueue.clear();
	}

	@ManagedAttribute(description = "Send a confirmation email")
	public void setSendConfirmationEmail(boolean sendConfirmationEmail) {
		this.sendConfirmationEmail = sendConfirmationEmail;
	}
}