SpringSource AMS will scan all supported servers (SpringSource tc Server, SpringSource dm Server, Apache Tomcat, WebLogic, WebSphere, and JBoss) and standalone Java applications for ModelMBeans representing your custom application components. If these ModelMBeans contain specific descriptor values and match a specific ObjectName pattern, they will be added to the AMS inventory model as services. This allows you to manage and monitor any component of your application as you would any of the services automatically exported by the SpringSource Enterprise instrumented jar files.

Exporting your Components to JMX

SpringSource AMS will auto-discover your services and import their metadata using a set of expected ModelMBean fields and descriptor values. The manner in which you choose to create these ModelMBeans from within your application does not matter, however Spring Framework 3.0 and the SpringSource Enterprise Instrumented Spring Framework 2.5.6 distributions provide annotations that will automatically export MBeans in the proper format needed to enable discovery by SpringSource AMS. Please consult the documentation included with Spring Framework 3.0 or the SpringSource Enterprise Instrumented Spring Framework distribution to learn how to easily export your components to JMX using annotations.

ModelMBean Data Required By SpringSource AMS

AMS will translate ModelMBeanInfos into service metadata, ModelMBeanAttributeInfos into custom property or metric metadata, and ModelMBeanOperationInfos into control action metadata. The following is a complete list of ModelMBean fields that are used by AMS to auto-discover your MBeans and add them to the service inventory.

ModelMBeans
ModelMBean Field Description Type AMS Expected Format AMS Default Value
ModelMBean ObjectName Used by AMS to determine the type and name of the service to add to the inventory. ObjectName In order to be auto-discovered by AMS, ObjectNames must have the following format:
spring.application:type=%type%,name=%name%,*
The value of %type% is used to uniquely identify Service types in AMS. All MBean instances with the same value of the type key property must have the same metadata (same attributes, metrics, and operations). AMS will use the value of type to form the service type. For example the service type of an MBean with an ObjectName of spring.application:application=swf-booking-mvc,
type=MessageListener,name=bookingMessageListener will be "MessageListener". AMS will also use all key property values except type to form the service name, with the name key property generally reserved for last. The name format differs slightly per server type. For example, if deployed in Apache Tomcat, the above ObjectName would be translated to the service name "machineName Apache Tomcat 6.0 swf-booking-mvc bookingMessageListener MessageListener"
N/A
ModelMBeanInfo.
getDescription()
The friendly description of the service String Must not be null N/A
ModelMBeanInfo.
getMBeanDescriptor().
getField("typeName")
Overrides the Service type name (for example "Spring Bean Factory") used by AMS String Optional If not specified, AMS uses the value of the "type" ObjectName key property as specified above
ModelMBeanInfo.
getMBeanDescriptor().
getField("export")
Specifies whether or not AMS should consider this MBean for inclusion in the service inventory String Set to "true" or "false" "true"
ModelMBean Attributes

ModelMBeanAttributeInfos can be interpreted by AMS as either metrics or custom properties (depending on the presence of the "metricType" descriptor, see table below). Attributes representing custom properties must be of a JMX SimpleType or array of JMX SimpleTypes. Attributes representing metrics must be of a numeric JMX SimpleType.

ModelMBean Field Description Type AMS Expected Format AMS Default Value
ModelMBeanAttributeInfo.
getDescription()
The friendly description of the Custom Property or Metric String Must not be null. ModelMBean Attributes that are represented as Custom Properties in the AMS dashboard are displayed by their descriptions instead of their names. Therefore, it is best to set the description to something human-readable. N/A
ModelMBeanAttributeInfo.
getDescriptor().
getField("metricCategory")
Sets the category of a Metric String Must be either PERFORMANCE, UTILIZATION, or THROUGHPUT. Performance metrics typically represent some time-related aspect of the system. For example, average elapsed time per method call. Utilization metrics typically represent usage of some resource. For example, memory usage, cache size, thread pool size. Throughput metrics typically represent the amount of work done over a period of time. For example, transactions per second. UTILIZATION
ModelMBeanAttributeInfo.
getDescriptor().
getField("displayName")
Sets the name of the metric in the AMS System String This value is used to uniquely identify the metric per service type. Defaults to the name of the ModelMBean attribute
ModelMBeanAttributeInfo.
getDescriptor().
getField("indicator")
Indicates that this metric provides relevant insight into the state of the system and should be considered a possible indicator of a system issue String If set to "true", the metric will be displayed in chart form on the Indicators tab in the AMS dashboard. NOTE: If set to "false" metric values will NOT be collected by default. "true"
ModelMBeanAttributeInfo.
getDescriptor().
getField("metricType")
A description of how the metric's values change over time. The presence of this field indicates to AMS that this MBeanAttribute should be considered a metric. If not set, the attribute will be considered a custom property. String As described by the JMX specification, must be set to either "counter" or "gauge". "A metric that is a counter has a value that never decreases except by being reset to a starting value. Counter metrics are almost always non-negative integers. An example might be the number of requests received. A metric that is a gauge has a numeric value that can increase or decrease. Examples might be the number of open connections or a cache hit rate or a temperature reading". AMS uses this value to set the default collection interval of the metric as well. If set to "counter", values will be collected every 10 minutes. If set to "gauge", values will be collected every 5 minutes "gauge"
ModelMBeanAttributeInfo.
getDescriptor().
getField("units")
The unit in which an attribute is measured, for example "B" or "ms". String As described by the JMX specification. AMS will accept the following units:
B: Bytes
KB: Kilobytes
MB: Megabytes
GB: Gigabytes
TB: Terabytes
epoch-millis: Time since January 1, 1970 in milliseconds.
epoch-seconds: Time since January 1, 1970 in seconds.
ns: Nanoseconds
mu: Microseconds
ms: Milliseconds
jiffys: Jiffies (1/100 sec)
s: Seconds
cents: Cents (1/100 of 1 US Dollar)
none
Defaults to "none" if not specified or if set to an unrecognized unit.
ModelMBean Operations

AMS expects ModelMBean Operation return values and parameters to be of JMX SimpleType or arrays of JMX SimpleTypes.

ModelMBean Field Description Type AMS Expected Format AMS Default Value
ModelMBeanOperationInfo.
getDescription()
The friendly description of the Operation String Must not be null. N/A

Example: Adding a Custom Component to AMS

The following example uses SpringSource Enterprise Instrumented Spring Framework 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="none")
	    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;
	    }
	}
	

Upon discovery of the MBean specified above, AMS will automatically create a service type of "Message Listener" representing all services in the spring.application domain whose ObjectName has a type key property value of "MessageListener". This service type will be configurable under the specific server type you are deploying to in Administration->Monitoring Defaults on the AMS dashboard (for example, "Apache Tomcat 6.0 Message Listener"). If the metadata associated with this type changes (for example, if you add another @ManagedAttribute to the BookingQueueMessageListener), the type will be updated in AMS and any existing service instances will be deleted and redeployed.

NOTE: Currently, a service type cannot be deleted from AMS. Once you have deployed any MBeans auto-discovered by AMS, those types will be visible and configurable through Administration->Monitoring Defaults. A future AMS version will give you the ability to remove these types when they are no longer in use.

Instances of this service type will then be auto-discovered along with any other services deployed in your container or standalone application. The image below demonstrates the name assigned to the service as well as the display of the Message Queue Size metric.

The image below demonstrates the ResetMessageQueue operation available as a Control Action.

The image below demonstrates the display of the sendConfirmationEmail attribute value (at the top of the screen) and the SetSendConfirmationEmail operation available as a Control Action to set the attribute value.