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>

Nodes

nodes.jpg
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

stackTraces.jpg
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:

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:

'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

merge.jpg
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:

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

compare.jpg
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

editTemplate.jpg
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: