JEXIN User's Guide

Overview

Jexin is a web application that allows the user to view and interact with the flow of execution. The tool allows the user to view details about the execution path within a node or nodes and inject exceptions into the path to simulate faults. Firefox is the preferred browser but IE is also supported.

The purpose of this tool is to emulate exception conditions (unable to connect to host, disk full, etc). You must understand the concept of stack traces and the internal workings of the application being tested to use this tool effectively. A stack trace is the path taken through the code by a thread of execution. If an HTTP request is received by a web application, for example, the thread processing the HTTP request runs through a series of methods to process the request and eventually sends a response back to the client. Each method call is represented as a stack frame. The stack frame contains information about the method call. The series of stack frames created by the methods invoked by a single thread is a stack trace. Several stack traces may be involved in a single functional test.

A stack trace template is used to validate and/or inject exceptions into a stack trace. The template is created from an existing stack trace. The stack frames from all active templates on a node are compared to the respective stack frames in live stack traces. If a template's frame does not match then the template is no longer associated with the live trace. If the template does match and is configured to inject an exception then that exception is injected into the live stack frame which results in the method associated with that frame throwing the injected exception. If multiple template frames match the live frame and are configured to inject exceptions the first injected exception found is injected and the others are ignored.

The interface layout is simple. There is a line near the top of every page that separates the header from the content. The left side of the header shows a series of links called breadcrumbs. As you progress through screens in the application the breadcrumb links form a trail. You can click on any breadcrumb to go back to that point in the application. The right-most breadcrumb is for the current page; clicking it will refresh the current page. The right side of the header shows the menu. Menus are page-specific. Some pages have no menu. The content section is below the header line. It contains the content for the page.

The TraceAspect aspect advises all methods and constructors annotated with Traceable. These are called traceable methods. Invocations of these methods result in realtime interaction with the Jexin web application both before and after the method executes. The before advice allows the tool to create a stack frame for the call and determine if the method should be allowed to execute normally or if an exception should be injected. The after advice informs the tool of a normal return or the exception thrown.

RuntimeExceptions may be injected. These are called 'injectable exceptions'. All injectable exceptions have a description (shown in the tool's UI) and ID. RuntimeExceptions may be made available by configuring them in the TraceServer.

Any injectable exception may be injected into any traceable method. Some exceptions will me more realistic in a particular method than others. Developers can highlight the more realistic exceptions using the injectableExceptions property of the Traceable annotation. All the exceptions listed in that property will be highlighted for that method in the tool's UI. This will not prevent any other exception from being injected into that method, it just highlights the ones the developer feels should be brought to the user's attention.

To enable tracing in a node you configure a Spring bean of class org.hopto.pentaj.jexin.client.TraceServer. TraceServer.init and TraceServer.destroy are advised by the TraceAspect aspect which delegates all implementation to the TraceServer. If no TraceServer is configured then the TraceAspect has minimal impact on the execution path (a single 'if' statement before and after each traceable method). An example configuration file is below:

<?xml version="1.0" encoding="UTF-8"?>
<beans
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"
    default-init-method="init" 
    default-destroy-method="destroy" 
>  
    <bean class="org.hopto.pentaj.jexin.client.TraceServer">
        <property name="nodeName" ref="My Node"/>
        <property name="port" value="4466"></property>
        <property name="readTimeout" value="5000"></property>
        <property name="injectableExceptions">
          <set>
            <bean class="org.hopto.pentaj.jexin.client.InjectableException">
              <constructor-arg value="1" />
              <constructor-arg value="Something Bad Happened" />
              <constructor-arg>
                <bean class="java.lang.RuntimeException">
                </bean>
              </constructor-arg>
            </bean>
          </set>
        </property>
    </bean>
</beans>

NodeName - The name of the node (required). This should uniquely identify an instance of an application.
Port - The port the TraceServer should listen on (default = 4466).
ReadTimeout - The socket SO_TIMEOUT value in milliseconds (default = 5000).
InjectableExceptions - The set of InjectableExceptions available to the UI. InjectableException takes three constructor arguments:
1. The exception ID: this can be any integer between Integer.MIN_VALUE + 100 and Integer.MAX_VALUE - 100. All injectable exception IDs must be unique.
2. The exception description: the string displayed in the tool's UI.
3. The RuntimeException to inject: this is the exception that is actually thrown when injected.

Nodes

Figure 1

Figure 1 is the nodes page. This page is used to manage and connect to nodes. A node is identified by its host and port. To add a node enter the host and port information in the fields provided and click 'Add'. Connected nodes, meaning the application is currently monitoring the node's stack traces, are indicated by a green circle. The red circle means the application is not currently connected to the node. Deleting a node will only remove it from this page. It will not delete any existing stack traces or templates. If you add the node back, using the same host and port, any existing traces and templates will be available again. Click 'Stack Traces' go to the Stack Traces page and view the traces and templates for all selected nodes.

Stack Traces

Figure 2

The stack traces page contains 2 tables: 'Live Stack Traces' and 'Stack Trace Templates'.

Live Stack Traces Table

The live stack traces table (traces) shows information about completed stack traces received from the nodes selected on the nodes page. Each row represents a single stack trace. Traces that are not complete, meaning the first method that was called has not yet returned, are not visible on this page. If the node has a blocked thread no information about its stack trace will be available here until the thread unblocks and completes. The traces table has the following fields:

Checkbox ( ) - Click to select a trace. The checkbox at the top selects/unselects all the traces in the table.
Actions - The actions you can perform on the trace. 'T' creates a new template from the trace. 'C' takes you to the compare page which compares the trace and all the templates listed in the 'Templates' column.
Node Name - The name of the node the trace executed on.
Start Time - The time the first stack frame for the trace was started.
Millis - The elapsed time, in milliseconds, for the first stack frame in the trace. This is effectively the elapsed time for the trace as all other stack frames must start after and end before the first.
Thread - The name of the thread that executed the trace.
Templates - The templates that either injected an exception into the trace or matched the trace. The letter in parenthesis after the template name indicates the type of relationship the template has to the trace: 'I' indicates the template injected an exception; 'M' indicates the template matched the trace. The same template may appear twice, as an injecting and matching template. A template matches a trace if all the method signatures and thrown exceptions match.

Clicking 'Merge Selected Traces' at the bottom of the table takes you to the merge page which merges all selected traces into a single trace. This is valuable for things like viewing the processing path for a single functional test. The 'Delete Selected Traces' button deletes all the selected traces. There is no confirmation dialog, the traces will be deleted immediately.

Stack Trace Templates Table

The stack trace templates table (templates) shows the templates for all nodes selected on the nodes page. Each row represents a single template. The templates table has the following fields:

Checkbox ( ) - Click to select a template. The checkbox at the top selects/unselects all the templates in the table.
Actions - The actions you can perform on the template. 'E' creates a new template from the trace. 'E' takes you to the edit template page where you can edit the template. 'D' deletes the template. There is no confirmation dialog; the template is deleted immediately.
Node - The name of the node the template is associated with. The node is always the same as the node of the trace the template was created from.
Name - The template's name. This is arbitrary and may be changed on the edit template page. You should give all templates meaningful names to prevent confusion.
Time Created - The time the template was created.
Millis - The elapsed time, in milliseconds, for the first stack frame in the template. This is effectively the elapsed time for the template as all other stack frames must start after and end before the first. This is useful when comparing future matching traces to see performance differences between the trace that was used to create the template and the traces it matches.
Status - 'Active' or 'Inactive'. Active templates are compared with all stack traces on the node to inject exceptions and find traces that match them. Inactive templates are ignored and will not inject any exceptions or match any traces.

'Activate Selected Templates' and 'Deactivate Selected Templates' activate and deactivate the selected templates, respectively.

The 'Compare Selected Traces/Templates' button at the bottom of the page opens the compare page to compare all the selected traces and templates.

Merge Traces

Figure 3

Merging traces allows you to view several traces 'merged' so you can see the sequence of events across threads and JVMs. The merge threads page contains 2 tables: 'Merge Trace' and 'Merge Summary' which show the merger of the stack traces selected on the stack traces page.

Merge Trace Table

The merge trace table contains a column for each stack trace being merged. The stack frames are spread out so there is only one frame per row and the frames are in sequence across all traces. Only the method signature is shown for each stack frame by default to conserve space. The indent and leading dashes show the method's level in the trace. For example, in figure 3 you can see that BlogServlet.doPost called BlogServiceImpl.addEntry which called BlogEntry.BlogEntry and so on. There are links on the right side of the header that allow you to show/hide the following additional information for each frame:

# - A sequence number for the frame, starting with 1. Used to associate a row in this table with a row in the merge summary table.
Exceptions - The exception thrown by the method. This is empty if the method returned without throwing an exception.
Inejcted - The exception injected by a template. This is empty if no exception was injected.

Merge Summary Table

The merge summary table is an expanded view of the merge trace table. It contains a column for all the information in the merge trace table in an expanded view. The # column is used to associate a row in this table with a row in the merge trace table.

Compare Traces/Templates

Figure 4

This page shows a side-by-side comparison of all the stack traces and stack trace templates selected on the stack traces page. Each stack trace is displayed in a single column with a stack frame in each row. The stack frame display works exactly like the one on the merge page.

Edit Template

Figure 5

The edit template page is used to change a template's name and inject exceptions. Each row in the table is associated with a stack frame (the information displayed for each frame can be changed with the links in the header as in the merge page). The table has the following columns:

Stack Method - The method the stack frame represents. This is informational only; it can't be edited.
Exception to Inject - The exception to inject into a stack trace frame that matches the template at this frame. If the frame in the stack trace that was used to make this template threw an exception you can't edit this field. If the thrown exception was injected this will be set to inject the same exception and can't be changed. The drop down may contain some highlighted exceptions. A highlighted exception indicates the developer specified that exception as a likely one to be thrown from that method.