Knowledge Base

1. Download the Instrumented Spring Libraries
2. Download the Spring Pet Clinic Application
3. Build the Spring Pet Clinic WAR
4. Instrument the WAR File
5. Deploy the Instrumented WAR File
6. Verify Metric Availability
7. Generate Metrics
8. View Metrics

To instrument the Spring Pet Clinic sample application:

1. Download the Instrumented Spring Libraries
   
   Download a copy of the Instrumented Spring Libraries. For assistance downloading the libraries, see Downloading the Instrumented Spring Libraries (2001874).
   
   
2. Download the Spring Pet Clinic Application
   
   Get a copy of the source code for the Spring Pet Clinic application. This can be obtained from the SpringSource Subversion repository. To do so, make sure that Subversion is installed and then execute this command:
   
   svn co https://src.springframework.org/svn/spring-samples/petclinic/trunk petclinic-trunk
   
   
3. Build the Spring Pet Clinic WAR
   
   After you have the application source code, build the WAR:
   1. Open a terminal and navigate to the petclinic-trunk directory.
   2. Open the pom.xml file for editing.
   3. Edit the properties block, setting the spring.version property to match the version of the instrumented libraries that were downloaded (this example assumes 3.0.5.RELEASE).
   4. Save and close the file.
   5. Compile the standard Spring Pet Clinic example and create a WAR file, by running this command:
      
      mvn package

When that command finishes, you see this the message: BUILD SUCCESSFUL .
      
      Note: If any other message is displayed, it is likely that the build failed. Execute this command to perform a clean build:
      
      mvn clean package

If this command fails also, additional troubleshooting is required.
      
      When the build completes successfully, the WAR file is created in the target directory and named petclinic.war.
      
      
4. Instrument the WAR File
   
   

   Modify the WAR file from the previous step and augment it with Instrumented Spring libraries.

   Note: When running on Windows, VMware recommends using a tool that is capable of opening a ZIP archive, adding files to the existing archive, and deleting files from the existing archive.

   To modify and augment the WAR file:

   Note:Version numbers may differ, but the library names are consistent.

   1. Delete these libraries from the WAR file's WEB-INF/lib directory.
      
      
      • org.springframework.aop-3.0.5.RELEASE.jar
      • org.springframework.asm-3.0.5.RELEASE.jar
      • org.springframework.aspects-3.0.5.RELEASE.jar
      • org.springframework.beans-3.0.5.RELEASE.jar
      • org.springframework.context-3.0.5.RELEASE.jar
      • org.springframework.context.support-3.0.5.RELEASE.jar
      • org.springframework.core-3.0.5.RELEASE.jar
      • org.springframework.expression-3.0.5.RELEASE.jar
      • org.springframework.jdbc-3.0.5.RELEASE.jar
      • org.springframework.orm-3.0.5.RELEASE.jar
      • org.springframework.oxm-3.0.5.RELEASE.jar
      • org.springframework.transaction-3.0.5.RELEASE.jar
      • org.springframework.web-3.0.5.RELEASE.jar
      • org.springframework.web.servlet-3.0.5.RELEASE.jar
        
        
   2. Copy these libraries from the Instrumented Spring libraries download into the WAR file's WEB-INF/lib directory.
      
      
      • lib/com.springsource.org.apache.commons.logging-1.1.1.jar
      • lib/com.springsource.org.aspectj.runtime-1.6.8.RELEASE.jar
      • dist/com.springsource.management.adapter.jmx-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.bootstrap-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.config-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.control-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.discovery.application.web-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.discovery.domain-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.discovery.resource-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.inventory-3.0.5.RELEASE.jar
      • dist/com.springsource.management.agent.monitoring-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.applicationcontext-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.beans-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.context-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.context.support-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.jdbc-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.jms-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.orm.hibernate-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.transaction.manager-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.tx-3.0.5.RELEASE.jar
      • dist/com.springsource.management.instrumentation.springframework.webmvc-3.0.5.RELEASE.jar
      • dist/org.springframework.aop.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.asm.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.aspects.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.beans.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.context.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.context.support.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.core.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.expression.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.jdbc.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.orm.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.oxm.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.transaction.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.web.instrumented-3.0.5.RELEASE.jar
      • dist/org.springframework.web.servlet.instrumented-3.0.5.RELEASE.jar
        
        
   When those libraries have been deleted and copied, the WAR file has been instrumented.
   
   
5. Deploy the Instrumented WAR File
   
   

   Start the HQ Server, HQ Agent, and a tc Server instance (if one is not already running). Once the servers have been started, login to the HQ Server GUI and use the Application Management tab of the tc Server instance to deploy the WAR file.

6. Verify Metric Availability
   
   

   Once the WAR file has been successfully deployed, look at the tc Server instance's catalina.out file. It contains lines that look similar to this:
   
   011-03-31 14:09:06,309 INFO [com.springsource.management.adapter.jmx.ManagedResourceExporter] - <Registered MBean: spring.application:application=Spring PetClinic,type=View,name=owners/show.xml>
   
   These lines indicate that the instrumented libraries have been loaded and they are exporting metrics. If these lines are not present, recheck the WAR file and make sure that it is properly instrumented.
   
   You can also use the jconsole tool to verify that the metrics have been properly exported. To do this:

   1. Connect to the tc Server instance with jconsole.
   2. Click the Mbeans tab.
   3. Expand the spring.application element, in the bean list on the left, to show all of the exported metrics.
      
      
   If the metrics are not listed here, recheck the WAR file and make sure that it is properly instrumented. For more information about instrumenting WAR files, see the Spring documentation Instrumenting Applications.
   
   
7. Generatie Metrics
   
   Once you have verified that metrics are being properly exported by the application, access the deployed Pet Clinic application with a browser and navigate through it. This generates some data to monitor with Hyperic HQ.
   
   
8. View Metrics
   
   Go to the HQ Server GUI and navigate to the Inventory page for the tc Server instance. When the Inventory page refreshes, it shows the new metrics for the instrumented Pet Clinic application.
   
   This metric is available: Spring PetClinic Root WebApplicationContext.beanFactory Spring Bean Factory. For a complete list of metrics, see the Spring documentation Managed Beans.
   
   If the metrics are not listed on the Inventory page:
   1. Scroll down to the Configuration Properties section and click Edit.
   2. Without changing any settings, click OK. This forces the Agent to check for the metrics.
   3. Wait a few minutes while the Agent completes the discovery process, and then refresh the Inventory page.
      
      
   After the metrics are listed in the inventory, it is view the actual metrics gathered by the Agent by switching to the Monitor tab.

At this point, the Pet Clinic application is instrumented and deployed to the tc Server instance. In addition, Hyperic HQ is configured and monitoring the metrics exported from the application.