Using Spring Insight Developer

vFabric tc Server

Spring Insight Developer 1.5


Table of Contents

1. Copyright Notice
2. What Is Spring Insight Developer?
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 Developer
3.1. Installing Spring Insight Developer
3.2. Configuring Spring Insight
3.3. Increasing Memory when Using Spring Insight
4. Using Spring Insight
4.1. Before You Begin
4.2. Invoking Spring Insight in your Browser
4.3. Browsing all Applications and End Points
4.4. Viewing Recent Activity of Your Application
4.5. Filtering Trace Details
4.6. Exporting and Importing Traces
4.7. Customizing End Point Thresholds
4.8. Viewing Spring Insight Data In Google Speed Tracer
4.9. Using Annotations To Customize Spring Insight Data For Your Application
5. Overview of Spring Insight Development
5.1. Prerequisites for Installing the Spring Insight Developer Kit
5.2. Installing the Spring Insight Developer 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. annotation
8.2. grails
8.3. hibernate
8.4. jdbc
8.5. method-endpoint
8.6. servlet
8.7. spring-core
8.8. spring-tx
8.9. spring-web
8.10. tomcat
8.11. Server-Based Instrumentation

1. Copyright Notice

Copyright © 2011 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one 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/or other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies.

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-time visibility 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 detailed information to developers.

Stress testing an application typically tells you which URL areas are slow. By combining Spring Insight Developer 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 following sections 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 renders the web page 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 Developer 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 and libraries that interact with the application. You can create plug-ins that are tailored to the needs of your application with the Spring Insight Developer Kit. Using the Developer Kit, you can extend Spring 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 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 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. VMware 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 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 may not be performing as well as it could.

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

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

2.3 Supported Environments

Spring Insight runs in environments with a Java 6 JVM. Most portability issues surface when you change JVMs and/or when you change browsers.

Spring Insight supports the same configurations as tc Runtime. See Supported Configurations: tc Runtime for the complete list.

3. Installing and Configuring Spring Insight Developer

In this chapter, you install and configure Spring Insight.

3.1 Installing Spring Insight Developer

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

Follow these steps to install Spring Insight Developer edition:

  1. From the VMware Download Center, download tc Server Developer Edition, which includes Spring Insight Developer.

    • tc Server Developer Edition, for example, vfabric-tc-server-developer-2.5.X.X.zip

  2. Open a terminal (Unix) or Command Prompt (Windows) and create the main tc Server installation directory, such as /home/tcserver. For example, on Unix:

    prompt$ mkdir /home/tcserver
  3. Unzip or untar the bundle you downloaded into the new directory.

    For example, if you downloaded the tc Server Developer Edition into the /home/Downloads directory:

    prompt$ cd /home/tcserver
    prompt$ unzip /home/Downloads/vfabric-tc-developer-2.5.X.X.zip

    This creates a directory called vfabric-tc-server-developer-2.5.X.X. This directory contains the tc Runtime utility scripts, the templates directory (including the insight template), Tomcat 6 and 7, and so on. See Overview of tc Server Directories, Variables, and Configuration Files for details.

  4. Create a tc Server instance with the Spring Insight Developer template using the tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) script. On Unix, for example:

    prompt$ cd /home/tcserver/vfabric-tc-server-developer-2.5.X.X
    prompt$ ./tcruntime-instance.sh create myInstanceName -t insight
  5. Execute the tc Server instance you created using the tcruntime-ctl.sh (Unix) or tcruntime-ctl.bat (Windows) script.

    On Unix:

    prompt$ ./tcruntime-ctl.sh myInstanceName start

    On Windows, you must install the instance as a Windows service before you start it:

    prompt$ tcruntime-ctl.bat myInstanceName install
    prompt$ tcruntime-ctl.bat myInstanceName start
  6. Deploy your Web applications to tc Server. Copy the WAR files to the webapps directory of the tc runtime instance and make any necessary changes to the conf/server.xml and conf/context.xml files to support the deployed application.

  7. Access the Spring Insight Dashboard by loading the url http://localhost:8080/insight in your browser.

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

3.2 Configuring Spring Insight

You configure Spring Insight by editing the insight.properties file, located in the insight directory of the tc Runtime instance. For example, if you created an instance called insight-instance, then its configuration file is in a subdirectory of the tc Server installation directory at ./insight-instance/insight/insight.properties.

In the properties file, each property is on its own line. The properties take the form property: value. Comments begin with #.

The following table describes the properties you can set in the insight.properties file.

Table 3.1. Properties of the insight.properties File

Property and Default SettingDescription
insight.data.dirSpecifies the full pathname of the directory in which Spring Insight persists its data. If you do not specify a value for this property, the default data directory is INSTANCE_DIR/insight/data.
application.context. ignore.identifierSpecifies the application contexts that you want Spring Insight to ignore. Spring Insight will not instrument these applications, which in turn improves the startup time of the application.

The default insight.properties file excludes the Spring Insight application itself from being instrumented by adding the following entry:

application.context.ignore.dashboard: localhost|insight

The identifier part of the property name (such as dashboard in the example above) is not used internally by Spring Insight. Use this part of the property name to separate multiple entries; specify an identifier that has meaning to you.

The value of this property must be of the form localhost|context where context refers to the URL context that invokes the application. The value of context refers to the URL context you specify in a browser to invoke the application. By default, this is the name of the WAR file in which the application is packaged, but you can specify a different name in the web.xml file.

database.urlSpecifies 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 persist its data. A tc Runtime instance configured with Spring Insight is automatically configured to internally connect and use the H2 database.

database.driverClassNameSpecifies the class name of the JDBC Driver that Spring Insight uses to connect to the database.
database.usernameSpecifies the name of the user that connects to the database that Spring Insight uses to persist its data.
database.passwordSpecifies the password of the user that connects to the database that Spring Insight uses to persist its data.
trace.exclude.path.typeProvides 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. Specify this property multiple times, one for each type of pattern you want to exclude.

For example:

trace.exclude.path.png: /**/*.png
trace.exclude.path.gif: /**/*.gif
trace.exclude.path.jpg: /**/*.jpg
trace.exclude.path.css: /**/*.css
trace.exclude.path.js: /**/*.js

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. With the the Sun JVM, you may need to 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, where CATALINA_BASE refers to the root directory of your instance, such as /home/tcserver/vfabric-tc-server-developer-2.5.X.X/insight-instance. The comments in the file itself show examples of setting the JVM options.

4. Using Spring Insight

Spring Insight Developer enables you to see what your application is doing under the glossy exterior of @annotated APIs or proxied objects. Popular frameworks of today hide tremendous power behind 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 tc Server Developer Edition and create a tc Runtime instance using the Spring Insight template. 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 that you created an instance called insight-instance using the provided insight template and that 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.

4.2 Invoking Spring Insight in your Browser

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

  1. Start your favorite browser and browse to the Spring Insight dashboard using 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:

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

4.3 Browsing all Applications and End Points

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

The Browse Resources screen shows information for all types of applications, but it is especially 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 Applications 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 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 this procedure.

    Spring Insight loads the resource tree when it initially loads the page. If you subsequently deploy a new application or Spring Insight detects 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. Each application has its own color so you can differentiate them. The lower panel lists the same applications in tabular form, along with the following information about each application:

    • The Health Trend column shows a simple sparkline that graphically describes the recent health 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 graphical or tabular view of all applications is useful to see which applications have been busiest and to compare their relative health. Click in the graphs to see the application-specific information. Click the column headers in the table to sort the information based on the column.

  2. Click on an application in the left Applications panel. The right panel displays similar information about the application as 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 the application 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 possible HTTP URLs is unlimited. However, Spring Insight can group requests together based on the controllers with which the requests 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 and green is more healthy. See Customizing End Point Thresholds for help setting the tolerable threshold.

    • End Point: Displays the name of the End Point.

    • Health Trend: Displays a simple sparkline that shows the recent health of the End Point.

    • 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 95% response time over the given time range. This value is useful to determine the worst-case request. A value of 115ms indicates that 95% of the requests completed within 115 milliseconds. The response time of an HTTP 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, response time trend, and error rate. Response time trend refers to the mean response time of the End Point over the time range. Throughput trend refers to the recent mean throughput time of the End Point. The error rate shows the percentage of traces that resulted in an error. Hover over any spot in the chart to view details for the time slice 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 time range represented on the current chart.

    • The Response Time section displays statistics about the response times for all of the traces represented on the current chart. The 95th Percentile statistic indicates that 95 percent of requests completed within the indicated time period. The Mean is the average response time. The Standard Deviation is a measure of the variability of response times. A larger standard 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 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 Health of the End Point 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. See Viewing Recent Activity of Your Application for detailed information about traces and trace details.

4.4 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 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. The Recent 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 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 Spring Insight captures 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 of the 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 then details about a specific trace. Spring Insight automatically shows details about the first trace in the Trace Details panel. If you 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 trace start?), 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 and pages 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 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 whether 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. Because operations can be nested within operations, the green bar shows only how long the particular operation took, not the sum of duration of the nested operations. This way you can scan all the nested operations and find the particular one that took the longest time, based on the 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 specific to 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 this feature.

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

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

    • Change the global time range using the first drop-down list. The time range specifies how many minutes worth of data shows 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 when you 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 trace information about all your applications to disk, which means you can rewind and look at trace information from when you first 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 Trace History graph.

4.5 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 operations that are most likely interesting to you. However, the Trace Details pane could still be very large. In this case, you might want to filter 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 the current list of trace details. Spring Insight has a number of plug-ins installed by default. Click the Administration tab on the main dashboard then Collection Plug-Ins to see the list. If you have previously added your own custom plug-in to Spring Insight so 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 as well 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 the Database filter.

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

  • Web: Filters operations based on whether they are related to Web calls, such as HTTP requests and responses, rendering of HTML 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 to reset 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 Your Application.

  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 only those operations, - (minus) to exclude the operations, or leave the box unselected. If you do not set a filter to + or -, the operations 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 to alert that a filter is being applied.

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

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

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

4.6 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 off to another person.

For example, assume that a QA engineer is testing their company's Web application and runs into an error, or an operation takes an excessive time to complete. The QA engineer uses Spring Insight to take a look at what just happened by navigating to the relevant trace and viewing its details. If the QA engineer decides to open a bug about the problem, they can export the trace to a file 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 to actually deploy the application; rather, they can look at the trace details to figure out which operation caused the error, where the excessive time occurred, and so on. This is an easy way to capture a complete set of trace information about an error event, even if 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 Your Application.

  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 form trace-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 trace in the Trace History pane, go back in time to when the trace was originally exported.

4.7 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-axis is 4-times the threshold, or 800ms by default. The time chunks of the y-axis are not evenly distributed, but rather, broken up in a way 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 this as the threshold. The histogram will then have a smaller range, and thus show more fine grained information. Similarly, if you have an end point in which the response times are always over 200ms, the health of this end point will almost always show as frustrated. If you decide that it is acceptable if a threshold of 300ms is acceptable, then you can change it for this End Point so 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 to decide 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 under 800ms 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 the default 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 change the 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 Points that 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 Insight applies 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. In our example, the new threshold is 100ms and so the upper limit is 400ms:

4.8 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 Spring Insight. The two products are now integrated so that you 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 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 Spring Insight data along with 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 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, End Point or Application links, which will jump into Spring Insight at the appropriate location so you can further drill down.

4.9 Using Annotations To Customize Spring 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 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 add Spring Insight-specific annotations to the Java source of your application to inform Spring 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 Spring Insight Annotations for a code example and a screenshot of Spring 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 Developer 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 Spring Insight should display the annotated method and its arguments in the Spring 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 Spring 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 Spring Insight to display when you expand the frame. If you do 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 and its arguments in the Spring Insight Traces. Additionally, the annotated method is declared as an End Point, which means that it shows up in the Browse Resource list as an End Point. 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 Spring 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 Spring Insight to display when you expand the frame. If you do not specify this attribute, Spring Insight does not display any comment.

Example of Using the Spring 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 Spring 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 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 make the 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.5.0.RELEASE</version>
        <scope>provided</scope>
      </dependency>
      ...
    </dependencies>

Note that the preceding example depends on version 1.5.0.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 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 Developer 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 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 VMware EULA. Plug-in authors are free to license their plug-ins as they see fit.

5.1 Prerequisites for Installing the Spring Insight Developer Kit

Before you install the Spring Insight Developer Kit:

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

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

5.2 Installing the Spring Insight Developer Kit

  1. Download the Spring Insight Developer Kit from the VMware Download Center. The name of the bundle is insight-developer-kit-1.5.X.X.zip, where X.X refers to a specific version, such as 0.RELEASE.

  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-1.5.X.X.zip

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

The Developer Kit installation consists of the following files:

samples/payme-insight-plugin
samples/payme-webapp
insight-plugins/annotation
insight-plugins/grails
insight-plugins/hibernate
insight-plugins/jdbc
insight-plugins/method-endpoint
insight-plugins/servlet
...
  • 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 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 (Operation.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 End Points based on the traces that match that End Point. End Points 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 End Point—defines the trace as belonging 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 same method 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. The raw Servlet to which the request was initially mapped can also define an End Point. In this case, the more specific End Point contains 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 in Spring 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, End Point analysis, trace storage, and the user interface.

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 Spring 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 Spring Insight 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 other words, ~/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 getting started.

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

    $ cd ~/dev/insight-dev/vfabric-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 Spring Insight-enabled tc Runtime instance insight-instance:

    $ cp target/payme-insight-plugin-version.jar \
         /home/s2/vfabric-tc-server-developer-2.5.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.5.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.5.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 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 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 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 Spring 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 Spring 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

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 own Operation subclasses that can be instantiated by the aspects. These plug-in operations are then moved through the Spring 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 Spring 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 Spring 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>

The Spring Insight Dashboard web application includes a FreeMarker macro file you can use to ensure your operation is rendered in 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 name attribute is printed in the first table column and the value returned by the getter (value attribute) is rendered in the second column. 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 what constitutes an End Point. An EndPointAnalyzer looks at a trace and says, "This is a Servlet End Point at /imageServlet" or "This is 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, and Servlets.

All registered EndPointAnalyzers can look at each trace as it is created and determine which End Points 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 Spring Insight by 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.

6.4 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 the Apache License 2.0. The source code for the Spring Insight dependencies (core packages) is available as source jars, through Eclipse and Maven. Eclipse makes these jars available after you import the sample plug-in.

If you are not using Eclipse, visit the VMware Download Center 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

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:

  • vFabric tc Server Developer Edition, version 2.5

  • Spring Insight Development Kit, version 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-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, 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
    vfabric-tc-server-developer-2.5.X.X.zip
    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 vfabric-tc-server-developer-2.5.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
  5. Verify that Insight is working.

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

  6. Unpack the Insight Development Kit:

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

    Replace X.X with the actual version numbers. This creates a child directory called vfabric-insight-developer-kit-1.0.X.X, where X.X refers 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 vfabric-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, you can 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 (or whatever is appropriate for your environment) in the Directory field.

    4. Click Finish.

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

    The insight-plugin-tiles plug-in requires some Apache Tiles interfaces and classes. You can make these available by 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.

  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 (because 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 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.

  18. Update the configuration of the Spring Insight application so that you can view trace information about the Insight application 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 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
    # "[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 see the plugin in action. Because the insight-plugin-tiles plug-in will also collect data for the Insight Dashboard, you can see the effect immediately, but you must first specify that you want Insight to instrument itself.

  19. 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. Choose the 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 to render 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 the TilesRenderOperation. Notice the Return Value: void and Exception: null properties. Those (along with the Tiles Render Operation Operation) 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, as described in the following steps.

  20. 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 />
    
    <@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 your TilesRenderOperation if they have a getter (getDefinitionName()).

  21. 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:

    <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 a TilesRenderOperation. The TilesRenderOperation.getType() method returns an OperationType that Insight uses to compose the bean id (operation.tiles_render_operation).

  22. 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/org/myorg/insight/tiles/ 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"));
        }
    }
  23. Run the test.

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

    The test should report BUILD SUCCESSFUL.

  24. 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 one line.

    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 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 annotation plug-in

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

Table 8.2. Endpoint Analysis of annotation plug-in

AnalyzerAnnotatedMethodEndPointAnalyzer
Core OperationAnnotatedMethod Operation
ScoreHigh by default, customizable in annotation.
SummaryFinds operations created from @InsightEndPoint, thus creating the end point.

8.2 grails

Grails-specific support for controller methods.

Table 8.3. Operations of grails plug-in

Collection PointSummary
Grails Controller MethodMethod on a Grails Controller to which the request is mapped.

Table 8.4. Endpoint Analysis of grails plug-in

AnalyzerGrailsControllerMethodEndPointAnalyzer
Core OperationGrailsControllerMethodOperation
ScoreVaries.
SummaryCreates an end point for HTTP requests handled by Grails.

8.3 hibernate

Support for tracing Hibernate persistence operations, such as get, save, update, and delete. A Hibernate session represents one transaction, 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 (the number of collection instances associated with the session).

Table 8.5. Operations of hibernate plug-in

Collection PointSummary
org.hibernate.SessionCRUD operation on persistent entities.

8.4 jdbc

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

Table 8.6. Operations of jdbc plug-in

Collection PointSummary
java.sql.StatementOperation with the raw SQL statement.
java.sql.PreparedStatementOperation with the raw SQL statement and parameters.

8.5 method-endpoint

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

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

AnalyzerTopLevelMethodEndPointAnalyzer
Core OperationMethodOperation
ScoreLow.
SummaryCreates an end point for a root-level operation within a Trace.

8.6 servlet

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

Table 8.8. Operations of servlet plug-in

Collection PointSummary
javax.servlet.FilterOperation with the filter name and init params.
javax.servlet.ServletContextListenerOperations for context initialization and destruction events with context params.

Table 8.9. Endpoint Analysis of servlet plug-in

AnalyzerServletEndPointAnalyzer
Core OperationHttpOperation
ScoreLow.
SummaryCreates an end point for HTTP requests, grouped by the matching servlet, that are otherwise not accounted for by an end point.

8.7 spring-core

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.10. Operations of spring-core plug-in

Collection PointSummary
@RepositoryCreates an operation for calls into classes annotated with @Repository
@ServiceCreates an operation for calls into classes annotated with @Service

8.8 spring-tx

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.11. Operations of spring-tx plug-in

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

8.9 spring-web

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.12. Operations of spring-web plug-in

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

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

AnalyzerControllerEndPointAnalyzer
Core OperationControllerMethodOperation
ScoreVaries.
SummaryCreates an end point for HTTP requests handled by Spring MVC.

8.10 tomcat

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

Table 8.14. Operations of tomcat plug-in

Collection PointSummary
JSP CompilerOperation showing time spent in JSP compilation (typically the first request to a JSP) and the compiler implementation.

8.11 Server-Based Instrumentation

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

Table 8.15. Operations of Server-Based Instrumentation

Collection PointSummary
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.
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.