INTELLISYS JAVA LENS

LENS is a JVMTI based Java concurrency profiler. For other recent  intelliSys products, visit http://www.intelliSys.com.cn
The following article provides a guided tour of the features of intelliSys LENS. intelliSys LENS requires intelliSys ORCA agent to present. To acquire ORCA, refer to the download page.

GENERATING TRACE AND SUPPORT FILES

intelliSys LENS uses a JVMTI-based agent (ORCA) to generate program trace files, class and method tables. The trace file (.orca) is simply a text file conforming to the ORCA specification found in the documentation section. It contains a series of concurrency related events along with details. To enable accurate stack trace source file look up, LENS also requires ORCA generated class table (.classtable) and method (.method) files to present in the same folder as their corresponding trace file.

To generate these files, simply attach the ORCA agent to the JVM instance.

ANALYZING TRACE EVENTS

The LENS program starts by searching for ORCA traces in its start up directory. It may be possible that no trace is present. In that case LENS will stay in the start up animation until a proper ORCA file is selected by pressing the (+) button. LENS remembers the last opened file, so the next time LENS will start where you left.

The following uses the PINGPONG trace as an example. To acquire PINGPONG and other sample traces, refer to the download page.

Once the trace file is loaded, LENS provides 2 main views:  a THREAD and a RESOURCE view. The THREAD view focuses on threads-as-subject, and resource-as-object and the RESOURCE view is exactly the opposite. Each thread is given a friendly name or an ID if friendly name is not present.

LENS uses the notion of subject and object for each trace event. Since a single trace event can be interpreted as "a thread did something" or "a resource was used", LENS formulates this by specifying subject as a thread when in thread view, a resource when in resource view, and object as a resource in thread view, a thread in resource view.

To the right are series of events associated with that subject, arranged by time. Lighter blue means the subject is not blocked or is idle (when the subject is a resource, meaning no thread is currently using the resource). Darker blue shows contended time series that cannot be shown (too many events to show in this period). Blank event means the subject is blocked, or is being held by some thread (in the case of a resource). Expanding entity in the viewer to reveals other three subviews, namely, the stack trace for the event you clicked on, if available; the resource that the current subject is waiting for (if the subject is a thread) or what threads are contending for this resource at the moment (if the subject is a resource); and another NAVIGATION panel that helps you focus on the selected event or find raw event in the trace file. Clicking on a stack trace will open a code viewer box that shows the source file and lines. Clicking on resource view item will pop up an event filter that helps you highlight all relevant event. Hover mouse on the list of actions in the NAVIGATION panel to see how they transform the current view.

The top range slider acts as a time stamp filter. To filter to a specific time or to uncollapse collapsed events, move the range selector to appropriate positions then click apply. Other filters are available in LENS as well. For example, you can search for a particular thread, a particular resource, or a particular type of event. Bring up search anywhere by pressing CTRL+F in the LENS main program and supply required information.

Events that meet the criterion will be highlighted in red. Note that searches are additive, a new search will no erase items highlighted by previous searches. To clear all highlights, press CTRL+F then click on CLEAR SEARCH.

Within a search, criterion is ANDed to form a compound delegate. Leave empty to match "all" events. When testing whether an event meets a criterion, the test succeeds if the actual value is a substring of the input value ("contains").

Note the search dialogue is populated automatically using Reflection, you must specify texts exactly as desired. If the reflected property is a complex object, its ToString method is called.

The setting panel on the upper right corner gives options like search path. Search path is where LENS finds appropriate source files. The default search path contains the current directory, so unnecessary to respecify it again. Search path is separated by semicolon.

The smartpanel on the right gives contextual statistics on the selected subject. The smart panel refreshes itself automatically when time filter is applied, so it always reflects the stats for the chosen time period.

At anytime, you can switch to another file by pressing the switch button on the upper left corner of LENS. Select any ORCA file to switch to and ORCA will replace the current file with the chosen one.

The next section details logistics.

QUESTIONS, ISSUE TRACKING, BUGS, AND FEATURE SUGGESTION

LENS uses ClickOnce to deploy itself, so it receives updates automatically. However, you need to manually update ORCA at this website.

If you'd like to report bugs, suggest features, please refer to corresponding pages of the site.

FAQ

1. What MethodName should I put in the Search Dialogue?

-> Currently we support method names as-is, therefore, the text you put in must be accurate. For a list of method names accepted, refer to the specification, or easier, just hover mouse on other events and see what event names are used there.

2. Why Can't I bring up search?

-> We use contextual information to populate search dialogue, therefore, you must first click on an event and press CTRL+F to bring up search dialogue.

3. The event rectangle is too small, how can I make it larger?

-> There're two ways to do it: by render zoom or by time filtering. When you click on an event, center your mouse on that event and scroll mouse wheel. Notice however in this mode the event gets larger but the collapsed event is still collapsed. To uncollapse event, use the time filter, or click on the focus on the event button in the NAVIGATION panel.

4. I'd like to change the accent, how can I do that?

-> Currently there is no way to do that. Click on settings would give a stub for that, but we're just not there yet.

5. The stacktrace shows a method name followed by a -1.

-> Sometimes the stacktrace is bogus - i.e., we believed we found a stacktrace item, but it is in reality not one. In that case, we can only display the method name.

6. The resource view is inaccurate - how can thread A use the monitor for such long time?

-> This is a known limitation. ORCA cannot provide monitor release information, so LENS has to guess by checking if in the future, any thread has ever used that monitor. This simple criterion is by no means accurate. However, with other locks, such as semaphore, the resource view is accurate.

7. Why my fancy re-enterant-auto-reset-event-semaphore-slim-reader-writer-super-synchronized-spinning-lock is not present in any of the traces?

-> We added support only for Semaphore, Monitor, Object wait/notify, Thread Start/Join/Sleep/Tear down. If you really want it, let us know in the appropriate page.

8. What does the backend look like?

->You can view via the link http://huxx.me/backend.pdf, or download a copy at the downloads page. ORCA is implemented by the owner of that website.

9. Can I launch ORCA from LENS directly?

-> Although we'd like to, currently these two components are separate.

10. Can I launch LENS from OSes other than Windows?

-> Theoretically yes, if WPF is ported along with .NET. Currently, you cannot launch LENS on other OSes, but you can collect traces in other OSes with ORCA, and analyze them in a Windows PC. It is straight forward to port ORCA to other OSes, just replace the timestamping function calls.