Getting Started with Spring Insight
Version Preview
SpringSource Document build:
January 7, 2010, 3:08:10 PM (PST)


   
Copyright Notice
Copyright © 2009 SpringSource Inc. All rights reserved.
Trademark Notice
SpringSource is a registered trademark of SpringSource, Inc. and/or its affiliates. Other names may be trademarks of their respective owners.
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19. SpringSource, Inc., 411 Borel Ave., Suite 101, San Mateo, CA 94402.
This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. SpringSource, Inc. and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.
This software and documentation may provide access to or information on content, products and services from third parties. SpringSource, Inc. and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. SpringSource, Inc. and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.


Version Preview   Getting Started with Spring Insight
   
Contents
Introduction to Spring Insight     •
Installing and Configuring Spring Insight     •
Using Spring Insight     •
•


Getting Started with Spring Insight
SpringSource, IncGetting Started with Spring InsightSpringSource Spring Insight
Introduction to Spring Insight
•
 
•
 
•
 
•
 
•
 
•
 
What Is Spring Insight?
Spring Insight answers the question "What just happened?" It is a SpringSource Web application that gives you real-time visibility into application behavior and performance.
In development and testing stages, developers can use Spring Insight to verify immediately whether their newly-written code is behaving as designed. QA engineers can pinpoint specific causes for "what just happened" and relay detailed information to developers.
Stress testing an application typically tells you which URL areas are slow. By combining Spring Insight with your existing tools (such as JMeter), you can see not only which URLs are slow, but why, thus accelerating your time to production.
The following topics discuss specific use cases:
Agile Development
Web application developers realize a massive increase in productivity when they can make changes and see the effect immediately. Typically, a developer makes changes to HTML or JSP and reloads the browser to verify that the modified application performs as desired. However, developers often lack a centralized tool that shows how their changes affect:
•
 
JDBC queries
•
 
Spring bean interaction
•
 
Calls to external services
Large, popular frameworks such as Hibernate and Spring Web push much of the code that developers formerly wrote manually into a convenient library. This process saves time and improves maintainability. The downside is relinquishing control, which means that the developer may not know exactly what is going on behind the scenes:
•
 
How many database transactions did a web request create?
•
 
How expensive is it to use complex web parameter binding?
•
 
What are the HTTP headers being sent to the developer's REST application?
The Spring Insight Trace view solves these problems. It allows developers to make changes and verify their effectiveness immediately.
QA Rear View Mirror
Spring Insight gives QA a richer picture of an application's performance, eliminating much of the work required to diagnose problems. As QA tests an application, typical problems include:
•
 
Slow-loading pages
•
 
Database grinding
•
 
Stack traces
As these problems arise, QA engineers can browse to the Spring Insight dashboard and review all recent operations. They can access in-depth information that helps them track down bugs:
•
 
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.
How Does Spring Insight Work?
Spring Insight is a lean framework that keeps developer requirements to a minimum. Developers can deploy a native application to a Spring Insight-enabled tc Server instance and immediately see diagnostics. There is no database to set up, no instrumentation to perform.
Spring Insight captures application events known as traces. A trace represents a thread of execution. It is usually started by an HTTP request but can also be started by a background job. A trace contains operations. Each operation represents a significant point in the execution of the trace, for example, a JDBC query or transaction commit.
Using this data,Spring Insight calculates summary information to lead you to the specifics of why your application is not performing.
Spring Insight uses AspectJ to snoop on operations in target web applications. Target web applications are loaded with a special classloader that dynamically instruments web applications at runtime. Spring Insight currently keeps its data in memory. It does not use an external database or write any data to disk. It uses sophisticated algorithms to keep the memory footprint low. Spring Insight-enabled servers require more memory (-Xmx) than a standard server.
Supported Environments
Spring Insight runs in environments with a Java 5 or Java 6 JVM. Spring recommends Java 6 for the best experience and will alert you to any differences that arise between Java 5 and Java 6. Most portability issues surface when you change JVMs and/or when you change browsers. For this preview release Spring has tested the following environments:
•
 
Linux 64 bit, Sun Hotspot 1.6 JVM
•
 
Windows 32 bit, Sun Hotspot 1.6 JVM
These environments should work well, but Spring welcomes feedback from anyone who tries out the preview on other configurations.
Installing and Configuring Spring Insight
•
 
•
 
Installing Spring Insight
Installing Spring Insight consists of two main tasks:
•
 
Installing a developer edition of the tc Server application server that includes the Spring Insight feature.
•
 
Creating a tc Server instance using the Spring Insight template so that the instance is immediately enabled with the Spring Insight feature.
The procedure covers Unix and Windows installation, although the examples are based on Unix. If you are installing on Windows, change the forward slashes (/) to back slashes (\); other differences are called out.
1.
 
Download the Spring Insight distribution from the Spring Insight Product Page. (The Spring Insight distribution is part of Spring tc Server Developer Edition.)
The distribution file is called tcServer-6.0.20.C-GA-devedition-PREVIEW.tgz.
2.
 
Unpack the Spring Insight distribution file into a temporary directory.
For example, to unpack the Unix file in a directory called /home/unpack and assign the extracted files to the same group as the user executing the command, use the tar command: 
prompt$ cd /home/unpack
prompt$ tar --no-same-owner -xvzf /home/tarfiles/tcserver-6.0.20.C-devedition-PREVIEW.tgz
This command creates a sub-directory called tcserver-6.0.20.C-devedition-PREVIEW.
3.
 
Start a terminal (Unix) or command prompt (Windows).
4.
 
Change to the directory in which you unpacked the tc Server distribution file and execute the install.sh (Unix) or install.bat (Windows) script. For example, on Unix:
prompt$ cd /home/unpack/tcserver-6.0.20.C-devedition-PREVIEW
prompt$ ./install.sh
The installation program performs checks of your system, then displays a menu:
     #####################################################################
     ##   SpringSource tc Server Application Server Installation Menu   ##
     #####################################################################
   
       1. Install tc Server Application Server
       2. Exit
Note: You must run the install.sh script from the directory in which it lives, and not from any other directory, or you will get an error.
5.
 
Enter 1 to install the tc Server application server.
6.
 
If you have not done so, create a directory into which you will install the tc Server application server. Enter the full pathname of the installation directory, for example, /home/springsource.
> Important: The specified directory must already exist; the install program does not create it for you.
7.
 
After confirming your entry, the installation program installs tc Server and returns you to the main menu.
8.
 
Enter 2 to exit the installation program.
9.
 
Change to the main tc Server installation directory. For example, if you specified that you wanted to install tc Server in /home/springsource, change to the /home/springsource/tcServer-6.0 directory:
prompt$ cd /home/springsource/tcServer-6.0
10.
 
Use the tcserver-instance.sh (Unix) or tcserver-instance.bat (Windows) command script to create a tc Server instance that uses the spring_insight template. For example, on Unix:
prompt$ ./tcserver-instance.sh -s insight -t spring_insight
In the preceding example, the script creates a tc Server instance called insight in the current directory.
Also, it is assumed in the example that you have set your JAVA_HOME environment variable to point to an installed JDK/JRE and the tcserver-instance.sh script will subsequently refer to it; if, however, this is not the case, use the -j option to point to its location:
prompt$ ./tcserver-instance.sh -s insight -t spring_insight -j /home/java/jdk1.6.0_12
11.
 
Start the newly-created tc Server instance with the tcserver-ctl command script. On Unix:
prompt$ ./tcserver-ctl.sh insight start
On Windows, start the instance as a foreground process:
prompt> tcserver-ctl.bat insight run
12.
 
From your Web browser, invoke the Welcome page for the tc Server instance:
http://host:8080
where host refers to the computer on which you installed tc Server. If it is the same as the browser's computer, you can use localhost:
http://localhost:8080
13.
 
To start Spring Insight:
http://localhost:8080/insight
14.
 
To shut down the tc Server instance on Unix, run the following command from /home/springsource/tcServer-6.0 directory:
prompt$ ./tcserver-ctl.sh insight stop
On Windows, enter Ctl-C in the command window where you started the tc Server foreground process.
Configuring Spring Insight
You configure Spring Insight by editing the spring-insight.yml file, located in the conf directory of the tc Server instance. For example, if you installed tc Server in /home/springsource and created a tc Server instance called insight, then its configuration file is /home/springsource/insight/conf/spring-insight.yml.
The file is written in YAML, which is an intuitive means of marking up complex datatypes.
The general format for setting a property is property: value, such as minTraceDuration: 0.
The following sample spring-insight.yml displays the default configuration file of a newly-created tc Server instance. Use it as a guide to set your own property values:
#
# The Spring Insight(tm) configuration file (in YAML)
#

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

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

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

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

# The number of seconds a request must complete in for
# it to be deemed 'satisfactory'.  This threshold is used
# to calculate the color of the health bar for endpoint
# response time.
# The formula for calculating the health bar closely
# corresponds to the Apdex formula.
# See apdex.org for more details.
healthyResponseTime: 0.2
The following table describes the properties you can set in the spring-insight.yml file.
Property and Default Setting
Description
minTraceDuration: 0
Minimum required duration of a trace should take (in milliseconds) for it to be captured by the system. This setting prevents extremely short requests from being processed and cluttering your view.
maxInMemoryTraces: 2000
Defines how many traces are kept in memory. Once this limit is reached, the oldest trace is discarded. The Spring Insight application does its work in memory and does not require a database.
tracePurgeBatch: 200
Defines how many traces are purged at once, once maxInMemoryTraces has been reached. By purging many traces simultaneously, Spring Insight frees memory more efficiently.
excludeTraceByPath:
Provides a list of patterns that are matched against requests. When a trace matches a path in this list, the trace is discarded. This setting lets you ignore requests to static content such as .css or .js files.
For example:
excludeTraceByPath:
- /**/*.jpg
- /**/*.css
- /**/*.js
The -prefix is important. It is the YAML identifier showing that the items are in a list.
healthyResponseTime: 0.2
Divided into categories: satisfying, tolerated, and frustrating. This property defines the maximum response time that can be satisfying. For example, if healthyResponseTime = 0.3 then a response in 100ms is satisfying. This setting gauges the colors of the indicators for response time (excellent, good, fair, poor, unacceptable).
Using Spring Insight
Spring Insight enables you to see what your application is doing under the glossy exterior of @annotated APIs or proxied objects. The most popular frameworks of today hide tremendous power behind their friendly facades. For example, a simple session.save(book) that uses Hibernate can execute hundreds of JDBC calls, depending on your mapping. Spring Insight brings these low-level performance-oriented operations to the screen for quick evaluation.
The following procedures describe basic tasks that help you start using Spring Insight with your own Web application:
•
 
•
 
Before You Begin
It is assumed that you have installed Spring Insight, created a tc Server instance with the spring_insight template, and then started the instance. For details, see Installing and Configuring Spring Insight.
It is also assumed that you have already deployed your Web application to the tc Server instance, that you have configured all of its resources (such as any required JDBC data sources), and that your application is running and ready to be used.
To deploy a Web application to a tc Server 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 Server instance.
For example, assume you created a tc Server instance called insight and its CATALINA_BASE is /home/tcserver/tcServer-6.0/insight. Further assume that the full pathname of your Web application is /home/apps/myApp.WAR. To deploy this application to the tc Server instance, execute the following command: 
prompt$ cp /home/apps/myApp.WAR /home/tcserver/tcServer-6.0/insight/webapps
For complete tc Server documentation about, see SpringSource tc Server Documentation.
Viewing Recent Activity of Your Application
The following procedure describes how to use Spring Insight to get an overview of the recent activity of a particular application, or for all applications currently deployed, and then how to drill down to the details of particular application event.
1.
 
Initiate activity by using your Web application; the exact steps depend on what your application actually does.
Spring Insight traces all application activity and displays it on the dashboard. For example, if you performed any JDBC queries, each one is shown in the Spring Insight dashboard along with a timeline of recent requests.
2.
 
Browse to the Spring Insight dashboard:
http://host:port/insight
where:
•
 
host is the computer on which the tc Server instance is running. If it is the same computer as your browser, you can use localhost.
•
 
port is the port number to which the tc Server instance listens. By default, this port is 8080.
For example:
http://localhost:8080/insight
The browser invokes the main Spring Insight dashboard on the Recent Activity screen and displays recent traces from your application. A trace is a breakdown of the activity of a request. The Recent Activity screen answers the question What just happened?
 
3.
 
In the top-right Application Selector drop-down box, select the name of your application.
Use the Application Selector to view activity for all applications or for just a single one. Viewing all applications at once is useful when you deploy many Web applications and are interested in activity across the entire set. Viewing a single application filters out activity not related to that application.
The Trace History panel shows a timeline of the recent activity of your application as real-time requests, represented by bars in the chart. Each bar represents all requests that occurred within a time slice, as measured by the chart. The full time range has 60 time slices. The height of the bar is equal to the longest request that occurred during that window.
The Trace History graph shows activity that Spring Insight has monitored over the past N minutes. When a trace is captured by Spring Insight, it shows on the graph as a bar on the right-hand side. As time moves on, bars move left until they fall out of the time range. Click on bars to drill deeper.
4.
 
Click on one of the bars 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?), Start (when did the trace start?), or Label (what was the request?)
5.
 
Click on a trace in the Traces panel to view its details in the Trace Detail panel, as shown by the following screenshot:
 
The Trace Detail panel contains a breakdown of a trace's activity in a tree format. A trace consists of a top-level operation, usually a Web request, and all nested operations.
Operations are the fundamental building blocks of traces. An operation can represent a Web request, a transaction, a call to an MVC controller, a file opening, a service request, and so on. Each operation may have other operations nested within it. The nesting structure shows the normal stack-based method invocation pattern.
The operation timing graph shows two pieces of information:
•
 
When the operation executed in relation to the other operations. This information shows the operation executed towards the end of the request or the beginning by the location of the green bar in relation to its borders.
•
 
How long the operation took to execute, indicated by the width of the green bar.
Click on an operation's label, or the entire row, to drill further into the operation details. The details of this panel are specific to each type of operation, and contain the finest granularity of collected data.
6.
 
In the Control menu directly below the Application Selector, control the information you see in the Spring Insight dashboard by:
•
 
Changing the global time range. The time range specifies how many minutes worth of data shows up in the Trace History graph.
•
 
Playing or pausing the graph movement. To stop the graph from automatically moving as new traces are recorded, click the control to Pause. If the graph is in Play mode, the word Live appears under the right hand side of the graph.
•
 
Refreshing the trace history by reloading all data within the Trace History graph or clearing the trace history, which removes all stored data. This function removes all captured response times, traces, and health data.
Viewing the Overall Health of Your Application
The following procedure describes how to view a health summary of your application's recent activity.
Currently, the Application Health screen shows information only for Spring Web applications.
1.
 
From the main Spring Insight dashboard, click the Application Health link. If you haven't already done so, select your application from the application selector.
The following graphic shows a sample application health screen for the swf-booking-mvc application:
 
Each row represents an endpoint, which is a receptor for requests. The universe of all possible HTTP URLs is unlimited. However, Spring Insight can group requests together based on the controller with which the requests are associated. For each endpoint, Spring Insight displays the following information:
•
 
Health: Shows how well the response time metric is kept within a tolerable threshold, where red is less healthy and blue is more healthy. If a given endpoint has received fewer than 100 invocations, it also display a ? to indicate that it does not have enough data to make a good determination. See Configuring Spring Insight for details on setting the tolerable threshold in the spring-insight.ytml file with the healthyResponseTime property.
•
 
HTTP Endpoint: Displays the name of the endpoint and a recent request made to it.
•
 
Trend: Displays a simple sparkline that shows the recent mean response time of the endpoint.
•
 
Invocations: Displays how many times the given endpoint has been invoked.
•
 
Response Time: Displays the 99% response time over the given time range. This value is most useful to determine the worst-case request. A value of 115 ms indicates that 99% of the requests occurred within 115 milliseconds. The response time of an HTTP request is determined by the full time it takes the container to ship the response to the client, and not just the time spent in a controller.
2.
 
Click a particular endpoint to view details of the recent activity of a specific endpoint (mostly its response time), as shown in the following screenshot:
 
The Response Time Trend chart shows the mean response time of the endpoint over the time range.
The Response Time Histogram is an interactive graph that shows how many invocations occurred within a given time period. The Y-axis represents the response time of an invocation. The X-axis represents the number of invocations. Using the histogram is an easy way to identify outliers in your data. The longest-running invocations are always at the top of the histogram. If extreme outliers exist, they are indicated by red bars.
3.
 
Click a bar in the histogram. 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.
•