User Guide

Don't use this page. Start from Home and follow the "even longer version" section links.

#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.

#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.

Aside from the three primary components, the trace details screen has a header area that holds several small (but important) components.

At the left of the header, the trace's name is displayed. If the trace happens to have the same name as another trace, it will show a warning suggesting that you change the name. You can change a trace's name by clicking on its name display in this header area.

Next to the name is the trace's creation date, and import date when it is applicable.

The header also contains an "Export" button that can be used similarly to the one in the trace list; it creates a file copy of the trace that can later be shared and imported.

The "Traces" button in the header reveals the trace list, which can be used to navigate to other traces (just like the trace list on the home screen as well as to add or import traces.

##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

The trace controls exist on the right-hand side of the trace details screen. They provide controls for starting and stopping trace connections, as well as for adding and removing "recordings" (explained below).

###About Tracing

"Tracing" (in Code Pulse's case) is the process of observing which methods are called in a Java application while that application is running. Starting the tracing process requires two primary steps:

1. Create a trace in Code Pulse - this lets Code Pulse figure out what it needs to know about the program it's about to observe, as well as how to represent it to you. Creating traces is explained in the sections above.
2. Connect the application to Code Pulse - the application you want to observe needs to know how to tell Code Pulse about what it's doing. This section explains how to set that up.

Once you decide you want to trace a Java application, navigate to the trace you created in Code Pulse, then find the "Start a trace" button in the upper-right part of the window, and click it. The button will give way to a message saying that it is "waiting for a trace connection". This means that Code Pulse is ready to listen. The next step is to get your application to talk to it. Your Code Pulse installation should have come with an agent.jar file (generally located right next to the Code Pulse executable). Locate this file, then create the following string:

"-javaagent:</path/to/agent.jar>=localhost:<port>"

Replace the </path/to/agent.jar> with the actual path in your file system to where you found agent.jar. Replace <port> with a port number. The port that Code Pulse is expecting can be found and changed via the "Options" menu at the top of the trace details screen. When you first install Code Pulse, it will probably be 8765. The port number choice is mostly arbitrary; as long as the <port> you use in the "javaagent" string is the same as the one Code Pulse expects, it should work.

Note: on some operating systems, port numbers below 1024 require higher permissions to use. Also, try to avoid ports that are already in use. For example, a web server might be using port 8080, so you wouldn't want to use port 8080 as the <port>.

Advanced Users: You could also change localhost to be an IP address. You could use this to run the traced application on one machine, and Code Pulse on another. For example, if Code Pulse is running on a machine accessible through the network at address 192.168.55.55 and listening on port 8765, you could replace localhost:<port> with 192.168.55.55:8765.

Code Pulse offers some help with the "javaagent" string if you click the "How do I make a trace connection" link while Code Pulse is waiting for a trace connection. It makes an educated guess at the path to agent.jar, and fills in the <port> with the number it is currently using.

Once you have determined your "javaagent" string, add it to the command that is used to run your Java application.

For the purposes of this example, the "javaagent" string will be "-javaagent:C:/Program Files/Code Pulse/agent.jar=localhost:8765" and the command that you would enter to run your Java application without tracing is java -jar myapp.jar. All you need to do to run the application with tracing is add the "javaagent" string as an extra argument in the command line:

java "-javaagent:C:/Program Files/Code Pulse/agent.jar=localhost:8765" -jar myapp.jar

If everything goes well, your application should start up and initiate a connection to Code Pulse. If the connection information was correct, Code Pulse will acknowledge the connection, and the "waiting for a trace connection" should be replaced with an "End Trace" button. Congratulations, you have successfully started a trace! As your application starts up, Code Pulse will start updating numbers and colors in the trace details screen, and will continue to do so as the application continues to run.

If something went wrong, you'll likely see an error message in the console when you try to run your app. Often times this happens because the connection information was wrong, or Code Pulse wasn't listening for any incoming connections at that time.

Your application should appear to run exactly as it normally does. Communicating with Code Pulse does add some overhead, so expect some slow-down, especially when the application is CPU-intensive.

As method are called during a trace, the corresponding things in the trace details page will briefly be highlighted in orange. For whichever packages or groups the method belonged to, those items will light up in the package list. Nodes in the treemap will light up as their corresponding methods are called as well.

Closing the application will cause the trace to end. Alternatively, you can click the "End Trace" button to tell your application to disconnect from Code Pulse but continue to run normally.

###Recordings

Once you are tracing a running Java application, you can start and stop "recordings". A recording remembers each method that was traced between the time it was started and the time it was stopped. Recordings are found in the trace controls area, below the legend. They can be selected in order to show their findings in the treemap and package list. To start a recording, simply click the "Start a Recording" button. (Note: the "Start a Recording" button is only available during a trace.) New recordings are untitled. You can change a recording's name at any time via the dropdown menu found on the right-hand side of the recording.

You can also stop or delete a recording from the same menu. Once a recording is stopped, it does not start again. Any new activity in the traced application will be ignored by that recording. A stopped recording remembers all activity that it saw while it was running, so it can still be selected to view its information. Deleting a recording completely removes it, and is not undoable.

Selecting a recording causes the rest of the screen to react, displaying information about the traced methods that were called during that recording. To select a recording, simply click on it. The package list will update its "Percent Coverage" column to reflect the methods covered by the selected recording. (When there is no selection, the package list shows the percent coverage of the entire trace, regardless of recordings). The treemap will update its colors to indicate which of the displayed methods were traced during the selected recording. (If multiple recordings are selected, and a method was traced by more than one of them, the treemap will use the "Overlaps" color, rather than randomly choosing a recording's color).

Recordings are combined with the "Treemap Legend" section to specify colors for the treemap to use. In the legend section, there are entries for "All Activity" and "Overlaps". The colors associated with these entries can be changed by clicking on the colored square, then choosing a color from the popup. Each recording, as well as the "Timing Filter" can have its color changed in the same manner.

The "Timing Filter" is a special recording that is always running, but only shows trace data from the "latest X amount of time". The time window it shows can be changed from its menu.