Using Spring Insight

Jon Travis

Scott Andrews

Beverley Talbott

Juliet Shackell

tc Server

1.0.0.M3

Copyright © 2010 VMware Inc. All rights reserved.


Table of Contents

1. Copyright Notice
2. What Is Spring Insight?
2.1. What You Can Do with Spring Insight
2.2. How Spring Insight Works
2.3. Supported Environments
3. Installing and Configuring Spring Insight
3.1. Installing Spring Insight
3.2. Configuring Spring Insight
3.3. Increasing Memory when Using Spring Insight
4. Using Spring Insight
4.1. Before You Begin
4.2. Viewing Recent Activity of Your Application
4.3. Browsing all Applications and Endpoints
4.4. Viewing Spring Insight Data In Google Speed Tracer
4.5. Using Annotations To Customize Insight Data For Your Application
5. Overview of Spring Insight Development
5.1. Prerequisites for Installing the Spring Insight Development Kit
5.2. Installing the Insight Development Kit
6. Using the Spring Insight Plug-ins
6.1. Relationships Among Spring Insight Objects and Plug-ins
6.2. Building and Deploying the Sample Plug-in
6.3. Using the Sample Plug-in
6.4. Building a Plug-in from the Source Code
7. Tutorial: Creating an Insight Plug-in with the Insight Development Kit
8. Core Plug-in Reference
8.1. insight-annotation
8.2. insight-grails
8.3. insight-jdbc
8.4. insight-servlet
8.5. insight-springcore
8.6. insight-springtx
8.7. insight-springweb
8.8. Server-Based Instrumentation
8.9. API Status

1. Copyright Notice

Copyright © 2010 VMware Inc. All rights reserved.

VMware Web Site Legal Notice

2. What Is Spring Insight?

Spring Insight answers the question "What just happened?" It is a SpringSource Web application that gives you real-time visibility into application behavior and performance.

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

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

The sections that follow provide an overview of Spring Insight:

2.1 What You Can Do with Spring Insight

The following topics discuss specific use cases:

Agile Development

Web application developers realize a massive increase in productivity when they can make changes and see the effect immediately. Typically, a developer makes changes to HTML or JSP and reloads the browser to verify that the modified application performs as desired. However, developers often lack a centralized tool that shows how their changes affect:

  • 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 manually into a convenient library. This process saves time and improves maintainability. The downside is relinquishing control, which means 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 effectiveness immediately.

QA Rear View Mirror

Spring Insight gives QA a richer picture of an application's performance, eliminating much of the work required to diagnose problems. 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 your existing 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 Development Kit

Spring Insight uses a plug-in architecture to collect, correlate, and analyze performance metrics from your application and from different pieces of third-party software that work with the application. With the Spring Insight Development Kit, you can create plug-ins tailored to the needs of your application. Using the Development Kit, you can extend Insight functionality to collect trace details such as Hibernate flush times and JSP render times; render custom HTML for an operation detail frame; and analyze traces to produce new types of EndPoints, such as a JMS message queue.

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

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 how long the browser takes to render, transform CSS, show images, and so on. SpringSource and Google partnered to integrate Spring Insight data into SpeedTracer, thereby tying browser performance to backend performance with a robust client-server application performance tool. If your web application uses Ajax and other rich open web technologies, we recommend you try SpeedTracer with Spring Insight.

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

2.2 How Spring Insight Works

Spring Insight's lean framework keeps developer requirements to a minimum. Developers can deploy a native application to a Spring Insight-enabled tc Runtime instance and immediately see diagnostics. There is no database to set up, no instrumentation to perform.

Spring Insight captures application events known as traces. A trace represents a thread of execution. It is usually started by an HTTP request but can also be started by a background job. A trace contains operations. Each operation represents a significant point 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 is not performing.

Spring Insight uses AspectJ to snoop on operations in target web applications. Target web applications are loaded with a special classloader that dynamically instruments web applications at runtime. Spring Insight currently keeps its data in memory. It does not use an external database or write any data to disk. It uses sophisticated algorithms to keep the memory footprint low. Spring Insight-enabled servers require more memory (-Xmx) than a standard server.

2.3 Supported Environments

Spring Insight runs in environments with a Java 5 or Java 6 JVM. Spring recommends Java 6 for the best experience and will alert you to any differences that arise between Java 5 and Java 6. Most portability issues surface when you change JVMs and/or when you change browsers. For this preview release Spring has tested the following environments:

  • Linux 64 bit, Sun Hotspot 1.6 JVM

  • Windows 32 bit, Sun Hotspot 1.6 JVM

These environments should work well, but Spring welcomes feedback from anyone who tries out the preview on other configurations.

3. Installing and Configuring Spring Insight

In this chapter, you install and configure Spring Insight.

3.1 Installing Spring Insight

There are two ways to install Spring Insight:

  • Install the Developer Edition of tc Server and start using the spring-insight-instance that is already configured with Spring Insight. You can also create a new tc Runtime instance by specifying this instance as a template.

    For details, see Installing Developer Edition.

  • Download Spring Insight as a standalone template ( springsource-insight-tc-server-developer-edition-version.zip ) and install it into any existing 2.X tc Server installation, as described in the rest of this section. The standalone bundle always includes the latest version of Spring Insight.

The bundle installs as a tc Runtime template. You can install many versions of Spring Insight in tc Server this way; all the versions will reside under the CATALINA_BASE/templates directory of your tc Server installation.. You then choose which Insight version you want to apply when you create a tc Runtime instance with the tcruntime-instance.sh script.

[Note]Note

The following instructions are written for Unix users; Windows users should change forward-slashes to back-slashes and use *.bat command scripts rather than *.sh.

To install the Spring Insight template bundle into an existing tc Server installation and create a new tc Runtime instance that uses the template :

  1. From the SpringSource tc Server Developer Edition with Spring Insight Web site, download the springsource-insight-tc-server-developer-edition-version.zip file.

  2. Open a terminal window and change to the templates directory of the tc Server home directory. For example, if you installed the Standard Edition of tc Server in /home/tcserver:

    prompt$ cd /home/tcserver/springsource-tc-server-standard/templates
  3. Unzip the Spring Insight bundle into this directory. For example:

    prompt$ unzip /path/to/springsource-insight-tc-server-developer-edition-1.0.0-RELEASE.zip

    In this example, the version of Spring Insight is 1.0.0-RELEASE; you might have downloaded a different version.

    The unzip command creates a directory under templates called springsource-insight-tc-server-developer-edition-version.

  4. Change to the main tc Server installation directory:

    prompt$ cd /home/tcserver/springsource-tc-server-standard
  5. Create a tc Runtime instance that uses the Spring Insight template you just untarred. For example:

    prompt$ ./tcruntime-instance.sh -c -s insightPlay -t springsource-insight-tc-server-developer-1.0.0-RELEASE

    In the preceding example, the script creates a tc Runtime instance called insightPlay using the template springsource-insight-tc-server-developer-1.0.0-RELEASE, which automatically configures Spring Insight for the instance.

  6. Start the instance using the tcruntime-ctl.sh script:

    prompt$ ./tcruntime-ctl.sh insightPlay start
  7. Access the Spring Insight dashboard in your browser:

    http://host:8080/insight

    where host refers to the computer on which you are running the tc Runtime instance. If on the same computer as your browser, you can use localhost:

    http://localhost:8080/insight

3.2 Configuring Spring Insight

You configure Spring Insight by editing the spring-insight.yml file, located in the insight directory of the tc Runtime instance. For example, if you installed the Developer Edition of tc Server in /home/tcserver and are using the prepackaged spring-insight-instance, then its configuration file is /home/tcserver/springsource-tc-server-developer/spring-insight-instance/insight/spring-insight.yml.

The file is written in YAML, which is an intuitive means of marking up complex datatypes.

The general format for setting a property is property: value , such as minTraceDuration: 0.

The following sample spring-insight.yml displays the default configuration file of a newly-created tc Runtime instance. Use it as a guide to set your own property values:

#
# The Spring Insight(tm) configuration file (in YAML)
#

# Number of wall-clock milliseconds that a trace must consume
# in order to be added to the trace repository.
minTraceDuration: 0

# Maximum # of traces which will be stored in memory
maxInMemoryTraces: 2000

# How many traces will be purged when the maximum limit is reached?
tracePurgeBatch: 200

# Paths to exclude from tracing (in ant path format)
excludeTraceByPath:
    - /**/*.png
    - /**/*.gif
    - /**/*.jpg
    - /**/*.css
    - /**/*.js

# The number of seconds a request must complete in for
# it to be deemed 'satisfactory'.  This threshold is used
# to calculate the color of the health bar for endpoint
# response time.
# The formula for calculating the health bar closely
# corresponds to the Apdex formula.
# See apdex.org for more details.
healthyResponseTime: 0.2

The table describes the properties you can set in the spring-insight.yml file.

Table 3.1. Properties of the spring-insight.yml File

Property and Default SettingDescription
minTraceDuration: 0Minimum required duration of a trace should take (in milliseconds) for it to be captured by the system. This setting prevents extremely short requests from being processed and cluttering your view.
maxInMemoryTraces: 2000Defines how many traces are kept in memory. Once this limit is reached, the oldest trace is discarded. The Spring Insight application does its work in memory and does not require a database.
tracePurgeBatch: 200Defines how many traces are purged at once, once maxInMemoryTraces has been reached. By purging many traces simultaneously, Spring Insight frees memory more efficiently.
excludeTraceByPath:Provides a list of patterns that are matched against requests. When a trace matches a path in this list, the trace is discarded. This setting lets you ignore requests to static content such as .css or .js files.

For example:

excludeTraceByPath:
- /**/*.jpg
- /**/*.css
- /**/*.js

The -prefix is important. It is the YAML identifier showing that the items are in a list.

healthyResponseTime: 0.2Divided into categories: satisfying, tolerated, and frustrating. This property defines the maximum response time, in seconds, that can be satisfying. For example, if healthyResponseTime = 0.3 then a response in 100ms is satisfying. This setting gauges the colors of the indicators for response time (excellent, good, fair, poor, unacceptable).

3.3 Increasing Memory when Using Spring Insight

When you use Spring Insight to view the performance of your application, you might need to increase the memory of the tc Runtime instance to more than what your application requires on its own. In particular, you might need to increase the max heap or max PermGen size (two JVM options), or both.

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

4. Using Spring Insight

Spring Insight enables you to see what your application is doing under the glossy exterior of @annotated APIs or proxied objects. The most popular frameworks of today hide tremendous power behind their friendly facades. For example, a simple session.save(book) that uses Hibernate can execute hundreds of JDBC calls, depending on your mapping. Spring Insight brings 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:

4.1 Before You Begin

Before you start using Spring Insight:

  • Install Spring Insight, create a tc Runtime instance by using the Spring Insight template from the standalone Insight installation, or use the instance that is prepackaged in the Developer Edition of tc Server. See Installing and Configuring Spring Insight.

  • Start the tc Runtime instance, deploy your Web application to the instance, configure all of its resources (such as any required JDBC 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 you are using the Developer Edition of tc Server and have started the included spring-insight-instance instance. Further assume that the CATALINA_BASE of this instance is /home/tcserver/springsource-tc-server-developer/spring-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/springsource-tc-server-developer/spring-insight-instance/webapps

If you are using the Developer Edition of tc Server, you can also use Tomcat Manager to deploy your application. See Deploying Applications to tc Runtime Instances.

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

4.2 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 applications currently deployed, and then how to drill down to the details of particular application event.

  1. 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 JDBC queries, each one is shown in the Spring Insight dashboard along with a timeline of recent requests.

  2. Browse to the Spring Insight dashboard:

    http://host:port/insight

    where:

    • host is the computer on which the tc Runtime instance is running. If it is the same computer as your browser, you can use localhost.

    • port is the port number to which the tc Runtime instance listens. By default, this port is 8080.

    For example:

    http://localhost:8080/insight

    The browser invokes the main Spring Insight dashboard on the Recent Activity screen and displays recent traces from your application. A trace is a breakdown of the activity of a request. The Recent Activity screen answers the question What just happened?

  3. 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 once is useful when you deploy many Web applications and are interested in activity across the entire set. Viewing a single application 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 by bars in the chart. Each bar represents all requests that occurred within a time slice, as measured by the chart. The full time range 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 a trace is captured by Spring Insight, it shows on the graph as a bar on the right-hand side. As time passes, bars move left until they fall out of the time range. Click on bars to drill deeper.

  4. 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 then details about a specific trace. Insight automatically shows details about the first trace in the Trace Details panel. If you click on a different trace, 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?), Start (when did the trace start?), Label (what was the request?), or Error (did the request result in an error?)

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

    Operations are the fundamental building blocks of traces. An operation can represent a Web request, a transaction, a call to an 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 the operation executed towards 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.

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

    Click on the Endpoint to navigate to the Trace's corresponding Endpoint in the Browse Resources tab. This button is useful when you want to see how similar requests (requests to the same Endpoint) have performed over time.

  6. Using the buttons by the Application Selector, control the information you see in the Spring Insight dashboard by:

    • Changing the global time range. The time range specifies how many minutes worth of data shows up in the Trace History graph.

    • Playing or pausing the graph movement. To stop the graph from automatically moving as new traces are recorded, click the control to Pause. If the graph is in Play mode, the word Live appears under the right hand side of the graph.

    • Refreshing the trace history by reloading all data within the Trace History graph or clearing the trace history, which removes all stored data. This function removes all captured response times, traces, and health data.

4.3 Browsing all Applications and Endpoints

The following procedure describes how to browse through all the applications deployed to the tc Runtime instance, as well as their associated Endpoint, and view their health, throughput trends, response time trends, and response time histograms.

Although the Browse Resources screen shows information for all types of applications, it is most effective (and shows the most detail) for Spring, Grails, and Roo applications.

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

    The Resources panel on the left displays a resource tree of all applications that have reported Traces; you can expand each application to see its list of Endpoints. The health of the application is displayed next to its name and represents the worst-performing Endpoint within the Application. Each Endpoint also displays its health, which is described later on in this procedure.

    Spring Insight loads the resource tree when it initially loads the page. If you subsequently deploy a new application or Insight detects new endpoints, Insight does not automatically add these resources into the resource tree; rather, you must explicitly click the Refresh button to the right of the Resources panel. This is also true for the health indications for application and Endpoints. Clicking the refresh button does not affect the currently loaded resource, it only fetches new data for the resource tree. Clicking refresh in the browser window has a similar effect, although in this case Insight reloads the resource details as well.

    The Applications panel on the right lists the same applications in tabular form, along with additional information about each application:

    • The Throughput Trend column shows a simple sparkline that graphically describes the recent mean throughput time of the application.
    • The Throughput column shows how many Traces per Minute (TPM) were executed over the current time window.
    • The Errors column shows what percentage of Traces resulted in an Error (HTTP status 500 to 600).

    The tabular view of all applications is useful to see which applications have been busiest and to compare their relative health. Click the column headers to sort the information based on the column.

  2. Click on an application in the left Resources panel. The right panel displays similar information about the application as in the previous table, but this time the Throughput Trend graph is much more detailed than the previous sparkline. The End Point panel displays the Endpoints associated with the application.

    Each row in the Endpoints table represents an Endpoint, which is a receptor for requests. The universe of all possible HTTP URLs is unlimited. However, Spring Insight can group requests together based on the controller with which the requests are associated. For each endpoint, 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 and green is more healthy. See Configuring Spring Insight for details on setting the tolerable threshold in the spring-insight.ytml file with the healthyResponseTime property.
    • Endpoint: Displays the name of the Endpoint.
    • Throughput Trend: Displays a simple sparkline that shows the recent mean throughput time of the Endpoint.
    • Throughput: Shows how many Traces per Minute (TPM) were executed over the current time window.
    • Errors: Shows what percentage of Traces resulted in an Error (HTTP status 500 to 600).
    • Response Time: Displays the 99% response time over the given time range. This value is most useful to determine the worst-case request. A value of 115 ms indicates that 99% of the requests occurred within 115 milliseconds. The response time of an HTTP request is determined by the full time it takes the container to ship the response to the client, and not just the time spent in a controller.
  3. Click on an particular Endpoint, either in the left Resources panel or in the right End Points table for a particular application:

    Spring Insight displays the following detailed information about the Endpoint:

    • The Response Time Trend chart shows the mean response time of the endpoint over the time range. Click on markers (points) in the chart to view Trace data that occurred during that time range.
    • The Throughput Trend graph displays more details about the recent mean throughput time of the Endpoint. Click on markers (points) in the chart to view Trace data that occurred during that time range.
    • The Response Time Histogram is an interactive graph that shows how many invocations occurred within a given time period. The Y-axis represents the response time of an invocation. The X-axis represents the number of invocations. Using the histogram is an easy way to identify outliers in your data. The longest-running invocations are always at the top of the histogram. If extreme outliers exist, they are indicated by red bars.
    • The End Point Health is determined by the Response Time for requests made over the given time interval. The response times are broken down into various Health Zones (such as frustrated, tolerated or satisfied. Click on a particular Health 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 Representative Traces 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 drill into the shortest or fastest running traces to see what made them different.

4.4 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 measures how 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 into what the application itself is doing in the back end. For that, it needs Insight. The two products are now integrated so that you can now see Trace data interleaved with Speed Tracer's browser timings.

To see 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 Started with 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.

  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 grey pillbox, with tooltip Includes timing data from the server; these resources include Insight data along with the standard Speed Tracer data. See the graphic in the next step.

  6. Expand the resource to view the Insight data, listed under the Server Trace section. This section includes a brief summary 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, Endpoint or Application links, which will jump into Insight at the appropriate location so you can further drill down.

4.5 Using Annotations To Customize Insight Data For Your Application

Spring Insight is implemented as a collection of plug-ins, each of which exposes specific types of method calls. Spring Insight includes 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 Spring Framework @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 by Spring 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 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 add Spring Insight-specific annotations to the Java source of your application to inform Insight that it should trace and expose one or more particular methods in your application. This is a quick and easy way to customize Spring Insight for your specific environment. Currently, Spring Insight supports the following annotations:

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

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

@InsightOperation Reference

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

Table 4.1. Attributes of @InsightOperation

AttributeDescription
labelSpecifies what Insight displays in the Trace frame stack for this method. A frame is the row in the Trace 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.

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

@InsightEndPoint Reference

Similar to @InsightOperation in that this annotation specifies that Insight should display the annotated method and its arguments in the Insight Traces. Additionally, the annotated method is declared as an EndPoint, which means that it shows up in the Browse Resource list as an EndPpoint. Use the optional label and comment attributes to customize the display, as described in the following table.

Table 4.2. Attributes of @InsightEndPoint

AttributeDescription
labelSpecifies what Insight displays in the Trace frame stack for this method. A frame is the row in the Trace 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.

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

Example of Using the Insight Annotations

The following code snippet shows how to use the @InsightOperation and @InsightEndPoint annotations in a simple Hello 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 and com.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 Insight after the annotated 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 to package this JAR file in your application. However, you do need this JAR file at compile time so you can successfully compile the Java classes in your application that use the 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 make the JAR file available to your project:

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

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

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

If you use build system other than Maven, you can download the annotation JAR file from the tc Server Developer Edition With Spring Insight Web site and then add the file to your compile-time CLASSPATH variable.

5. Overview of Spring Insight Development

Spring Insight uses a plug-in architecture to collect, correlate, and analyze performance metrics from your application and from different 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 Insight Development Kit to create plug-ins tailored to the needs of your application. The Development Kit provides a copy of the source code for all plug-ins shipped with Spring Insight and includes a sample plug-in to use as a starting point for creating your own plug-in.

Use the Development Kit to create plug-ins that extend 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 EndPoints, such as a JMS message queue.

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

  • SQL statement capturing (insight-jdbc plug-in)
  • MVC Controller calls (insight-springweb plug-in)
  • Grails controller calls (insight-grails plug-in)

Note: The Insight Development 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 SpringSource EULA. Plug-in authors are free to license their plug-ins as they see fit.

5.1 Prerequisites for Installing the Spring Insight Development Kit

Before you install the Spring Insight Development Kit:

  • Install the Developer Edition of tc Server 2.0 from the tc Server product page. See Getting Started with tc Server.

  • Optionally install the Spring Insight template from the tc Server Developer Edition with Spring Insight page. You use this template to create a new tc Runtime instance that is configured with Spring Insight.

    This step is optional because the Developer Edition of tc Server already contains a pre-built tc Runtime instance that is configured with Spring Insight; you can immediately start using this instance after you install tc Server. However, the standalone template always contains the latest version of Insight, which might be a more recent version than the one that is packaged in tc Server (Developer Edition). See Installing and Configuring Spring Insight.

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

For more API reference information about Insight, see Insight core classes.

5.2 Installing the Insight Development Kit

  1. Download the Insight Development Kit from the tc Server Developer Edition with Spring Insight page. The name of the bundle is springsource-insight-developer-kit-1.0.X.X.zip, where X.X refers to a specific version, such as M3.SR02.

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

    $ mkdir ~/dev/insight-dev
    $ cd ~/dev/insight-dev
    $ unzip /path/to/springsource-insight-developer-kit-1.0.X.X.zip

    This creates a sub-directory called springsource-insight-developer-kit-1.0.X.X.

The Development Kit installation consists of the following files:

samples/payme-insight-plugin
samples/payme-webapp
insight-plugins/annotation
insight-plugins/grails
insight-plugins/gwt
insight-plugins/jdbc
insight-plugins/servlet
...
  • payme-insight-plugin is a sample plug-in for 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 Insight plug-ins that ship with the project; for the full list and a description of each of these plug-ins, see Core Plug-in Reference . The code is also a good reference for the variety of tasks that plug-ins can accomplish.

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 (Operaton.java) that plug-ins can implement to store information about the captured work being done. An Operation implementaton is an item of work, for example, a socket opening, a cache miss, a method call, or a JDBC SELECT. Operations are defined by plug-ins and contain all the information needed to capture the work being done.

    [Note]Note
    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, but this is not always necessary. A frame can be created for any logical event that a plug-in dictates. A frame holds information about when an event occurred and about the frame's nested relationship to other frames. The meat of the frame lies within the Operation.

  • Trace: A recording of a single thread of execution for an application. A trace can represent a single web request (and all the work it did), or it could represent a JMS message listener's processing times. A trace contains a nested tree of frames, which contain 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 EndPoint. EndPoints for a given trace are identified by EndPointAnalyzers that post-process a trace after it is collected. All EndPointAnalyzers known to Insight process each trace. The analyzer with the highest score -- that is, the analyzer that the plug-in determines has most closely identified the EndPoint -- defines the trace as belonging to a particular EndPoint.

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

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

  • Spring Insight: The entirety of Operation collection, EndPoint analysis, trace storage, and the user interface. For brevity, the term Insight is used as well.

6.1 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 an associated Operation.

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

6.2 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 Insight Development Kit. In the procedure, it is assumed that:

  • You unzipped the Insight Development Kit into the dev/insight-dev sub-directory of your home directory (in other words, ~/dev/insight-dev.)
  • You installed the Developer Edition of tc Server in /home/s2 and you are using the pre-packaged spring-insight-instance instance to run Insight and deploy applications.
  • You have installed Maven on your computer. See Maven Users Center for information about downloading Maven and getting started.
  1. Build the sample plug-in from the Insight Development Kit using Maven:

    $ cd ~/dev/insight-dev/springsource-insight-developer-kit-1.0.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 Insight-enabled tc Runtime instance spring-insight-instance:

    $ cp target/payme-insight-plugin-version.jar \
         /home/s2/springsource-tc-server-developer/spring-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/springsource-tc-server-developer/spring-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/springsource-tc-server-developer
    $ ./tcruntime-ctl.sh spring-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 Insight will track.

    Back on the 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 following indicates that the plug-in is working correctly.

6.3 Using the Sample Plug-in

The sample plug-in, payme-insight-plugin, makes it easy for a developer to add new instrumentation for a specific technology such as Hibernate or Struts. The sample does not provide an example for creating an EndPoint, although other plug-ins within the Development 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 all calls to .setBalance(int) on any object. This capability is useful when you have many different Web applications, with different 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 Insight, with no need to change code in any Web application.

Sample Plug-in Files

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

src/main/java/org/myorg/insight/myplugin/CashMoneyOperation.java
src/main/java/org/myorg/insight/myplugin/CashMoneyOperationCollectionAspect.aj
src/main/resources/META-INF/insight-plugin-myplugin.xml
src/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 the CashMoneyOperation with this data.

It is the plug-in's own implementation of Operation that holds information captured by the aspect. When the aspect intercepts a 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, see Collecting 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 with the 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's specific 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 custom views for operations. See EndPointAnalyzer.

cash_money_operation.ftl

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

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

Collecting Runtime Data

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 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 own Operation subclasses that can be instantiated by the aspects. These plug-in operations are then moved through the Insight 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 View with which to render their Operation into HTML. FreeMarker is the recommended view technology. You can use other view technology if it implements the Spring View interface. However, the libraries needed to render the view must already be available. JSP is not an option because the files live outside the servlet environment.

When rendering a trace in the UI, the Insight dashboard examines the OperationType of each Operation in the trace. It uses this type to locate an associated view. If a plug-in defines the view, the Insight dashboard renders it and includes 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 the generic 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 the FreeMarker 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>

EndPointAnalyzer

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

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

All registered EndPointAnalyzers can look at each trace as it is created and determine which EndPoints it has. Because many plug-ins run per trace and each one can produce its own EndPointAnalysis, only a single EndPointAnalysis will represent the trace. 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 Insight by adding it to the plug-in's Spring context file (insight-plugin-myplugin.xml).

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

6.4 Building a Plug-in from the Source Code

The Insight Development Kit contains the source code for Insight plug-ins, which is licensed under the Apache License 2.0. Source code for the Insight dependencies (core packages) is available as source jars, through Eclipse and Maven. Eclipse automatically makes these jars available after you import the sample plug-in.

To download the source jars directly, visit the tc Server Developer Edition with Spring Insight homepage for download links.

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

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

This tutorial describes how to create a Spring Insight plug-in called insight-plugin-tiles using the Insight Development Kit. The purpose of the plug-in is to capture the amount of time that Apache Tiles spends rendering content. Apache Tiles is a templating 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#render method. 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 is spent 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 download and install everything you need. If, however, you have already installed one or more of these products, modify the tutorial accordingly. The full list of products or bundles required for this tutorial is as follows:

  • tc Server Developer Edition, version 2.0
  • Spring Insight Development Kit, vesion 1.0
  • SpringSource Tool Suite, version 2.3

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

  1. Create a workspace. For example, to create a workspace dev/insight 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, and create will be contained here.

  2. Download tc Server Developer Edition and the Insight Development Kit from the tc Server Developer Edition with Spring Insight Web site.

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

    $ ls
    springsource-tc-server-developer-2.0.X.X.zip
    springsource-insight-developer-kit-1.0.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 springsource-tc-server-developer-2.0.X.X.zip

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

  4. Start the built-in spring-insight-instance:

    $ cd springsource-tc-server-developer
    $ ./tcruntime-ctl.sh spring-insight-instance start
  5. Verify that Insight is working.

    Browse to http://localhost:8080/insight to verify Insight started correctly. If so, you should see a page like the following:

  6. Unpack the Insight Development Kit:

    $ cd ~/dev/insight-dev
    $ unzip springsource-insight-developer-kit-1.0.X.X.zip

    Replace X.X with the actual version numbers. This creates a child directory called springsource-insight-developer-kit-1.0.X.X, where X.X refer to a specific version.

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

    Use the sample plug-in from the Insight Development Kit to create a new plug-in, called insight-plugin-tiles, in your insight-dev directory:

    $ cd ~/dev/insight-dev
    $ cp -Rp springsource-insight-developer-kit-1.0.X.X/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, remove the ones that come with the payme-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 version from 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:

    1. Select File -> New -> Java Project .
    2. Select Create Project from Existing Source.
    3. Enter ~/dev/insight-dev/insight-plugin-tiles in the Directory field.
    4. Click Finish.

  10. Update the Maven pom.xml file.

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

    Edit pom.xml, 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>

  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 file that 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 TilesRenderOperation class.

    This class is an implementation of Operation that will hold the data you collect from the TilesContainer#render method. The class basically holds the tile's definitionName.

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

    package org.myorg.insight.tiles;
    
    import com.springsource.insight.intercept.operation.BasicOperation;
    import com.springsource.insight.intercept.operation.OperationType;
    import com.springsource.insight.intercept.operation.SourceCodeLocation;
    
    public class TilesRenderOperation
        extends BasicOperation
    {
        public static final String NAME = "tiles_render_operation";
        public static final OperationType TYPE = OperationType.valueOf(NAME);
        private String definitionName;
        private String label;
    
        public TilesRenderOperation(SourceCodeLocation scl, String definitionName) {
            super(scl);
            this.definitionName = definitionName;
            this.label = "Tiles Render: " + definitionName;
        }
    
        public String getLabel() {
            return label;
        }
    
        public OperationType getType() {
            return TYPE;
        }
    
        public String getDefinitionName() {
            return definitionName;
        }
    }

  13. Create the TilesRenderOperationCollectionAspect class.

    This aspect will be woven into the target application at runtime by AspectJ. In this aspect you specify the method that you want to capture (TilesContainer.render()) as the collectionPoint pointcut. The aspect is also responsible for creating 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;
    
    public aspect TilesRenderOperationCollectionAspect
        extends AbstractOperationCollectionAspect
    {
        public pointcut collectionPoint()
            : execution(void TilesContainer.render(String, Object...));
    
        @Override
        protected Operation createOperation(JoinPoint jp) {
            Object[] args = jp.getArgs();
            String definitionName = (String)args[0];
            return new TilesRenderOperation(getSourceCodeLocation(jp), definitionName);
        }
    }
  14. Create the DummyTilesContainer class for testing.

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

    When the Target Application is really running (becaus it is deployed to a running tc Runtime instance, and so on), the target application will occasionally make calls to the TilesContainer.render() methods. During testing, you create a 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:

    package org.myorg.insight.tiles;
    
    import java.io.IOException;
    import java.io.Writer;
    import java.util.Map;
    
    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;
        }
    }
  15. 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 that TilesRenderOperation is successfully captured by the TilesRenderOperationCollectionAspect.

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

    package org.myorg.insight.tiles;
    
    import static org.junit.Assert.assertEquals;
    
    import org.junit.Test;
    
    import com.springsource.insight.collection.OperationCollectionAspectSupport;
    import com.springsource.insight.collection.OperationCollectionAspectTestSupport;
    
    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
            TilesRenderOperation op = (TilesRenderOperation) getLastEntered(TilesRenderOperation.class);
    
            // Step 3:  Validate
            assertEquals("myDefinition", op.getDefinitionName());
            assertEquals("Tiles Render: myDefinition", op.getLabel());
            assertEquals(DummyTilesContainer.class.getName(), op.getSourceCodeLocation().getClassName());
            assertEquals("render", op.getSourceCodeLocation().getMethodName());
        }
    
        public OperationCollectionAspectSupport getAspect() {
            return TilesRenderOperationCollectionAspect.aspectOf();
        }
    }
  16. 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 on TilesRenderOperationCollectionAspectTest.java and select Run-As -> JUnit Test .

  17. Copy the insight-plugin-tiles plug-in into the tc Runtime 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 by copying the generated plug-in JAR file into the insight/collection-plugins directory of your spring-insight-instance instance:

    $ cd ~/dev/insight-dev/insight-plugin-tiles
    $ mvn clean package
    $ cp target/insight-plugin-tiles-0.0.1.SNAPSHOT.jar ../springsource-tc-server-developer/spring-insight-instance/insight/collection-plugins
  18. Start (or restart if it is already running) the tc Runtime instance and view the new TilesRenderOperation. For example, to restart:

    $ cd ../springsource-tc-server-developer
    $ ./tcruntime-ctl.sh spring-insight-instance restart

    Navigate to http://localhost:8080/insight to see the insight-plugin-tiles plug-in in action.

    Fortunately, the Insight Dashboard uses Tiles to display its UI. Because the insight-plugin-tiles plug-in will also collect data for the Insight Dashboard, you can see the effect immediately. 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 to render different tiles when generating the result of a request to http://localhost:8080/insight/endpoints/insight.

    The drilldown into the "Tiles Render: noscript" operation shows details about the TilesRenderOperation. Notice the 'Exception: null' and 'Return Value: void" properties. Those (along with the Tiles Render Operation Operation doublespeak) are generated automatically by examining the TilesRenderOperation. To customize the UI that is rendered for the TilesRenderOperation, you must add it to the plug-in.

  19. Add the tiles_render_operation.ftl view.

    Insight plug-ins can use FreeMarker to customize the view. Create the FreeMarker template

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

    <h2>Tiles Render Operation</h2>
    
    <table class="dl">
        <tr>
            <td>definitionName</td>
            <td>${operation.definitionName?html}</td>
        </tr>
    </table>

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

    "${operation.definitionName?html}"

    calls the method TilesRenderOperation.getDefinitionName() and HTML-encodes the result. You can access all properties from your TilesRenderOperation if they have a getter (getDefintionName()).

  20. Register the view with the plug-in.

    Insight locates views for Operations by looking for insight-plugin-*.xml Spring Application Context descriptor files. 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:

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
    
        <bean id="operation.tiles_render_operation" class="org.springframework.web.servlet.view.freemarker.FreeMarkerView">
            <property name="url" value="org/myorg/insight/tiles/tiles_render_operation.ftl"/>
        </bean>
    </beans>

    This file points Insight at the tiles_render_operation.ftl view when it attempts to render a TilesRenderOperation. The TilesRenderOperation.getType() method returns an OperationType that Insight 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 the tiles_render_operation.ftl based on it. You will create a TilesRenderOperationViewTest to verify that this rendering works.

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

    Create src/test/java/TilesRenderOperationViewTest.java:

    package org.myorg.insight.tiles;
    
    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 start it:

    $ mvn clean package
    $ cp target/insight-plugin-tiles-0.0.1.SNAPSHOT.jar ../springsource-tc-server-tomcat-std-2.0.0.RELEASE/insightPlay/webapps-lib
    $ cd ../springsource-tc-server-tomcat-std-2.0.0.RELEASE
    $ ./tcruntime-ctl.sh insightPlay run

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

8. Core Plug-in Reference

Most metrics collected by Spring Insight 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.

8.1 insight-annotation

Use of the @Insight* annotations are optional. They make it easy for end users to define custom operation frames and end points without needing to create a plug-in. Because end user code modification is required to use the annotations, they are an option 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 Your Application.

Table 8.1. Operations of insight-annotation

Collection PointSummaryAvailability
@InsightOperationAny methods annotated with @InsightOperation will create an operation, including: basic source code location, method parameters and the return value.1.0.0.M2
@InsightEndPointSimilar to @InsightOperation; also indicates the operation should be treated as an end point.1.0.0.M2

Table 8.2. EndPoint Analysis of insight-annotation

AnalyzerCore OperationScoreSummaryAvailability
AnnotatedMethodEndPointAnalyzerAnnotatedMethodOperationHigh by default, customizable in annotation.Finds operations created from @InsightEndPoint, thus creating the end point.1.0.0.M2

8.2 insight-grails

Grails-specific support for controller methods.

Table 8.3. Operations of insight-grails

Collection PointSummaryAvailability
Grails Controller MethodMethod on a Grails Controller to which the request is mapped.1.0.0.M2

Table 8.4. EndPoint Analysis of insight-grails

AnalyzerCore OperationScoreSummaryAvailability
GrailsControllerMethodEndPointAnalyzerGrailsControllerMethodOperationVaries.Creates an end point for HTTP requests handled by Grails.1.0.0.M2

8.3 insight-jdbc

Low level support for tracing raw SQL queries. Currently, no ORM tools are directly supported.

Table 8.5. Operations of insight-jdbc

Collection PointSummaryAvailability
java.sql.StatementOperation with the raw SQL statement.1.0.0.M1
java.sql.PreparedStatementOperation with the raw SQL statement and parameters.1.0.0.M1

8.4 insight-servlet

Creates end points for servlets and application lifecycle events such as start and stop. No advice is contained in this plug-in as the implementation details are server specific. For tc Runtime, the collection is done by the com.springsource.insight.collection.tcserver packages.

Table 8.6. EndPoint Analysis of insight-servlet

AnalyzerCore OperationScoreSummaryAvailability
ServletEndPointAnalyzerHttpOperationLow.Creates an end point for HTTP requests, grouped by the matching servlet, that are otherwise not accounted for by an end point.1.0.0.M1

8.5 insight-springcore

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

Table 8.7. Operations of insight-springcore

Collection PointSummaryAvailability
@RepositoryCreates an operation for calls into classes annotated with @Repository1.0.0.M1
@ServiceCreates an operation for calls into classes annotated with @Service1.0.0.M1

8.6 insight-springtx

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

Table 8.8. Operations of insight-springtx

Collection PointSummaryAvailability
PlatformTransactionManagerDefines the boundaries of a transaction. Attributes such as the propagation, isolation, timeout and readonly states are collected.1.0.0.M1

8.7 insight-springweb

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

Table 8.9. Operations of insight-springweb

Collection PointSummaryAvailability
@InitBinderData binder configuration including target name and type, allowed, required, and disallowed fields.1.0.0.M1
@ModelAttributeMethods returning objects that are added directly to the model, including the attribute name and value.1.0.0.M1
@RequestMappingSpring MVC request handlers.1.0.0.M1
ValidatorValidation logic.1.0.0.M1
ViewView rendering including view name and content type.1.0.0.M1
ViewResolverView resolution with the view name requested and the matching View object returned.1.0.0.M1
ControllerLegacy Spring MVC Controller interface.1.0.0.M2
DispatcherServletHandling of requests by Spring's DispatcherServlet.1.0.0.M1

Table 8.10. EndPoint Analysis of insight-springweb

AnalyzerCore OperationScoreSummaryAvailability
ControllerEndPointAnalyzerControllerMethodOperationVaries.Creates an end point for HTTP requests handled by Spring MVC.1.0.0.M1

8.8 Server-Based Instrumentation

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

Table 8.11. Operations of Server-Based Instrumentation

Collection PointSummaryAvailability
HttpRequestMetricCollectionValveCreates an HTTP operation for every HTTP request to a web application. Full request and response headers are collected as provided by Tomcat and the Servlet API. Request parameters are provided if available (user parsing of the request body prevents parameters from being available). Request headers are collected before the application is involved, and response headers are collected after the application has returned.1.0.0.M1
ApplicationLifecycleCollectionListenerCreates traces for application life cycle events such as start and stop. Not all web applications have a start event when the server is first starting, if Spring Insight has not fully initialized.1.0.0.M2

8.9 API Status

Spring Insight is a young, rapidly evolving project. Although we try to keep APIs compatible, we cannot guarantee that APIs will be compatible between milestones.