spring insight developer - vmware documentation

Spring Insight Developer

Spring Insight Developer 1.8

VMware vFabric tc Server 2.7 and 2.8

This document supports the version of each product listed andsupports all subsequent versions until the document is replaced bya new edition. To check for more recent editions of this document,

see http://www.vmware.com/support/pubs.

EN-000904-00

http://www.vmware.com/support/pubs

You can find the most up-to-date technical documentation on the VMware Web site at: https://www.vmware.com/support.

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to: [email protected]

Copyright © 2013 VMware, Inc. All rights reserved. This product is protected by copyright and intellectual propertylaws in the United States and other countries as well as by international treaties. VMware products are covered byone or more patents listed at http://www.vmware.com/go/patents.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and other jurisdictions. Allother marks and names mentioned herein may be trademarks of their respective companies.

VMware, Inc., 3401 Hillview Avenue, Palo Alto, CA 94304

www.vmware.com

http://www.vmware.com/support/

http://www.vmware.com/support/

http://www.vmware.com/go/patents

VMware vFabric tc Server 2.7 and 2.8 iii

Table of Contents1. About Spring Insight Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12. What Is Spring Insight Developer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

What You Can Do with Spring Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3How Spring Insight Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Supported Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3. Install and Configure Insight Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Install Insight Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Configure Spring Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Increasing Memory when Using Spring Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4. Using Spring Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Invoke Spring Insight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Browse Applications and End Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Viewing Recent Activity of Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Filtering Trace Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Exporting and Importing Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Customizing End Point Thresholds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Viewing Spring Insight Data In Google Speed Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Using Annotations To Customize Spring Insight Data For Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

5. Overview of Spring Insight Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Prerequisites for Installing the Spring Insight Developer Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Installing the Spring Insight Developer Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

6. Using the Spring Insight Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Relationships Among Spring Insight Objects and Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Building and Deploying the Sample Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Using the Sample Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Building a Plug-in from the Source Code .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

7. Tutorial: Creating an Insight Plug-in with the Insight Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478. Contributing Plugins to Insight Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619. Core Plug-in Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

annotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63apache-http-client3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63apache-http-client4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63blazeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63ehcache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64ejb3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64files-tracker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64gemfire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64grails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65hibernate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65javax-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65jax-rs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65jdbc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66jms .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66jws . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67method-endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67mongodb .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67quartz-scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67rabbitmq-client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68redis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

iv Spring Insight Developer

servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69spring-core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69spring-integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69spring-security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69spring-tx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70spring-web .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Server-Based Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

About Spring Insight Developer 1

VMware vFabric tc Server 2.7 and 2.8 1

1. About Spring Insight DeveloperRevised October 16, 2012

Spring Insight Developer describes Spring Insight concepts and provides instructions for configuring and using Spring InsightDeveloper with VMware® vFabric™ tc Server. Spring Insight Developer provides in-depth tracing and performance monitoringfor Web applications during the development and QA phases.

Intended Audience

Spring Insight Developer is intended for anyone who wants to install, configure, and use Spring Insight Developer in a Webapplication development and testing environment.

2 Spring Insight Developer

2 About Spring Insight Developer

What Is Spring Insight Developer? 3


2. What Is Spring Insight Developer?Spring Insight Developer answers the question "What just happened?" It is a VMware® Web application that gives you real-timevisibility into application behavior and performance.

In development and testing stages, developers can use Spring Insight Developer to verify immediately whether their newly-written code is behaving as designed. QA engineers can pinpoint specific causes for "what just happened" and relay detailedinformation to developers.

Stress testing an application typically tells you which URL areas are slow. By combining Spring Insight Developer with yourexisting tools (such as JMeter), you can see not only which URLs are slow, but why, thus accelerating your time to production.

The following sections provide an overview of Spring Insight:

• What You Can Do with Spring Insight

• How Spring Insight Works

• Supported Environments

What You Can Do with Spring Insight

The following topics discuss specific use cases:

• Agile Development

• QA Rear View Mirror

• Load and Performance Testing

• Extended Customization with the Spring Insight Developer Kit

• Browser Performance Data from Integration with Google SpeedTracer

Agile Development

Web application developers realize a massive increase in productivity when they can make changes and see the effectimmediately. Typically, a developer makes changes to HTML or JSP and reloads the browser to verify that the modifiedapplication renders the web page as desired. However, developers often lack a centralized tool that shows how their changesaffect:

• JDBC queries

• Spring bean interaction

• Calls to external services

Large, popular frameworks such as Hibernate and Spring Web push much of the code that developers formerly wrote manuallyinto a convenient library. This process saves time and improves maintainability. The downside is relinquishing control, whichmeans that the developer may not know exactly what is going on behind the scenes:

• How many database transactions did a web request create?

• How expensive is it to use complex web parameter binding?

• What are the HTTP headers being sent to the developer's REST application?

The Spring Insight Trace view solves these problems. It allows developers to make changes and verify their effectivenessimmediately.


4 What Is Spring Insight Developer?

QA Rear View Mirror

Spring Insight gives QA a richer picture of an application's performance, eliminating much of the work required to diagnoseproblems. As QA tests an application, typical problems include:

• Slow-loading pages

• Database grinding

• Stack traces

As these problems arise, QA engineers can browse to the Spring Insight dashboard, review all recent operations, and access in-depth information that helps them track down bugs. The dashboard provides information such as:

• A list of all database queries and their performance

• A detailed description of the web request, its parameters, and headers

• A list of component method calls and their parameters

• A list of all Spring components that were used and their performance

QA forwards this information to the developer, thus improving the turnaround time for identifying and resolving root causes.

Load and Performance Testing

Web applications must be loaded and stressed before being deployed in a production setting. Spring Insight works with yourexisting load-testing tools to answer two main questions:

• What was slow?

• Why was it slow?

After running a load test, Spring Insight displays a breakdown of all requests to Spring Web. It shows you:

• The response time trend over a designated period

• A histogram that identifies response time patterns and outliers

• Detailed statistics, such as 95th percentile response time

Using this information, you can drill down to specific information about why a request was slow:

• Did the request execute an extremely slow database query?

• Did it make a call to a remote system that locked up?

• Did it spend a long time rendering the result?

The request trace information that you access in the Trace view is also available when you analyze a performance test.

Extended Customization with the Spring Insight Developer Kit

Spring Insight uses a plug-in architecture to collect, correlate, and analyze performance metrics from your application and fromdifferent pieces of third-party software and libraries that interact with the application. You can create plug-ins that are tailoredto the needs of your application with the Spring Insight Developer Kit. Using the Developer Kit, you can extend Spring Insightfunctionality to collect trace details such as Hibernate flush times and JSP render times; render custom HTML for an operationdetail frame; and analyze traces to produce new types of End Points, such as a JMS message queue.

The Developer Kit is a separate download. It includes a copy of the source code for all plug-ins shipped with Spring Insight and asample plug-in that serves as a starting point for creating your own plug-ins. See:

What Is Spring Insight Developer? 5


• Overview of Spring Insight Development

• Using the Spring Insight Plug-ins

• Tutorial: Creating a Spring Insight Plug-in with the Spring Insight Developer Kit

• Core Plug-in Reference

Browser Performance Data from Integration with Google SpeedTracer

SpeedTracer is a Google Chrome extension that analyzes how your application is performing inside the browser. It measures howlong the browser takes to render, transform CSS, show images, and so on. VMware and Google partnered to integrate SpringInsight data into SpeedTracer, thereby tying browser performance to backend performance with a robust client-server applicationperformance tool. If your web application uses Ajax and other rich open web technologies, we recommend you try SpeedTracerwith Spring Insight.

For details, see Viewing Spring Insight Data in Google Speed Tracer.

How Spring Insight Works

Spring Insight captures application events known as traces. A trace represents a thread of execution. It is usually started by anHTTP request but can also be started by a background job. A trace contains operations. Each operation represents a significantpoint in the execution of the trace, for example, a JDBC query or transaction commit.

Using this data, Spring Insight calculates summary information to lead you to the specifics of why your application may not beperforming as well as it could.

Spring Insight uses AspectJ to intercept operations in target web applications. Target web applications are loaded with a specialclassloader that dynamically instruments web applications at runtime. Spring Insight uses sophisticated algorithms to keep thememory footprint low. However, Spring Insight-enabled servers require more memory (-Xmx) than a standard server.

Spring Insight Developer and applications run together on a single tc Server runtime instance. Spring Insight's lean frameworkkeeps developer requirements to a minimum. Developers can deploy a native application to a Spring Insight Developer-enabledtc Runtime instance and immediately see diagnostics. There is no database to set up, no instrumentation to perform.

Supported Environments

Spring Insight runs in environments with a Java 6 JVM. (Insight 1.8 does not support Java 1.7. Support for the new bytecodegenerated in 1.7 is under development.) Supported versions are: tcServer Standard Edition 2.1, 2.5, 2.6 and 2.7.

Spring Insight supports the same configurations as tc Runtime. See vFabric tc Server Release Notes for the complete list.

http://code.google.com/webtoolkit/speedtracer/get-started.html

http://www.vmware.com/support/pubs/vfabric-tcserver.html


6 What Is Spring Insight Developer?

Install and Configure Insight Developer 7


3. Install and Configure Insight Developer

This section has instructions for installing and configuring Insight Developer, and documents the inisght.properties file.

• Install Insight Developer

• Configure Spring Insight

Install Insight Developer

To install Spring Insight Developer, you install the vFabric tc Server Developer edition and then create a new tc Runtimeinstance using the insight template.

These instructions assume that you have downloaded tc Server Developer edition from the VMware Download Center, but notyet installed it.

1. Create a directory for tc Server, for example:

/home/tcserver

2. Unpack the tc Server archive into the directory created in the previous step, such that the tc Server home directory is a sub-directory of it, for example:

/home/tcserver/vfabric-tc-developer-2.7.X.X

3. Create a tc Server instance where Insight will run:

a. In a terminal window, change to the tc Server home directory.

b. Create a tc Server instance with tcruntime-instance.sh or tcruntime-instance.bat, using theinsight template.

For example, to create an instance named "Insight", enter the following command:

./tcruntime-instance.sh create Insight -t insight

4. Start the new tc Server instance using the tcruntime-ctl.sh or tcruntime-ctl.bat command.

• On Unix, to start an instance named "Insight":

./tcruntime-ctl.sh Insight start

• On Windows, install a Windows service for the instance before you start it the first time (After than, you can control theservice from the Windows services control panel.) To install an instance named "Insight" as a Windows service, and thenstart it :

a. tcruntime-ctl.bat Insight install

b. tcruntime-ctl.bat Insight start

5. Deploy your Web applications to tc Server. Copy the WAR files to the webapps directory of the tc runtime instance. Ifnecessary, update conf/server.xml and conf/context.xml files to support the deployed application.

6. Access the Spring Insight Dashboard by opening http://localhost:8080/insight in your browser.

See the tc Server documentation for more detailed information about installing and configuring tc Server.

http://www.vmware.com/go/download-tcserver

http://www.vmware.com/products/vfabric-tcserver


8 Install and Configure Insight Developer

Configure Spring Insight

You configure Spring Insight by editing the insight.properties file, located in the insight directory of the tc Runtimeinstance. For example, the properties file for an instance called insight-instance is tc-server/vfabric-tc-server-developer-x.y/insight-instance/insight/insight.properties.

The properties file lists supported properties in property: value form. Comment lines begin with #.

The following table defines the properties you can set in insight.properties.

Table 3.1. Properties of the insight.properties File

Property and Default Setting Description

application.context.ignore.identifier (Optional) You can use this property to specify application contexts that you want SpringInsight to ignore, and not instrument. (Instrumentation can increase the time it takes anapplication to start. )

The default value (shown below) excludes the Insight Agent from being instrumented.

The format for this property isapplication.context.ignore.identifier:hostName|contextName

where:

• identifier—is a value that makes the property name unique in the properties file;Insight does not use the value. Specify any identifier that is meaningful to you.

• hostName—identifies the application host.

• contextName—is the URL context that invokes the application. This is generally isthe name of the WAR file in which the application is packaged, unless it is otherwisespecified in the application's web.xml file.

The following example ignores the Tomcat Manager application, which has theapplication context manager.

application.context.ignore.mgr: localhost|manager

Default:

application.context.ignore.agent: localhost|insight-agent

database.driverClassName Specifies the class name of the JDBC Driver that Spring Insight uses to connect to thedatabase.

Default:

org.h2.Driver

database.password Specifies the password of the user that connects to the database that Spring Insightuses to persist its data.

Default:

admin

database.url Specifies the URL of the database that Spring Insight uses to persist its data.

Note: Spring Insight bundles the H2 Java SQL database and uses it internally to persistits data. By default, a tc Runtime instance configured with Spring Insight is configured touse the H2 database.

Default:

jdbc\:h2\:\#{insightConfig.dataDir}/dashboard/dashboard;DB_CLOSE_DELAY\=-1;MVCC\=TRUE

database.username Specifies the name of the user that connects to the database that Spring Insight uses topersist its data.

Default:

Install and Configure Insight Developer 9



insight

insight.data.dir Specifies the full pathname of the directory in which Spring Insight persists its data.

Default:INSTANCE_DIR/insight/data.

insight.purge.interval.min Specifies, in minutes, how frequently Spring Insight purges traces and resources fromthe database.

Default:

30

metric.max.granularity.sec Specifies, in seconds, the maximum granularity at which Spring Insight aggregatesmetrics. Spring Insight collects metrics every 15 seconds, and aggregates metric valuesat various granuarities from minute up to the default value of one year.

Default:

31,536,000 (one year)

trace.exclude.path.type This property configures Spring Insight to not save traces for application requestswhose performance you do not wish to track, such as requests for static content. Youspecify the requests to ignore by specifying a pattern (in ant path format) against whichrequests are matched. Insight does not save traces that match a path specified bytrace.exclude.path.

Specify each path you wish excluded separately, as shown in the example below. Thisexcerpt from the default insight.properties file excludes traces for requests forcontent of the following types: .png, .gif, .jpg, .css., and .js:

Default:

trace.exclude.path.png: /**/*.pngtrace.exclude.path.gif: /**/*.giftrace.exclude.path.jpg: /**/*.jpgtrace.exclude.path.css: /**/*.csstrace.exclude.path.js: /**/*.js

trace.purge.batch Specifies how many traces Spring Insight purges each time it periodically purges tracesfrom the database.

Default:

500

trace.max.memory.mb The maximum amount of memory, in MB, that is available for trace storage. When thisthreshold is reached, traces are randomly removed, with older traces removed first.

Default:

40

trace.purge.expiry.days Specifies how many days Spring Insight saves traces before purging them from thedatabase.

Default:

7

resource.purge.batch Specifies how many resources Spring Insight purges each time it periodically purgesresources from the database. Note that, regardless of the value of this property, SpringInsight only purges resources that are not referenced by any traces.

Default:


10 Install and Configure Insight Developer


40

Increasing Memory when Using Spring Insight

When you monitor an application with Spring Insight, you need to take into account the memory requirements of Insight itself. Itmay be necessary to increase the memory available to tc Runtime to ensure enough memory is available for both the monitoredapplication and Spring Insight. VMware reacommends 256MB permgen for an application, depending on the complexity. Withthe the Sun JVM, you increase the size of the Permanent Generation using the -XX-MaxPermSize JVM option.

To increase the memory used by tc Runtime, edit the CATALINA_BASE/bin/setenv.sh|bat file, whereCATALINA_BASE refers to the root directory of your instance, such as /home/tcserver/vfabric-tc-server-developer-2.7.X.X/insight-instance. The comments in the file itself show examples of setting the JVM options.

Using Spring Insight 11


4. Using Spring InsightSpring Insight Developer enables you to see what your application is doing under the hood of @annotated APIs orproxied objects. Popular frameworks of today hide tremendous power behind friendly facades. For example, a simplesession.save(book) that uses Hibernate can execute hundreds of JDBC calls, depending on your mapping. Spring Insightbrings these low-level performance-oriented operations to the screen for quick evaluation.

The following procedures describe basic tasks that help you start using Spring Insight with your own Web application:

• Invoking Spring Insight in your Browser

• Browsing all Applications and End Points

• Viewing Recent Activity of Your Application

• Filtering Trace Details

• Importing and Exporting Traces

• Customizing End Point Thresholds

• Viewing Spring Insight Data In Google Speed Tracer

• Using Annotations To Customize Spring Insight Data For Your Application

Before You Begin

Before you start using Spring Insight:

• Install tc Server Developer Edition and create a tc Runtime instance using the Spring Insight template. See Installing andConfiguring Spring Insight.

• Start the tc Runtime instance, deploy your Web application to the instance, configure all of its resources (such as any requiredJDBC data sources), and make sure your application is running and ready to be used.

To deploy a Web application to a tc Runtime instance, copy its WAR file or exploded directory to the deployment directory,which by default is CATALINA_BASE/webapps where CATALINA_BASE is the root directory of the tc Runtime instance.

For example, assume that you created an instance called insight-instance using the provided insight template andthat you have already started the instance. Further assume that the CATALINA_BASE of this instance is /home/tcserver/vfabric-tc-server-developer/insight-instance and that the full pathname of your Web application is /home/apps/myApp.WAR. To deploy this application to the tc Runtime instance, execute the following command:

prompt$ cp /home/apps/myApp.WAR /home/tcserver/vfabric-tc-server-developer/insight-instance/webapps

For complete documentation about tc Server, see vFabric tc Server Documentation.

Invoke Spring Insight

Follow these steps to invoke Spring Insight in your browser and to start seeing trace data.

1. Browse to the Spring Insight dashboard at the following URL:

http://localhost:8080/insight

Note: In Spring Insight Developer, you can access the Spring Insight dashboard only from the localhost.

The browser invokes the main Spring Insight dashboard on the Browse Resources screen:

http://www.vmware.com/support/pubs/vfabric-tcserver.html


12 Using Spring Insight

2. Initiate activity by using your Web application; the exact steps depend on what your application actually does.

Spring Insight traces all application activity and displays it on the dashboard. For example, if you performed any JDBCqueries, each one is shown in the Spring Insight dashboard along with a timeline of recent requests.

Browse Applications and End Points

The following procedure describes how to browse the applications deployed to the tc Runtime instance and their End Points, andview health, throughput trends, response time trends, and response time histograms.

The Browse Resources screen shows information for all types of applications, but provides more detail for Spring, Grails, andRoo applications.

1. From the main Spring Insight dashboard, click the Browse Resources link:



The Applications panel on the left displays a tree control of all applications that have reported Traces; you can expand eachapplication to see its list of End Points. The health of the application is displayed next to its name and represents the worst-performing End Point within the Application. Each End Point also displays its health, which is described later on in thisprocedure.

Spring Insight loads the resource tree when it loads the page. If you subsequently deploy a new application or Spring Insightdetects new End Points, it automatically adds these resources into the resource tree.

The Applications Health Trend panel on the right shows a graph of the recent health of all applications. The health of eachapplication is graphed in a different color so you can differentiate them. The table in the lower panel presents the followinginformation for each application:

• Health Trend — Sparkline that graphically describes the recent health of the application.

• Throughput — How many Traces per Minute (tpm) were executed over the current time window.

• Errors —Percentage of Traces that resulted in an Error (HTTP status 500 to 600).

The graphical or tabular view of all applications is useful to see which applications have been busiest and to compare theirrelative health. Click in the graphs to see the application-specific information. Click the column headers in the table to sortthe information based on the column.

2. Click on an application in the left Applications panel. The right panel displays similar information about the applicationas in the previous table, but this time the graph contains information only about the specific application and its End Points.The End Points panel displays the End Points associated with the application; the same list appears below the name of theapplication in the left Applications panel.



The Vitals section shows a summary of the health of the application.

Each row in the End Points table represents an End Point, which is a receptor for requests. The universe of all possibleHTTP URLs is unlimited. However, Spring Insight can group requests together based on the controllers with which therequests are associated. For each End Point, Spring Insight displays the following information:

• Health—Shows how well the response time metric is kept within a tolerable threshold, where red is less healthy andgreen is more healthy. See Customizing End Point Thresholds for help setting the tolerable threshold.

• End Point— The name of the End Point.

• Health Trend— Simple sparkline that shows the recent health of the End Point.

• Throughput—Number of Traces per Minute (tpm) executed over the current time window.



• Errors— Percentage of Traces resulted in an Error (HTTP status 500 to 600).

• Response Time—The 95% response time over the given time range. This value is useful to determine the worst-caserequest. A value of 115ms indicates that 95% of the requests completed within 115 milliseconds. The response time of anHTTP request is the full time the container takes to send the response to the client, not just the time spent in a controller.

3. Click on a particular End Point, either in the left Applications panel or in the right End Points table:



Spring Insight displays the following detailed information about the End Point:

• The End Point chart shows the

• throughput trend—the recent mean throughput time of the End Point over the time range

• response time trend— the mean response time of the End Point over the time range

• error rate—percentage of traces that resulted in an error. Hover over any spot in the chart to view details for the timeslice represented by that section of the chart. Click on a data point to see trace data that occurred during that time range.

• The Vitals section displays the mean throughput, total number of Invocations, and errors for all of the traces in the timerange represented on the current chart.

• The Response Time section displays statistics about the response times for all of the traces represented on the currentchart. The 95th Percentile statistic indicates that 95 percent of requests completed within the indicated time period. TheMean is the average response time. The Standard Deviation is a measure of the variability of response times. A largerstandard deviation indicates a greater variability in response times.

• The Response Time Histogram is an interactive graph that shows how many invocations occurred within a given timeperiod. The Y-axis represents the response time of an invocation. The X-axis represents the number of invocations. Usingthe histogram is an easy way to identify outliers in your data. The longest-running invocations are always at the top of thehistogram. If extreme outliers exist, they are indicated by red bars.

• The Health of the End Point is determined by the Response Time for requests made over the given time interval. Theresponse times are broken down into various Health Zones (such as frustrated, tolerated or satisfied. Click on a particularHealth Zone to see representative Traces within that zone.

4. Click a bar in the histogram or on one of the markers in the Throughput or Response Time Trend graphs. A RepresentativeTraces panel shows representative traces for some invocations that occurred during the selected duration.



The Representative Traces panel includes similar data as that of the Recent Activity screen. From here it is easy to drillinto the shortest or fastest running traces to see what made them different. See Viewing Recent Activity of Your Applicationfor detailed information about traces and trace details.

Viewing Recent Activity of Your Application

The following procedure describes how to get an overview of the recent activity of a particular application, or for all applicationscurrently deployed, and then how to drill down to the details of a particular application event.

1. From the main Spring Insight dashboard, click the Recent Activity tab:

The Recent Activity screen displays traces from your application. A trace is a breakdown of the activity of a request. TheRecent Activity screen answers the question What just happened?

2. In the top-right Application Selector drop-down box, select the name of your application.

Use the Application Selector to view activity for all applications or for just a single one. Viewing all applications at onceis useful when you deploy many Web applications and are interested in activity across the entire set. Viewing a singleapplication filters out activity not related to that application.

The Trace History panel shows a timeline of the recent activity of your application as real-time requests, represented bybars in the chart. Each bar represents all requests that occurred within a time slice, as measured by the chart. The full timerange has 60 time slices. The height of the bar is equal to the longest request that occurred during that window.

The Trace History graph shows activity that Spring Insight has monitored over the past N minutes. When Spring Insightcaptures a trace, it draws a new bar on the graph on the right-hand side. As time passes, bars move left until they fall out ofthe time range.

Click on bars to drill deeper.

3. Click on a bar in the Trace History chart.



Spring Insight displays a list of traces in the Traces panel that executed during the window of time (or time slice), and thendetails about a specific trace. Spring Insight automatically shows details about the first trace in the Trace Details panel. Ifyou click on a different trace, Spring Insight refreshes the details panel with corresponding information.

The Spring Insight dashboard shows the Traces and Trace Detail panels.



You can sort the traces in the Traces panel by Duration (how long did the trace take?), Label, Start (when did the tracestart?), End Point (what was the request?), or Error (did the request result in an error?)



4. Click on a trace in the Traces panel to view its details in the Trace Detail panel.



The Trace Detail panel contains a breakdown of a trace's activity in a tree format. A trace consists of a top-level operation,usually a Web request, and all nested operations.

Spring Insight uses "smart collapse" to determine how to collapse the tree of trace details so that you do not get pages andpages of trace information. You can, of course, uncollapse operations to drill down into their details.

Operations are the fundamental building blocks of traces. An operation can represent a Web request, a transaction, a call toan MVC controller, a file opening, a service request, and so on. Each operation may have other operations nested within it.The nesting structure shows the normal stack-based method invocation pattern.

The operation timing graph shows two pieces of information:

• When the operation executed in relation to the other operations. This information shows whether the operation executedtowards the end of the request or the beginning by the location of the green bar in relation to its borders.

• How long the operation took to execute, indicated by the width of the green bar. Because operations can be nestedwithin operations, the green bar shows only how long the particular operation took, not the sum of duration of the nestedoperations. This way you can scan all the nested operations and find the particular one that took the longest time, based onthe width of its green bar.

Click on an operation's label, or the entire row, to drill further into the operation details. The details of this panel are specificto each type of operation, and contain the finest granularity of collected data.

Click on Filter to filter the trace details shown in the panel. See Filtering Trace Details for additional details about thisfeature.

Click on Related To to navigate to the Trace's corresponding End Point or application in the Browse Resources tab. Thisbutton is useful when you want to see how similar requests (requests to the same End Point or application) have performedover time.

5. The buttons above the Application Selector help you control the information you see in the Spring Insight dashboard andperform additional administrative tasks:

• Change the global time range using the first drop-down list. The time range specifies how many minutes worth of datashows up in the Trace History graph.



• Play or pause the graph movement by specifying now or pause in the first drop-down list. If the graph is in Play mode,the word Live appears under the right hand side of the graph. If you have paused the graph movement, the time whenyou clicked the pause button appears instead.

• Click the << or >> buttons to rewind or fast-forward, based on the specified time ranges. Spring Insight persists all traceinformation about all your applications to disk, which means you can rewind and look at trace information from when youfirst began to track the performance of your application.

• In the right-most drop-down list, choose Refresh to refresh the trace history by reloading all data within the TraceHistory graph.

Filtering Trace Details

Depending on the nature of a specific trace, the list of operations in the corresponding Trace Detail pane might be very long.Spring Insight uses smart collapse, which means it collapses those operations it thinks are unimportant but uncollapses operationsthat are most likely interesting to you. However, the Trace Details pane could still be very large. In this case, you might want tofilter the list of operations to display only certain types that interest you.

The list of available filters depends on the plug-ins currently installed in Spring Insight as well as the type of operations in thecurrent list of trace details. Spring Insight has a number of plug-ins installed by default. Click the Administration tab on themain dashboard then Collection Plug-Ins to see the list. If you have previously added your own custom plug-in to Spring Insightso as to display custom trace details, then this filter might also be available.

The default list of filters is as follows:

• Database: Filters operations based on whether they are related to general database calls. This could include transactions aswell as standard calls to a relational database, for example.

• JDBC: Filters operations based on whether they are JDBC calls. The results of this filter are a subset of the results of theDatabase filter.

• Servlet: Filters operations based on whether they are Servlet operations, including operations such as authentication, sessionmanagement, and handling requests and responses.

• Web: Filters operations based on whether they are related to Web calls, such as HTTP requests and responses, rendering ofHTML pages, and so on. The results of this filter are a subset of the results of the Servlet filter.

Filters are tri-state—you can set each filter to one of three different states:

• Unselected – operations are included in the results unless one or more other filters are set to + (plus)

• + (plus sign) – only these operations are included in the results

• - (minus sign) - only these operations are excluded from the results

Filters are sticky, which means that they stay in place even when you navigate away from the page in which you set the filter.This is useful if you want to look at multiple applications or End Points, searching for JDBC calls, because you do not have toreset the filter each time you look at a different trace. You can remove the filter at any time, as described in the procedure below.

To use filters, follow these steps:

1. Display the Trace Details pane for a particular trace you are interested in. See Viewing Recent Activity of YourApplication.

2. In the top-right corner of the Trace Details pane, click the Filter drop-down list and select the filters you want to apply.You can select multiple filters; the results are a sum of the individual filter results. Set the filter to + (plus) to include onlythose operations, - (minus) to exclude the operations, or leave the box unselected. If you do not set a filter to + or -, theoperations are included unless another filter is set to +.



3. Click to the left of the Filter drop-down list to actually apply the filter. A message appears below the Trace Detail label toalert that a filter is being applied.

After applying the filter, the trace details navigation tree is smaller, and only details included meet the specified filterconditions.

Because of the stickiness of the filter, as you navigate away from your current page you'll notice that Spring Insightcontinues to apply the filter.

4. To remove the filter, click on the X to the left of the Filter applied to trace alert.

Exporting and Importing Traces

With this feature, you can export a trace to a file and then import it into either the same or different instance of Spring Insight.This feature is useful if the Spring Insight user who captured the trace in real time wants to look at it at a later time, or hand it offto another person.

For example, assume that a QA engineer is testing their company's Web application and runs into an error, or an operation takesan excessive time to complete. The QA engineer uses Spring Insight to take a look at what just happened by navigating to therelevant trace and viewing its details. If the QA engineer decides to open a bug about the problem, they can export the trace to afile and then attach this file to the bug issue so that the developer can take a look at a later date. The developer does not need toactually deploy the application; rather, they can look at the trace details to figure out which operation caused the error, where theexcessive time occurred, and so on. This is an easy way to capture a complete set of trace information about an error event, evenif the event is not reliably reproduceable.

You can only import traces that were previously exported from a Spring Insight instance.

To export a trace:

1. Display the Trace Details pane for the particular trace you want to export. See Viewing Recent Activity of YourApplication.

2. From the right-most drop-down list in the Trace Details pane , select Export Trace:



3. Save the exported trace to a file. The name of the file will be of the form trace-identifier.insight.

To import a trace:

1. From the main Spring Insight dashboard, click the Administration tab.

2. In the left pane, click Import Trace.

3. In the right pane, use the browse button to browse the trace you want to import; the name of the file will be of the formtrace-identifier.insight.

4. Click Import.

5. Spring Insight immediately takes you to the Recent Activity page with the trace and its details displayed. To locate the tracein the Trace History pane, go back in time to when the trace was originally exported.



Customizing End Point Thresholds

The health of an End Point is based on how many traces took longer to execute than the response time threshold.

By default, Spring Insight uses a response time threshold of 200ms. In the response time histogram, the upper limit of the y-axisis 4-times the threshold, or 800ms by default. The time chunks of the y-axis are not evenly distributed, but rather, broken up in away to show the distribution of the response times of the recent End Point traces.

If, for a given trace or subset of traces, you find that the default threshold is too high or too low, you can change it. For example,if you find that all your response times for the .*show.* methods are almost always below 100ms, you might want to set thisas the threshold. The histogram will then have a smaller range, and thus show more fine grained information. Similarly, if youhave an end point in which the response times are always over 200ms, the health of this end point will almost always show asfrustrated. If you decide that it is acceptable if a threshold of 300ms is acceptable, then you can change it for this End Pointso it will show as appropriately healthy.

In other words, when you change the response time threshold for an End Point, you change the criteria that Spring Insight uses todecide whether it is healthy or not.

The following graphic shows the health and response time histogram for an End Point whose threshold is the default (200ms):

The upper limit in the histogram of 800ms, and the satisfied range is under 200ms. A response time of over 200ms but under800ms is tolerated, but over 800ms is frustrated, or unhealthy.

All response times are under the default threshold so the End Point is healthy. If the response times are all significantly below thedefault threshold, it might be a good candidate to lower the threshold to get more fine-grained response time information.

To change the threshold for an End Point or set of End Points:



1. From the main Spring Insight dashboard, click the Administration tab.

2. Click End Point Thresholds in the left pane.

3. In the right pane, click New:

4. In the Rule field, enter a regular expression that corresponds to the End Point or End Points for which you want to changethe threshold. For example, if you want to specify all show methods, enter .*show.*:

5. Enter the new threshold. As described above, the default Spring Insight threshold is 200 milliseconds.

6. Click the pencil icon. The new rule appears in the table. The Matching End Points column shows the number of End Pointsthat match this rule; the number is a link. Click on this link to see the list of matching End Points.

7. Click Make Permanent to apply your changes.

8. If you have three or more rules, you can use the up and down arrow buttons to change the order in which Spring Insightapplies the rules. Spring Insight applies the rules from first in the list to last. The default rule (.*) should always be last,since it matches all end points.



9. Browse to a trace that matches the rule. Note that the y-axis of the Response Time Histogram now has an upper limit of 4-times the new threshold. The health of the End Point is now satisfied when its response time is below the new threshold. Inour example, the new threshold is 100ms and so the upper limit is 400ms:



Viewing Spring Insight Data In Google Speed Tracer

Speed Tracer is a Google Chrome extension that analyzes how your application is performing inside the browser. It measureshow long the browser takes to render, transform CSS, show images, process events, and so on.

Although Speed Tracer is a great tool for determining where CPU time is spent within the browser process, it cannot see intowhat the application itself is doing in the back end. For that, it needs Spring Insight. The two products are now integrated so thatyou can now see Trace data interleaved with Speed Tracer's browser timings.

To see Spring Insight Trace data within Speed Tracer for an application deployed to Spring Insight, follow these steps:

1. Deploy your application to a tc Runtime instance that is configured with Spring Insight.

2. If you have not already done so, download the version of Google Chrome that has been instrumented for Speed Tracer,install the Speed Tracer extension, and launch the Chrome browser with the appropriate flag. For details, see Getting Startedwith Speed Tracer.

3. Open up the Speed Tracer console by clicking on the stopwatch icon in the top-right corner of the Google Chrome browser.

http://code.google.com/webtoolkit/speedtracer/





4. Using Google Chrome, navigate to a page of your deployed application and perform some action.

5. In Speed Tracer, click on the Network (resources) timeline. In the left column, search for resources that have a greypillbox, with tooltip Includes timing data from the server; these resources include Spring Insight data alongwith the standard Speed Tracer data. See the graphic in the next step.

6. Expand the resource to view the Spring Insight data, listed under the Server Trace section. This section includes a briefsummary of the Trace frame stack and allows easy navigation into various parts of Spring Insight related to the given Trace.To see more detailed information, select the Trace, End Point or Application links, which will jump into Spring Insight atthe appropriate location so you can further drill down.



Using Annotations To Customize Spring Insight Data For YourApplication

Spring Insight is implemented as a collection of plug-ins, each of which exposes specific types of method calls. Spring Insightincludes a default set of core plug-ins that expose a broad set of information about your application. For example:

• The insight-springcore plug-in allows all methods in your application that have been annotated with the SpringFramework @Service or @Repository annotations to be traced by Spring Insight.

• The insight-jdbc plug-in allows all calls to PreparedStatement.execute() in your application to be traced bySpring Insight.

See Core Plug-In Reference for the full set of core plug-ins that are included by default in Spring Insight.

The default set of core Spring Insight plug-ins exposes a lot of useful information about applications in general. However,these plug-ins may not provide as much visibility into your particular application as you might like. In this case, you can addSpring Insight-specific annotations to the Java source of your application to inform Spring Insight that it should trace and exposeone or more particular methods in your application. This is a quick and easy way to customize Spring Insight for your specificenvironment. Currently, Spring Insight supports the following annotations:

• @InsightOperation

• @InsightEndPoint

• @InsightObscure

• @InsightSensitive

See Example of Using the Spring Insight Annotations for a code example and a screenshot of Spring Insight that shows theannotations in action.

If you require Spring Insight to expose even more detailed information about your application, then you can use the SpringInsight Developer Kit to create your own plug-in which is tailored to the exact needs of your application. For details, seeOverview of Spring Insight Development.

@InsightOperation Reference

Specifies that Spring Insight should display the annotated method and its arguments in the Spring Insight Traces. Use the optionallabel and comment attributes to customize the display, as described in the following table.

Table 4.1. Attributes of @InsightOperation

Attribute Description

label Specifies what Spring Insight displays in the Trace frame stack for this method. A frame is the row in theTrace that you can expand or collapse so as to view more information about the method call.

If you do not specify this attribute, Spring Insight uses the label Class#method, such as Hello#doGet.

comment Specifies additional information that you want Spring Insight to display when you expand the frame. If youdo not specify this attribute, Spring Insight does not display any comment.

@InsightEndPoint Reference

@InsightEndPoint, like @InsightOperation, specifies that Spring Insight should display the annotated method andits arguments in the Spring Insight Traces. Additionally, the annotated method is declared as an End Point, which means thatit shows up in the Browse Resource list as an End Point. Use the optional label and comment attributes to customize thedisplay, as described in the following table.



Table 4.2. Attributes of @InsightEndPoint

Attribute Description

label Specifies what Spring Insight displays in the Trace frame stack forthis method. A frame is the row in the Trace that you can expand orcollapse so as to view more information about the method call.

If you do not specify this attribute, Spring Insight uses the labelClass#method, such as Hello#doGet.

comment Specifies additional information that you want Spring Insight to displaywhen you expand the frame. If you do not specify this attribute, SpringInsight does not display any comment.

@InsightObscure Reference

@InsightObscure is used to mark values that should be obscured before a trace is transmitted or stored. To obscure aparameter, annotate it:

public int login(String username, @InsightObscure String password) { ... do work... }

To obscure a return value from a method, annotate the method:

@InsightObscure public int getCCVNumber(AuthToken token) { ... return ccv; }

Obscured values will be replaced with [xxx] or -1 (for numeric values) within the Trace. If two strings which are to be obscuredoverlap, the longer strings will be obscured first. e.g. "batman123" and "123456" are sensitive. The value "batman123456" willbe changed to "[xxx]456"

@InsightSensitive Reference

@InsightSensitive is used to mark a method which processes sensitive data. Trace executions including this annotationwill not be stored or visible in the Insight Dashboard. Metrics about the end point will still be collected.

@InsightSensitive public int login(String username, String password) { ... do work... }

Example of Using the Spring Insight Annotations

The following code snippet shows how to use the @InsightOperation and @InsightEndPoint annotations in a simpleHello servlet Java class; only relevant code is shown (in bold):

package examples;...

import com.springsource.insight.annotation.InsightOperation;import com.springsource.insight.annotation.InsightEndPoint;

/**



* Simple Hello servlet. */

public final class Hello extends HttpServlet {

@InsightOperation(comment="This is the InsightOperation comment", label="doGet method of Hello class") @InsightEndPoint(comment="This is the InsightEndPoint comment", label="doGet method of Hello class")

public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {...

The example shows how to import the com.springsource.insight.annotation.InsightOperation andcom.springsource.insight.annotation.InsightEndPoint annotations, then use them on the doGet method.The following graphic shows how the comments and labels show up in the Trace Details section of Spring Insight after theannotated method is executed:



Getting the Annotation JAR File

The Spring Insight container provides the insight-annotation-version.jar file at runtime, so you do not have topackage this JAR file in your application. However, you do need this JAR file at compile time so you can successfully compilethe Java classes in your application that uses the Spring Insight annotations.

If you use Maven to build your application, add the following XML (shown in bold in the snippet) to your pom.xml file to makethe JAR file available to your project:

<repositories> <repository> <id>spring-release</id> <name>Spring Repository</name> <url>http://maven.springframework.org/release</url> </repository> ... </repositories>

<dependencies> <dependency> <groupId>com.springsource.insight</groupId> <artifactId>insight-annotation</artifactId> <version>1.8.3.RELEASE</version> <scope>provided</scope> </dependency> ... </dependencies>

Note that the preceding example depends on version 1.8.3.RELEASE of the Spring Insight JAR; when a new version releases,you should make the corresponding change in your pom.xml file.

If you use a build system other than Maven, you can download the annotation JAR file from the SpringSource community pageand then add the file to your compile-time CLASSPATH variable.

http://www.springsource.org/insight/develop

Overview of Spring InsightDevelopment

35


5. Overview of Spring Insight DevelopmentSpring Insight uses a plug-in architecture to collect, correlate, and analyze performance metrics from your application and fromdifferent pieces of third-party software that work with the application. You can deploy a native application to a Spring Insight-enabled tc Runtime instance and see diagnostics immediately, without further instrumentation. Or, you can use the Spring InsightDevelopment Kit to create plug-ins tailored to the needs of your application. The Developer Kit provides a copy of the sourcecode for all plug-ins shipped with Spring Insight and includes a sample plug-in to use as a starting point for creating your ownplug-in.

Use the Developer Kit to create plug-ins that extend Spring Insight functionality; for example:

• Collect trace details such as Hibernate flush times or JSP render times.

• Render custom HTML for an operation detail frame.

• Analyze traces and produce new types of End Points, such as a JMS message queue.

Among the metrics that the core plug-ins collect are:

• SQL statement capturing (jdbc plug-in)

• MVC Controller calls (spring-web plug-in)

• Grails controller calls (grails plug-in)

Note: The Spring Insight Developer Kit and supporting APIs are published under the Apache Software License, version 2.0.Other portions of Spring Insight, primarily the Trace repository and dashboard user interface, are licensed under the VMwareEULA. Plug-in authors are free to license their plug-ins as they see fit.

Prerequisites for Installing the Spring Insight Developer Kit

Before you install the Spring Insight Developer Kit:

• Install the Developer Edition of vFabric tc Server from the VMware Evaluation Center. See Getting Started with tc Server.

• Install Maven 2.0.10 or later (or a similar environment) and Java 1.6 or later.

Installing the Spring Insight Developer Kit

1. Download the Spring Insight Developer Kit from the SpringSource Community Web site. The name of the bundle isinsight-developer-kit-version.zip.

2. Create a directory that will hold the Developer Kit files and unzip the downloaded file into it. For example:

$ mkdir ~/dev/insight-dev$ cd ~/dev/insight-dev$ unzip /path/to/insight-developer-kit-version.zip

This creates a sub-directory called insight-developer-kit.

The Developer Kit installation consists of the following files:

samples/payme-insight-pluginsamples/payme-webappinsight-plugins/annotationinsight-plugins/grailsinsight-plugins/hibernateinsight-plugins/jdbcinsight-plugins/method-endpointinsight-plugins/servlet

http://www.apache.org/licenses/LICENSE-2.0.html

https://my.vmware.com/web/vmware/evalcenter?p=tcserver-dev



36Overview of Spring Insight

Development

...

• payme-insight-plugin is a sample plug-in for Spring Insight. It is a good template for writing new plug-ins.

• payme-webapp is a simple web application that demonstrates the payme-insight-plugin capabilities.

• insight-plugins/* are copies of the source code for the Spring Insight plug-ins that ship with the project; for the full list and adescription of each of these plug-ins, see Core Plug-in Reference. The code is also a good reference for the variety of tasks thatplug-ins can accomplish.

Using the Spring Insight Plug-ins 37


6. Using the Spring Insight Plug-ins

The fundamental concepts to understand about Spring Insight are:

• Target application: A Web application for which you want to monitor the run-time performance.

• Operation: An interface (Operation.java) that plug-ins can implement to store information about the captured workbeing done. An Operation implementaton is an item of work, for example, a socket opening, a cache miss, a method call, or aJDBC SELECT. Operations are defined by plug-ins and contain all the information needed to capture the work being done.

Operations must be serializable and can contain only fields that are classes within the JDK or the plug-in itself.

• Frame: Represents a unit of execution within a call hierarchy. Typically a frame equates to a method call in a stack, butthis is not always necessary. A frame can be created for any logical event that a plug-in dictates. A frame holds informationabout when an event occurred and about the frame's nested relationship to other frames. The meat of the frame lies within theOperation.

• Trace: A recording of a single thread of execution for an application. A trace can represent a single web request (and all thework it did), or it could represent a JMS message listener's processing times. A trace contains a nested tree of frames, whichcontain the details of the work done.

• Endpoint: Logical grouping of similar traces within an application. Health and response time metrics are calculated for EndPoints based on the traces that match that End Point. End Points for a given trace are identified by EndPointAnalyzers thatpost-process a trace after it is collected. All EndPointAnalyzers known to Insight process each trace. The analyzer with thehighest score—that is, the analyzer that the plug-in determines has most closely identified the End Point—defines the trace asbelonging to a particular End Point.

End Points are visible in the Insight dashboard under the Browse Resources tab. For example, in a Spring MVC application,End Points are defined by the @RequestMapping method that receives the request dispatch. All traces dispatched to the samemethod are members of the same End Point. In a production-ready application, a trace potentially matches multiple End Points.For web requests, the Spring MVC controller defines End Points, but not all web requests are processed by Spring MVC. Theraw Servlet to which the request was initially mapped can also define an End Point. In this case, the more specific End Pointcontains the trace; the Spring MVC End Point trumps the Servlet End Point.

• Aspect: Primary mechanism used by Spring Insight plug-ins to collect runtime data about a user's application. Aspects inSpring Insight typically have the role of collecting data about the target application and storing it into implementations of anOperation.

• Spring Insight: The entirety of Operation collection, End Point analysis, trace storage, and the user interface.

Relationships Among Spring Insight Objects and Plug-ins

This diagram illustrates the relationship among Spring Insight objects. A trace contains a hierarchical list of frames, each with anassociated Operation.


38 Using the Spring Insight Plug-ins

This diagram illustrates the relationship between the plug-ins and the core objects of Spring Insight, with respect to operations.



Building and Deploying the Sample Plug-in

The following procedure describes how to build and deploy the sample payme-insight-plugin plug-in from the SpringInsight Developer Kit. In the procedure, it is assumed that:

• You unzipped the Spring Insight Developer Kit into the dev/insight-dev sub-directory of your home directory (in otherwords, ~/dev/insight-dev.)

• You installed the Developer Edition of vFabric tc Server in /home/s2 and you created an instance called insight-instance using the insight template to run Spring Insight and deploy applications.

• You have installed Maven on your computer. See Maven Users Center for information about downloading Maven and gettingstarted.

1. Build the sample plug-in from the Spring Insight Developer Kit using Maven:

http://maven.apache.org/users/index.html



$ cd ~/dev/insight-dev/vfabric-insight-developer-kit-1.8.X.X/samples/payme-insight-plugin$ mvn clean package

The build creates and packages the plug-in into a JAR file in the target child directory of payme-insight-plugin.

2. Copy the plug-in JAR file into the insight/collection-plugins directory of the Spring Insight-enabled tc Runtimeinstance insight-instance:

$ cp target/payme-insight-plugin-version.jar \ /home/s2/vfabric-tc-server-developer-2.7.X.X/insight-instance/insight/collection-plugins

Note: For clarity, the preceding command is shown on two lines, but you should execute it all on one line.

3. Build the sample web application that is included with the payme plug-in:

$ cd ~/dev/insight-dev/samples/payme-webapp$ mvn clean package

4. Deploy the resulting WAR by copying it from the target directory to the webapps directory of the tc Runtime instance:

$ cp target/payme-webapp.war /home/s2/vfabric-tc-server-developer-2.7.X.X/insight-instance/webapps

5. Start (or restart if it is already running) the tc Runtime instance to activate the plug-in. For example:

$ cd /home/s2/vfabric-tc-server-developer-2.7.X.X$ ./tcruntime-ctl.sh insight-instance start

6. Using your browser, navigate to the Spring Insight dashboard (http://localhost:8080/insight.)

In a new browser, open http://localhost:8080/payme-webapp, which is the URL for the payme-webapp.Reload the screen a few times to create some activity that Spring Insight will track.

Back on the Spring Insight dashboard, you will see traces for each Web request to payme-webapp.

7. Select the Recent Activity tab, then select the payme-webapp from the Applications pull-down list.

8. Select any column in the Trace History timeline at the top of the page.

A trace loads at the bottom of the page that shows the CashMoneyOperation. A screen similar to the followingindicates that the plug-in is working correctly.



Using the Sample Plug-in

The sample plug-in, payme-insight-plugin, makes it easy for a developer to add new instrumentation for a specifictechnology such as Hibernate or Struts. The sample does not provide an example for creating an End Point, although other plug-ins within the Developer Kit show how this can be accomplished.

The sample demonstrates how to extract details from calls within a target application. In this case, the plug-in intercepts allcalls to .setBalance(int) on any object. This capability is useful when you have many different Web applications, withdifferent domains (credit card accounts, investment accounts) that you want to monitor. As long as the Web application calls.setBalance(int), the balance that is set will be recorded by Spring Insight, with no need to change code in any Webapplication.

Sample Plug-in Files

The files included with the sample represent most of the files a typical plug-in needs. Each file contains more detaileddocumentation.

src/main/java/org/myorg/insight/myplugin/CashMoneyOperation.javasrc/main/java/org/myorg/insight/myplugin/CashMoneyOperationCollectionAspect.ajsrc/main/resources/META-INF/insight-plugin-myplugin.xmlsrc/main/resources/org/myorg/insight/myplugin/cash_money_operation.ftl

CashMoneyOperation.java

The CashMoneyOperation.java file represents what happens when setBalance() is called on an object.The CashMoneyOperationCollectionAspect captures the argument to setBalance() and populates theCashMoneyOperation with this data.

It is the plug-in's own implementation of Operation that holds information captured by the aspect. When the aspect interceptsa call to setBalance(30), for example, it takes the 30 and creates a new CashMoneyOperation with that information.Implementations of Operation primarily act as simple beans.



CashMoneyOperationCollectionAspect.aj

The aspect that intercepts calls to setBalance() and creates new CashMoneyOperations. For more details, seeCollecting Runtime Data.

insight-plugin-myplugin.xml

The insight-plugin-myplugin.xml file is the plug-in descriptor, a Spring application context file that is packaged withthe plug-in. Spring Insight uses this file to locate and initialize the plug-in and to learn how the UI should render the plug-in'sspecific data.

The file contains a plain Spring XML beans definition. The file is included in the plug-in JAR and must follow this pattern: /META-INF/insight-plugin-pluginname.xml. The most common beans to define are EndPointAnalyzers and customviews for operations. See EndPointAnalyzer.

cash_money_operation.ftl

The FreeMarker template that is rendered when the CashMoneyOperation is displayed in the Spring Insight dashboard. Thetemplate is populated with a binding for Operation onto an instance of CashMoneyOperation. See Operation Renderingin the UI.

The filename (cash_money_operation.ftl) is looked up via the insight-plugin-myplugin.xml configurationfile.

Collecting Runtime Data

Spring Insight gathers data from a running Web application primarily through the use of Aspect Oriented Programming (AOP).AspectJ is an Open Source AOP technology that allows Spring Insight to capture data without any changes to the user's code.

Plug-ins can define their own aspects, which will be woven into the target application at runtime. Plug-ins also define their ownOperation subclasses that can be instantiated by the aspects. These plug-in operations are then moved through the SpringInsight repository for storage and later viewing.

The sample plug-in uses aspects to intercept calls to methods called setBalance().

See CashMoneyOperationCollectionAspect.aj.

Operation Rendering in the UI

If a plug-in creates its own Operation, it should also create a view to render it in the UI. Plug-ins can define a Spring Viewwith which to render their Operation into HTML. FreeMarker is the recommended view technology. You can use otherview technology if it implements the Spring View interface. However, the libraries needed to render the view must already beavailable. JSP is not an option because the files live outside the servlet environment.

When rendering a trace in the UI, the Spring Insight dashboard examines the OperationType of each Operation in thetrace. It uses this type to locate an associated view. If a plug-in defines the view, the Spring Insight dashboard renders it andincludes the generated content in the response.

For operations that do not define a view, a generic view attempts to display all the properties of the Operation. Although thegeneric view is useful while you are developing a plug-in, we do not recommend shipping a plug-in that depends on this view.

Inside the plug-in's Spring context, you register a view as follows:

<bean id="operation.cash_money_operation" class="org.springframework.web.servlet.view.freemarker.FreeMarkerView"> <property name="url" value="org/myorg/insight/myplugin/cash_money_operation.ftl"/></bean>



The bean ID must take the form "operation.operationTypeIdentifier". The URL property is the path to theFreeMarker template from the root of the JAR.

The rendered HTML should be clean, balanced, and semantic.

<h2>Operation Title</h2><table class="dl"> <tr> <td>Name1</td> <td>Value1</td> </tr> <tr> <td>Name2</td> <td>Value2</td> </tr> ...</table>

The Spring Insight Dashboard web application includes a FreeMarker macro file you can use to ensure your operation is renderedin a consistent way. The above HTML can be written this way:

<#ftl strip_whitespace="true"><#import "/insight-1.0.ftl" as insight />

<@insight.group label="Operation Title" > <@insight.entry name="Name1" value=operation.Property1 /> <@insight.entry name="Name2" value=operation.Property2 /></@insight.group>

In the example, Property1 and Property2 are properties with getters in the Operation class. The value of the nameattribute is printed in the first table column and the value returned by the getter (value attribute) is rendered in the secondcolumn. See the core plug-in source code for more examples.

EndPointAnalyzer

Plug-ins can hook into the Analyze End Points phase of Spring Insight, allowing them to define their own concept of whatconstitutes an End Point. An EndPointAnalyzer looks at a trace and says, "This is a Servlet End Point at /imageServlet" or "Thisis a Controller End Point at BankController#debitAccount."

Most plug-ins do not need to implement this functionality. It is most useful for dispatching frameworks such as MVC, JMS, andServlets.

All registered EndPointAnalyzers can look at each trace as it is created and determine which End Points it has. Because manyplug-ins run per trace and each one can produce its own EndPointAnalysis, only a single EndPointAnalysis will represent thetrace. It is determined by the score field within EndPointAnalysis.

To create a new EndPointAnalyzer, create a class that implements EndPointAnalyzer and expose the class to Spring Insightby adding it to the plug-in's Spring context file (insight-plugin-myplugin.xml).

The following diagram shows plug-ins creating End Point analysis based on trace examination.



Building a Plug-in from the Source Code

The Spring Insight Developer Kit contains the source code for the standard Spring Insight plug-ins, which is licensed under theApache License 2.0. The source code for the Spring Insight dependencies (core packages) is available as source jars, throughEclipse and Maven. Eclipse makes these jars available after you import the sample plug-in.

If you are not using Eclipse, visit the SpringSource community site to download these source jars directly.

For more information about core plug-in functionality, see Core Plug-in Reference.

To build a specific plug-in, for example, insight-jdbc:

$ cd insight-plugins/jdbc




$ mvn clean package

Tutorial: Creating an Insight Plug-inwith the Insight Development Kit

47


7. Tutorial: Creating an Insight Plug-in with the InsightDevelopment Kit

This tutorial describes how to create a Spring Insight plug-in called insight-plugin-tiles using the Insight DevelopmentKit. The purpose of the plug-in is to capture the amount of time that Apache Tiles spends rendering content. Apache Tiles is atemplating framework built to simplify the development of Web application user interfaces.

In particular, the plug-in will track how much time is spent in the org.apache.tiles.TilesContainer#rendermethod. The signature of the render method is:

TilesContainer#render(String definitionName, Object... requestItems)

The plug-in will intercept all calls to this method when it is invoked in the target application. Insight will track how much time isspent in this method and create new operations based on the definitionName.

In the tutorial it is assumed that you do not have any required product installed, and so the tutorial provides the steps to downloadand install everything you need. If, however, you have already installed one or more of these products, modify the tutorialaccordingly. The full list of products or bundles required for this tutorial is as follows:

• vFabric tc Server Developer Edition, version 2.7

• SpringSource Tool Suite, version 2.3

• git and read access to the Spring Insight Github Repository

Follow these steps to create a sample Spring Insight plug-in:

1. Create a workspace. For example, to create a workspace dev/insight-dev in your home directory:

$ cd ~$ mkdir dev/insight-dev$ cd dev/insight-dev

You will do all your development within the ~/dev/insight-dev directory. Everything that you download, install, andcreate will be contained here.

2. Download tc Server Developer Edition from the VMware evaluation site.

Assuming you downloaded the files into ~/dev/insight-dev, you should see the following:

$ lsvfabric-tc-server-developer-2.7.X.X.zip

3. Install tc Server, if necessary, by unpacking the ZIP file into the ~/dev/insight-dev directory.

If you have already installed tc Server, you can skip this step.

$ cd ~/dev/insight-dev$ unzip vfabric-tc-server-developer-2.7.X.X.zip

Replace X.X with the actual version numbers. This creates a child directory called vfabric-tc-server-developer.

4. Create a tc Server instance that uses the insight template and start it:

$ cd vfabric-tc-server-developer$ ./tcruntime-instance.sh create insight-instance -t insight$ ./tcruntime-ctl.sh insight-instance start

http://tiles.apache.org/framework/index.html

https://github.com/SpringSource/spring-insight-plugins

https://my.vmware.com/group/vmware/evalcenter?p=tcserver-dev


48Tutorial: Creating an Insight Plug-in

with the Insight Development Kit

5. Verify that Insight is working.

Browse to http://localhost:8080/insight to verify Insight started correctly. If so, you should see The SpringInsight Dashboard.

6. Clone or Fork the Spring Insight Plugin Github Repository:

If you are a github user you can fork the Spring Insight repository by clicking on the "fork" link. Once you have therepository ready you will need to clone the repository to develop the plugin. The following instructions assume that you onlyhave read access to the spring repository:

$ cd ~/dev/insight-dev$ git clone git://github.com/SpringSource/spring-insight-plugins.git $ cd spring-insight-plugins$ git checkout insight-1.8.3.RELEASE

This checks out the current github repository for public insight plugins, and switches to the 1.8.3.RELEASE branch.

7. Create the insight-plugin-tiles plug-in.

Use the sample plug-in from the samples directory to create a new plug-in, called insight-plugin-tiles, in yourinsight-dev directory:

$ cd ~/dev/insight-dev$ cp -Rp spring-insight-plugins/samples/payme-insight-plugin insight-plugin-tiles

The preceding action sets up an insight-plugin-tiles plug-in with a build system, test framework, and so on.Because this tutorial tells you which files to create, in the correct sequence, you can remove the ones that come with thepayme-insight-plugin. These files can serve as a reference and starting point when you create your own plug-in.

$ cd ~/dev/insight-dev/insight-plugin-tiles$ rm -rf src/main/java/org/myorg/insight/myplugin$ rm src/main/resources/META-INF/insight-plugin-myplugin.xml$ rm -rf src/main/resources/org/myorg/insight/myplugin$ rm -rf src/test/java/org/myorg/insight/myplugin

8. If you want to use SpringSource Tool Suite (STS) as your IDE, and you have not yet installed it, download the latest versionfrom STS Product Page, then install and start it.

9. Import insight-plugin-tiles into SpringSource Tool Suite (Eclipse) or another IDE.

From SpringSource Tool Suite:

a. Select File > New > Java Project.

b. Select Create Project from Existing Source.

c. Enter ~/dev/insight-dev/insight-plugin-tiles (or whatever is appropriate for your environment) in theDirectory field.

d. Click Finish.

http://www.springsource.com/developer/sts


49





10. The insight-plugin-tiles plug-in requires some Apache Tiles interfaces and classes. You can make these availableby including the Maven dependency shown in the preceding snippet. You will usually want to use the provided scope.The target application provides the jars at runtime.

Update the Maven pom.xml file by adding the following dependency in the <dependencies> section:

<dependency> <groupId>org.apache.tiles</groupId> <artifactId>tiles-core</artifactId> <version>2.1.3</version> <scope>provided</scope> </dependency>


51


11. Change the plug-in name in pom.xml.

Update the properties at the top of the file to reflect what you are building. The artifactId, name, and version dictate the filethat is generated by the build process.

<groupId>org.myorg.insight</groupId> <artifactId>insight-plugin-tiles</artifactId>




<name>insight-plugin-tiles</name> <packaging>jar</packaging> <version>0.0.1.SNAPSHOT</version>

12. Create the TilesRenderOperationCollectionAspect class.

This aspect will be woven into the target application at runtime by AspectJ. In this aspect you specify the method thatyou want to capture (TilesContainer.render()) as the collectionPoint pointcut. The aspect is also responsible forcreating new instances of the TilesRenderOperation that you just created.

Name this file TilesRenderOperationCollectionAspect.aj and create it in the following directory: src/main/java/org/myorg/insight/tiles.

package org.myorg.insight.tiles;

import org.apache.tiles.TilesContainer;import org.aspectj.lang.JoinPoint;

import com.springsource.insight.collection.AbstractOperationCollectionAspect;import com.springsource.insight.intercept.operation.Operation;import com.springsource.insight.intercept.operation.OperationType;

/** * Tiles Render Aspect for Spring Insight */public aspect TilesRenderOperationCollectionAspect extends AbstractOperationCollectionAspect{ private static final OperationType TYPE = OperationType.valueOf("tiles_render_operation");

// Declare which methods we wish to instrument public pointcut collectionPoint() : execution(void TilesContainer.render(String, Object...));

// Create an operation containing information about calls to // the render method. @Override protected Operation createOperation(JoinPoint jp) { Object[] args = jp.getArgs(); String definitionName = (String)args[0]; return new Operation() .type(TYPE) .sourceCodeLocation(getSourceCodeLocation(jp)) .label("Tiles Render: " + definitionName) .put("definitionName", definitionName); }}

13. Create the DummyTilesContainer class for testing.

In this step, you create a dummy implementation to test that all implementations of TilesContainer.render() arecaptured by the aspect.

When the Target Application is really running (because it is deployed to a running tc Runtime instance, and so on), thetarget application will occasionally make calls to the TilesContainer.render() methods. During testing, you createa dummy implementation of TilesContainer to test that the Aspects are able to correctly intercept calls.

Create src/test/java/org/myorg/insight/tiles/DummyTilesContainer.java:


import java.io.IOException;import java.io.Writer;import java.util.Map;


53


import org.apache.tiles.Attribute;import org.apache.tiles.AttributeContext;import org.apache.tiles.TilesApplicationContext;import org.apache.tiles.TilesContainer;

public class DummyTilesContainer implements TilesContainer {

public void endContext(Object... requestItems) { }

public Object evaluate(Attribute attribute, Object... requestItems) { return null; }

public TilesApplicationContext getApplicationContext() { return null; }

public AttributeContext getAttributeContext(Object... requestItems) { return null; }

public void init(Map<String, String> initParameters) { }

public boolean isValidDefinition(String definition, Object... requestItems) { return false; }

public void prepare(String preparer, Object... requestItems) { }

public void render(String definition, Object... requestItems) { }

public void render(Attribute attribute, Object... requestItems) throws IOException { }

public void render(Attribute attribute, Writer writer, Object... requestItems) throws IOException { }

public void renderContext(Object... requestItems) { }

public AttributeContext startContext(Object... requestItems) { return null; }}

14. Create the test.

To verify that the code works, create a unit test. You will run the test as part of the Maven build to verify thatTilesRenderOperation is successfully captured by the TilesRenderOperationCollectionAspect.

Create src/test/java/org/myorg/insight/tiles/TilesRenderOperationCollectionAspectTest.java:


import static org.junit.Assert.assertEquals;

import org.junit.Test;

import com.springsource.insight.collection.OperationCollectionAspectSupport;import com.springsource.insight.collection.OperationCollectionAspectTestSupport;import com.springsource.insight.intercept.operation.Operation;




public class TilesRenderOperationCollectionAspectTest extends OperationCollectionAspectTestSupport{ @Test public void myOperationCollected() { // Step 1: Execute some implementation of TilesContainer#render DummyTilesContainer container = new DummyTilesContainer(); container.render("myDefinition", "requestItem1", "requestItem2");

// Step 2: Get the Operation that was just created by our aspect Operation op = (Operation) getLastEntered();

// Step 3: Validate assertEquals("myDefinition", op.get("definitionName", String.class)); assertEquals("Tiles Render: myDefinition", op.getLabel()); assertEquals(DummyTilesContainer.class.getName(), op.getSourceCodeLocation().getClassName()); assertEquals("render", op.getSourceCodeLocation().getMethodName()); }

public OperationCollectionAspectSupport getAspect() { return TilesRenderOperationCollectionAspect.aspectOf(); }}

15. Run the test:

$ cd ~/dev/insight-dev/insight-plugin-tiles$ mvn test

If everything works correctly, you will see BUILD SUCCESSFUL.

You can also run the test from the SpringSource Tool Suite. Right-click onTilesRenderOperationCollectionAspectTest.java and select Run-As > JUnit Test.

16. Copy the insight-plugin-tiles plug-in into the the insight/collection-plugins directory of yourtcServer instance

It is time to try out the plug-in in Insight to verify that it works. Deploy the new plug-in to the tc Runtime instance bycopying the generated plug-in JAR file into the insight/collection-plugins directory of your tc Runtime instance(created in a previous step and called insight-instance):

$ cd ~/dev/insight-dev/insight-plugin-tiles$ mvn clean package$ cp target/insight-plugin-tiles-0.0.1.SNAPSHOT.jar \ ../vfabric-tc-server-developer/insight-instance/insight/collection-plugins

Note: For clarity, the preceding command is shown on two lines, but you should execute it all on one line.

17. Update the configuration of the Spring Insight application so that you can view trace information about the Insightapplication itself. By default, Spring Insight does not instrument itself.

Change this behavior by commenting out the application.context.ignore.dashboard: localhost|insight property in the insight.properties file, which is located in the ../vfabric-tc-server-developer/insight-instance/insight/conf directory.

The following insight.properties snippet shows the property commented out (see section in bold):

...# Application Context Instrumentation# Specify application contexts which should not be instrumented# by Insight. Removing contexts that do not need Insight will improve# startup time of the application. Each entry must be prefixed with# "application.context.ignore." and takes the form of


55


# "[Host name]|[Context name]"##application.context.ignore.myapp: localhost|my-app#application.context.ignore.dashboard: localhost|insight...

We perform this step because we want to use the Insight Dashboard itself, which uses Tiles to display its UI, as a way to seethe plugin in action. Because the insight-plugin-tiles plug-in will also collect data for the Insight Dashboard, youcan see the effect immediately, but you must first specify that you want Insight to instrument itself.

18. Start (or restart if it is already running) the tc Runtime instance to view the new TilesRenderOperation. For example,to start:

$ cd ../vfabric-tc-server-developer$ ./tcruntime-ctl.sh insight-instance start

Navigate to http://localhost:8080/insight to see the insight-plugin-tiles plug-in in action. Choosethe insight (Insight Dashboard) application to narrow down the traces to just those generated by Insight itself.

Click around in the Insight Dashboard to generate some pages (select Browse Resources, or drill into Trace Operations).Here you select a Trace from the timeline and can see the TilesRenderOperation showing how much time it took torender different tiles when generating the result of a request to http://localhost:8080/insight/endpoints/insight.




The drilldown into the Tiles Render: traces/trace operation shows details about theTilesRenderOperation. Notice the Return Value: void and Exception: null properties. Those(along with the Tiles Render Operation Operation) are generated automatically by examining theTilesRenderOperation. To customize the UI that is rendered for the TilesRenderOperation, you must add it tothe plug-in, as described in the following steps.

19. In your IDE, such as STS in this tutorial, add the tiles_render_operation.ftl view.

Insight plug-ins can use FreeMarker to customize the view. Create the following FreeMarker template using your IDE:

src/main/resources/org/myorg/insight/tiles/ tiles_render_operation.ftl:

<#ftl strip_whitespace=true><#import "/insight-1.0.ftl" as insight />


57


<@insight.group label="Tiles Render Operation"> <@insight.entry name="definitionName" value=operation.definitionName /><@insight.group>

The operation variable is bound to an instance of TilesRenderOperation. The FreeMarker code

operation.definitionName

calls the method TilesRenderOperation.getDefinitionName(). You can access all properties from yourTilesRenderOperation if they have a getter (getDefinitionName()).

20. Register the view with the plug-in.

Insight locates views for Operations by looking for insight-plugin-*.xml Spring Application Context descriptorfiles. To enable the custom view, you inform Insight about it by adding the view to it.

Create src/main/resources/META-INF/insight-plugin-tiles.xml:

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:insight="http://www.springframework.org/schema/insight-idk" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/insight-idk http://www.springframework.org/schema/insight-idk/insight-idk-1.0.xsd"><insight:plugin name="tiles" version="0.0.1" publisher="[your name here]" /><insight:operation-view operation="tiles_render_operation" template="org/myorg/insight/tiles/tiles_render_operation.ftl"/></beans>

This file points Insight at the tiles_render_operation.ftl view when it attempts to render aTilesRenderOperation. The TilesRenderOperation.getType() method returns an OperationType thatInsight uses to compose the bean id (operation.tiles_render_operation).

21. Create a test for the view.

The view takes the TilesRenderOperation as an input parameter and renders thetiles_render_operation.ftl based on it. You will create a TilesRenderOperationViewTest to verifythat this rendering works.

The AbstractOperationViewTest allows you to test tiles_render_operation.ftl rendering in only a fewlines. Here you create a TilesRenderOperation, run it through the TilesRenderOperationView and make surethe output contains strings specified in the operation.

Create src/test/java/org/myorg/insight/tiles/ TilesRenderOperationViewTest.java:


import static org.junit.Assert.assertTrue;

import org.junit.Test;import org.junit.runner.RunWith;import org.springframework.test.context.ContextConfiguration;import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

import com.springsource.insight.idk.AbstractOperationViewTest;import com.springsource.insight.idk.WebApplicationContextLoader;import com.springsource.insight.intercept.operation.SourceCodeLocation;@ContextConfiguration(locations = { "classpath:META-INF/insight-plugin-tiles.xml", "classpath:META-INF/test-app-context.xml" }, loader = WebApplicationContextLoader.class)@RunWith(SpringJUnit4ClassRunner.class)public class TilesRenderOperationViewTest




extends AbstractOperationViewTest{ public TilesRenderOperationViewTest() { super(TilesRenderOperation.TYPE); }

@Test public void testView() throws Exception { SourceCodeLocation scl = new SourceCodeLocation("MyClass", "methodName", 45); TilesRenderOperation operation = new TilesRenderOperation(scl, "myTileDefinition");

String content = getRenderingOf(operation); System.err.println(content);

// Simply test for some expected contents within the HTML. assertTrue(content.contains("definitionName")); assertTrue(content.contains("myTileDefinition")); }}

22. Run the test.

$ cd ~/dev/insight-dev/insight-plugin-tiles$ mvn test

The test should report BUILD SUCCESSFUL.

23. Try out the new view in Insight.

To try out the new view, you copy a new package of your plug-in to the tc Runtime instance and (re)start it:

$ mvn clean package$ cp target/insight-plugin-tiles-0.0.1.SNAPSHOT.jar \ ../vfabric-tc-server-developer/insight-instance/insight/collection-plugins$ cd ../vfabric-tc-server-developer$ ./tcruntime-ctl.sh insight-instance restart

Note: For clarity, the second command in the preceding example is shown on two lines, but you should execute it all on oneline.

Click around in Insight to generate some traces. Here is a trace that was generated for /insight/applications/endpoints/insight:


59


Contributing Plugins to Insight Core 61


8. Contributing Plugins to Insight CoreContributing plugins back to the insight project has a number of advantages. The plugin becomes part of our internal buildprocess and will be maintained as the plugin API changes. The plugin API can change between core releases of insight as wedevelop new strategies for optimizing and managing plugins.

Most plugins are developed at our Spring Insight Github Repository and the easiest way to contribute plugins is to fork thisrepository and perform a pull request. Different releases of insight are in unique branches of this repository.

Insight plugins are often designed to run in production and there are a number of key things a plugin developer can do tohelp improve adoption. One of the primary goals is to reduce the number of objects created within the context of theser's webapplication through caching or by limiting the scope of the data collected. Additionally there are more general requirements tohelp the Insight team integrate a plugin into the distribution.

General Requirements for plugins:

1. Must extend OperationCollectionAspectSupport or AbstractOperationCollectionAspect

2. For 1.9+ plugins, you must implement getPluginName()

3. Few new objects created during plugin operaiton (createOperation and other methods)

4. Use of caching to reduce the number of objects created

5. Provide a screenshot of the plugin in action

6. Provide a sample web application and guide on testing the plugin

7. Include a README.textfile

8. Include a mention of the versions of the framework which the plugin supports

9. Include Unit tests for all aspects and classes

10. Include Freemarker test for ftl rendering (if using ftl)

11. Follows the licensing and legal requirements described at the github repository

https://github.com/SpringSource/spring-insight-plugins


62 Contributing Plugins to Insight Core

Core Plug-in Reference 63


9. Core Plug-in ReferenceMost metrics are contributed by plug-ins. Several plug-ins ship with the core product. Developers can create their own plug-ins.Only core plug-ins are documented here.

annotation

Use of the @Insight* annotations are optional. They make it easy for end users to define custom operation frames and endpoints without needing to create a plug-in. Because end user code modification is required to use the annotations, they are anoption for users who cannot or do not wish to write aspects.

For more information on using the @Insight* annotations, see Using Annotations To Customize Insight Data For YourApplication.

Table 9.1. Operations of annotation plug-in

Collection Point Summary

@InsightOperation Any methods annotated with @InsightOperation will create an operation, including: basicsource code location, method parameters and the return value.

@InsightEndPoint Similar to @InsightOperation; also indicates the operation should be treated as an end point.

@InsightObscure Used to annotate a value which should be obscured from Trace transmission or storage.

@InsightSensitive Used to mark a method which processes sensitive data.

Table 9.2. Endpoint Analysis of annotation plug-in

Analyzer AnnotatedMethodEndPointAnalyzer

Core Operation AnnotatedMethod Operation

Score High by default, customizable in annotation.

Summary Finds operations created from @InsightEndPoint, thus creating the end point.

apache-http-client3

Traces calls to external HTTP resources using the Apache HTTP client version 3.

Table 9.3. Operations of Apache HTTP Client 3 plug-in


HttpClient.executeMethod(...) Execution of HTTP calls

apache-http-client4

Traces calls to external HTTP resources using the Apache HTTP client version 4.

Table 9.4. Operations of Apache HTTP Client 4 plug-in


HttpClient.execute(...) Execution of HTTP calls

blazeds

Tracing of calls to BlazeDS. Supports the message broker APIs as well as command and message based communication.


64 Core Plug-in Reference

Table 9.5. Operations of BlazeDS plug-in


MessageBroker.route*(..) Message broker operations

Service.serviceMessage(..) Remote object and message based operations

Service.serviceCommand(..) Command based operations

Table 9.6. Endpoint Analysis of BalzeDS plug-in

Analyzer BlazeDSEndPointAnalyzer

Score Varies.

Summary Creates an end point for HTTP requests handled by BlazeDS.

ehcache

Tracing of calls to Ehcache

Table 9.7. Operations of ehcache plug-in


Get Get value from Ehcache

Put Put value in Ehcache

Remove Remove a value from Ehcache

Replace Replace a value in Ehcache

ejb3

Tracing of calls to EJB3 beans

Table 9.8. Operations of EJB3 plug-in


@Stateful Execution of stateful beans

@Stateless Execution of stateful beans

files-tracker

Tracing of file open and close operations

Table 9.9. Operations of files tracker plug-in


Open A file was opened

Close A file was closed

gemfire

Tracing of calls to GemFire



Table 9.10. Operations of gemfire plug-in


Region Writing and reading values using the GemFire Region APIs

Query Querying GemFire using the Query APIs

grails

Grails-specific support for controller methods.

Table 9.11. Operations of grails plug-in


Grails Controller Method Method on a Grails Controller to which the request is mapped.

Table 9.12. Endpoint Analysis of grails plug-in

Analyzer GrailsControllerMethodEndPointAnalyzer

Core Operation GrailsControllerMethodOperation

Score Varies.

Summary Creates an end point for HTTP requests handled by Grails.

hibernate

Support for tracing Hibernate persistence operations, such as get, save, update, and delete. A Hibernate session represents onetransaction, which may include several database transactions. The hibernate plug-in collects the method name (flush, save,update, delete, etc.), entity count (the number of entity instances associated with the Hibernate session), and collection count (thenumber of collection instances associated with the session).

Table 9.13. Operations of hibernate plug-in


org.hibernate.Session CRUD operation on persistent entities.

javax-mail

Tracing of mail sending using java mail

Table 9.14. Operations of javax-mail plug-in


javax.mail.Transport.sendMessage(..) Sending an email message.

jax-rs

JAX-RS trace support.

Table 9.15. Operations of jax-rs plug-in


@DELETE Collect DELETE operations.

@GET Collect GET operations.




@HEAD Collect HEAD operations.

@POST Collect POST operations.

@PUT Collect PUT operations.

Table 9.16. Endpoint Analysis of grails plug-in

Analyzer JaxrsEndPointAnalyzer

Score Varies.

Summary Creates an end point for HTTP requests handled by JAX-RS.

jdbc

Low level support for tracing raw SQL queries.

Table 9.17. Operations of jdbc plug-in


java.sql.Statement Operation with the raw SQL statement.

java.sql.PreparedStatement Operation with the raw SQL statement and parameters.

jms

jms trace support.

Table 9.18. Operations of jms plug-in


MessageConsumer Tracing for the javax.jms.MessageConsumer APIs

MessageListener Tracing for the javax.jms.MessageListener APIs

MessageProducer Tracing for the javax.jms.MessageProducer APIs

Table 9.19. Endpoint Analysis of jms plug-in

Analyzer JMSConsumerEndPointAnalyzer and JMSMessageListenerEndPointAnalyzer

Score Varies.

Summary Creates an end point for messages that are received on a queue or topic.

jws

jws trace support.

Table 9.20. Operations of jws plug-in


@WebService Tracing for the javax.jws.WebService APIs

Table 9.21. Endpoint Analysis of jms plug-in

Analyzer JwsEndPointAnalyzer



Score Varies.

Summary Creates an end point for HTTP requests handled by JAX-RS.

logging

Logging frameworks support. Currently supports Log4J, SLF4J and Commons logging. This plugin will create error traces whenan error or fatal message is logged.

Table 9.22. Operations of logging plug-in


Log.error and Log.fatal Logging using commons logging

Category.error and Category.fatal Logging using Log4J

Logger.error Logging using SLF4J

method-endpoint

Creates an end point for a root-level operation within a trace. When a web request invokes a method asynchronously (backgroundthreads, scheduled threads, etc.), this plug-in creates an end point for it.

Table 9.23. Endpoint Analysis of method-endpoint plug-in

Analyzer TopLevelMethodEndPointAnalyzer

Core Operation MethodOperation

Score Low.

Summary Creates an end point for a root-level operation within a Trace.

mongodb

Support for tracing MongoDB queries.

Table 9.24. Operations of mongodb plug-in


com.mongodb.DBCollection Operations with the DBCollection APIs. insert, update, remove, save, find, count,group, distinct, map reduce and index operations are supported

com.mongodb.DBCursor Operations with the DBCursor APIs. next, skip, limit, toArray and sort operations aresupported

quartz-scheduler

Support for tracing Quartz scheduler queries.

Table 9.25. Operations of quartz-scheduler plug-in


Job.execute Quartz job execution

Table 9.26. Endpoint Analysis of quartz-scheduler plug-in

Analyzer QuartzSchedulerEndPointAnalyzer



Score Low.

Summary Creates an end point for Quartz triggered jobs.

rabbitmq-client

Support for tracing RabbitMQ queries.

Table 9.27. Operations of rabbitmq-client plug-in


com.rabbitmq.client.Consumer andcom.rabbitmq.client.Channel

Consumer and Channel based message receivers

com.rabbitmq.client.Channel Channel based message publishing

Table 9.28. Endpoint Analysis of rabbitmq-client plug-in

Analyzer AbstractRabbitMQResourceAnalyzer

Score Low.

Summary Creates an end point for messages that are received on an exchange or routing key.

redis

Support for tracing Redis queries.

Table 9.29. Operations of redis plug-in


Jedis Collects operations executed using the Jedis APIs

AbstractRedisCollection Collects operations exucted using the Spring Data abstraction for Redis

servlet

Creates end points for servlets and application lifecycle events such as start and stop. Support forservlet Listeners and Filters operation collection. For tc Runtime, the collection is done by thecom.springsource.insight.collection.tcserver packages.

Table 9.30. Operations of servlet plug-in


javax.servlet.Filter Operation with the filter name and init params.

javax.servlet.ServletContextListener Operations for context initialization and destruction events with context params.

Table 9.31. Endpoint Analysis of servlet plug-in

Analyzer ServletEndPointAnalyzer

Core Operation HttpOperation

Score Low.

Summary Creates an end point for HTTP requests, grouped by the matching servlet, that are otherwise not accounted for by anend point.



socket

Support for tracking opening and closing of sockets

Table 9.32. Operations of socket plug-in


HttpURLConnection Creating a new connection

ServerSocketChannel,ServerSocket

Accepting a connection

SocketChannel Creating a new connection or openning a connection

Socket Creating a connection

spring-core

Basic support for calls into Spring managed beans containing user business logic. Currently only calls into objects annotatedwith @Service or @Repository stereotype annotations are supported. Even if component scanning is not enabled, using theseannotations allows the agent to pick up the operations.

Table 9.33. Operations of spring-core plug-in


@Repository Creates an operation for calls into classes annotated with @Repository

@Service Creates an operation for calls into classes annotated with @Service

spring-integration

Support for Spring Integration.

Table 9.34. Operations of spring-integration plug-in


MessageChannel Sending messages using the MessageChannel APIs

MessageHandler Handling of messages using the MessageChannel APIs

Transformer Tansforming of messages using the Transformer APIs

Table 9.35. Endpoint Analysis of spring-integration plug-in

Analyzer IntegrationEndPointAnalyzer

Score Low.

Summary Creates an end point for operations that were triggered in Spring Integration.

spring-security

Tracing support for Spring Security.

Table 9.36. Operations of spring-security plug-in


AuthenticationManager Calls to the authenticate operation




AuthenticationProvider Calls to the authenticate operation

UserDetailsService Calls to the loadUserByUsername, createUser, updateUser, deleteUser,changePassword and userExists operations

spring-tx

Detects the creation, commit, and rollback of a transaction using Spring's PlatformTransactionManager. Transaction boundariesdefined with @Transactional or with standard Spring config are detected.

Table 9.37. Operations of spring-tx plug-in


PlatformTransactionManager Defines the boundaries of a transaction. Attributes such as the propagation, isolation,timeout and readonly states are collected.

spring-web

Full support for events in the Spring MVC request life cycle. Both annotated @Controller and the legacy Controller interfaceclass hierarchy flavors of MVC are supported.

Table 9.38. Operations of spring-web plug-in


@InitBinder Data binder configuration including target name and type, allowed, required, and disallowed fields.

@ModelAttribute Methods returning objects that are added directly to the model, including the attribute name and value.

@RequestMapping Spring MVC request handlers.

Validator Validation logic.

View View rendering including view name and content type.

ViewResolver View resolution with the view name requested and the matching View object returned.

Controller Legacy Spring MVC Controller interface.

DispatcherServlet Handling of requests by Spring's DispatcherServlet.

Table 9.39. Endpoint Analysis of spring-web plug-in

Analyzer ControllerEndPointAnalyzer

Core Operation ControllerMethodOperation

Score Varies.

Summary Creates an end point for HTTP requests handled by Spring MVC.

tomcat

Provides deep hook into Tomcat and vFabric tc Server internals that are not exposed by the public Servlet API

Table 9.40. Operations of tomcat plug-in


JSP Compiler Operation showing time spent in JSP compilation (typically the first request to a JSP) and the compilerimplementation.



Server-Based Instrumentation

The following instrumentation is provided by default to the tc Runtime; it is not provided as a plug-in.

Table 9.41. Operations of Server-Based Instrumentation


AbstractHttpRequestOperationSupport Creates an HTTP operation for every HTTP request to a web application.Full request and response headers are collected as provided by Tomcat andthe Servlet API. Request parameters are provided if available (user parsingof the request body prevents parameters from being available). Requestheaders are collected before the application is involved, and responseheaders are collected after the application has returned.

ApplicationLifecycleCollectionSupport Creates traces for application life cycle events such as start and stop. Notall web applications have a start event when the server is first starting, if theagent has not fully initialized.

spring insight developer - vmware documentation

Documents