Knowledge Base

The VMware Knowledge Base provides support solutions, error messages and troubleshooting guides
 
Search the VMware Knowledge Base (KB)   View by Article ID
 

Instrumenting the Spring Pet Clinic example application (2001728)

Purpose

There are many examples for using the Spring Framework, but they do not showcase the Instrumented Spring libraries. This document explains how to convert the standard Spring Pet Clinic example application to an Instrumented Spring example application.

Resolution

There are several steps required to instrument the Spring Pet Clinic sample application:
  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.

Additional Information

For a more in-depth look at the topics covered in this article, see this Spring documentation:

Tags

instrumenting-application

See Also

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 3 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.
What can we do to improve this information? (4000 or fewer characters)
  • 3 Ratings
Actions
KB: