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:

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 2. 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 3. 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 VMware downloads page (vFabric tc Server link) and then add the file to your compile-time CLASSPATH variable.