User Guide

#Overview

Code Pulse is a code coverage tool that works on Java programs in real time, showing you what code was called, when it was called.

TODO

#The Home Screen

When you open Code Pulse, it displays a loading indicator while the underlying components are initialized. Once it is ready, you will see the main screen.

There are three main components on the main screen; the new trace form, the import trace form, and the trace list. The two forms are accessible via their respective tabs, and the trace list is on the side of the page. Each section is described in more detail below.

##Creating Traces

To create a trace, Code Pulse needs two things; a name, and an input file.

The name can be whatever you want it to be. It is simply used to help distinguish one trace from another. You should try to pick different names for each trace that you make. If you name everything the same thing, Code Pulse won't be confused, but you might. Don't worry about picking the perfect name up front, you can always change it later.

The input file must be compressed folder containing .class files. Generally this will be a .jar, .war, or .zip file.

Note: most Java-based web apps are distributed as .war files. Often times, a .war file will contain .jar files in a special "lib" folder within itself. Code Pulse will dig into these "nested" jars during its search for .class files. As long as it finds at least one somewhere in the file you pick, it can use that file.

To pick a file, you can use the "Browse" button to open up a file picker dialog, or you can simply drag a file straight from your file system to the "Drag a file here" area.

Once you have filled in the form, click the "OK" button to submit it (or the "Cancel" button to clear the form). Code Pulse will start crunching the data, showing you the trace details screen when it has finished.

##Importing Traces

Traces can be shared. You can export traces by clicking the "export" links in either the trace-list or trace deatils screen. Exported traces have a .pulse file extension. Once exported, you can import it back into Code Pulse via the "Import Trace" form on the home screen. You could even send the file to someone else and they could import it with their own Code Pulse.

The import trace form and its controls are almost exactly like the new trace form, except that you don't need to pick a name; the name is included in the exported trace file. Simply pick the trace file (.pulse file) that you want to import, then click OK.

##The Trace List

As you create and import traces, they will be added into the trace list. This list serves as navigation between different traces, as well as some high-level controls for individual traces. The trace list is accessible from anywhere in Code Pulse; on the [home screen](#the home screen), it is visible by default; on the trace details screen, clicking the "Traces" button will cause it to slide into view.

Each entry in the trace list is a trace that you created or imported. The trace's name serves as a link to the details for that trace. Each entry shows the time when the trace was originally created. If it was imported, it also shows the time when it was imported to your Code Pulse. Each item also provides an export and delete link.

While on any trace details page, the trace list also includes links at the bottom for creating new traces and importing traces. The home screen version doesn't have these links because they would be redundant.

#Trace Details

The trace details screen is where most activity in Code Pulse happens. It contains three primary components; the package list, the treemap, and the trace controls.

The package list initially takes up a majority of the screen. The trace controls occupy the right-hand side of the screen. The treemap is hidden in a "drawer" by default. There is a < button that appears in the right side of the package list's header area; clicking this button will cause the treemap to slide out from under the trace controls, partially covering the package list.

To get to the trace details page, you can click one of the trace links in the trace list. Also, after creating or importing a trace, Code Pulse will automatically send you to its corresponding details page.

##Package List

The package list shows a high level view of the code. Each entry in the list represents either a Java package that was found during the analysis, or a high level grouping.

When creating the trace, Code Pulse searches for class files within the chosen input file (which is some sort of compressed archive). When it finds .class files, the corresponding classes are assigned to the "Classes" group. When it finds .jar or other compressed archives within the main file, it assigns any .class files within that sub-archive to the "Jars" group. When it finds a .jsp file, it creates a corresponding entry under the "JSPs" group.

Each item in the package list has the following sections, listed from left to right:

• expand/collapse button If the item has children in the package/group hierarchy, there will be a "+" button at the far left. Clicking the button expands the item's children. Clicking it again collapses the children.

• selection checkbox Clicking this box selects the corresponding item and all of its children. Selected items are then displayed in the treemap.

• name Displays the name of the package or group. Clicking the name also counts as clicking on the selection checkbox.

  Note: In some cases, Code Pulse needs to make the distinction between "classes in package 'com.foo.bar'" and "classes in package 'com.foo.bar' and any of its subpackages". If there is the need to express the former ("classes in package 'com.foo.bar' but not its subpackages), Code Pulse will generate a "<self>" node to represent it, as a child of the package it represents.

• trace selection checkbox This checkbox is used to determine which classes will be instrumented when tracing is in progress. Anything not checked here will not be considered for tracing. This is useful in case you picked a large .war file to trace, but it includes a lot of third-party dependencies that you don't care about. By default, Code Pulse will pick classes from the "Classes" and "JSPs" groups to be instrumented, ignoring classes from the "Jars" group.

• method count Shows the total number of methods found within the package/group and any of its children.

• percent coverage A bar chart that shows the percentage of methods that have been encountered by the trace (affected by selectios in the trace controls) While the trace is running, these bars will generally grow, as methods in the program are encountered.

Note: When the treemap is in view, the percent coverage bars are collapsed; only the percent label is visible instead of the bar.

##Treemap

The treemap exists in a "drawer" that slides out from behind the trace controls. To "open the drawer," click on the button with the triangle icon in the package list's header. Initially, you will only see a prompt asking you to select items from the package list:

The selection of items in the package list controls the contents of the treemap. No selection means no content. By selecting an item like com.foo.bar from the "Classes" group, the treemap will change to display a visualization of the packages, classes, and methods within com.foo.bar.

Note: A treemap is a method for displaying hierarchical data by using nested rectangles. In Code Pulse's case, we display code; groups contain packages (and sometimes other groups), packages contain classes (and sometimes other packages), and classes contain methods. The groupings Code Pulse displays reflect this hierarchy.

If you hover your mouse over the treemap, it will display a tool tip with more info about the particular "node" you are pointing to. At the very least, it will display some contextual information about where the node exists; for example, if you point to a method, the tool tip will show you what package and class that method belongs to. Also for methods, the tool tip's title shows the method's "signature" (i.e. public void foo(Object, String)) If a node has not been selected for tracing (see the "trace selection checkbox" in the trace list section), it is indicated in the tooltip.

Once run-time tracing has begun, the tooltip will also display information about which recordings have encountered that particular node.

The area of each method displayed in the treemap is proportional to the number of instructions in the method. Classes are sized to fit their children, and packages are sized to fit their own children, plus a small area for a title bar. Title bars are not always wide enough to fit the entire title. For example, a package named com.example.foo.bar.example may be displayed as "example" because the area wasn't wide enough to fit the entire text. You can always see the full text in the tool tip by mousing over the package's title area.

Once you have started tracing your program, Code Pulse will keep track of the methods it sees during the trace. Certain segments of time are treated as "recordings" (see more in the trace controls section). Each recording is associated with a color. When trace encounter information is available, these colors can be used to color items in the treemap. By default, the "All Activity" color is shown for any item that was encountered during a trace. As you select recordings in the trace controls, their colors will override the "all" color. Selecting multiple recordings will cause the treemap to use the "Overlaps" color for nodes that were encountered by more than one of the selected recordings. Recordings are explained in further detail in the trace controls section. In addition to coloring, each node that was encountered by a recording makes a note of which recording(s) encountered it in its tooltip.

##Trace Controls TODO