jTracer  1.03
Stack trace visualization tool
Overview

1. Introduction


1.1. Description

Project jTracer is a stack trace visualization utility for libcsdbg. In other words, it acts as a TCP/IP server for libcsdbg clients, that connect to it and transfer their trace data, either C++ exception stack traces or generic thread stack traces and whole process stack dumps. This functionality is generally very useful during the development cycle of any C++ application, to have a way to collect centrally, organize and process libcsdbg-related debug data, but it is essential when doing cross-platform development (on a development board, a remote system, an embedded/mobile device e.t.c), where dumping data to a terminal console or a file, is not often a commodity. The rationale and motive to develop jTracer was the gdb/gdbserver pair used in that very scenario. Project jTracer fully mirrors the capabilities of libcsdbg, to debug single or multithreaded or even multiprocess applications, with any kind of binary formats and easy integration of shared, dynamic link libraries.

This is a comprehensive list of current and planned jTracer features:

  • Full-blown Graphical User Interface
  • Concurrent server to flawlessly interface with any number of debugged processes, over TCP/IP
  • Traces are detailed with C++ syntax highlighting
  • Easy search and navigation through trace data
  • Data transaction logging
  • Easy configurable Server and GUI through a tree of XML files
  • Support for on-the-fly pluggable configuration
  • Automatic application updates
  • Portability to all Java capable systems

Future versions are planned to support other interfaces, both through a serial line, UDP/IP and Unix sockets and pipes.


1.2. Licence and details

jTracer is currently published as an Open Source project, licenced under the GNU General Public License version 3.0 (GPLv3), copyright belongs to Tasos Parisinos who develops, maintains and documents the project. Version numbering uses three numbers, major, minor and subminor. The subminor version is often omitted if it is zero. The current jTracer version is 1.03. Major project updates are related with multiple feature addition, significant changes in the GUI, major bug fixes or overall optimizations. Minor updates usually add minor features (or major features that were almost ready to be included in the major release but didn't), minor bug fixes, typos and documentation updates or entities that need to be tested for feedback. Subminor releases are stable beta snapshots of the current code development status, with the last additions since the last minor update.

The following are locations essential to the development of jTracer:



2. Download and installation


The current (beta) version of jTracer, version 1.03 (release date February 11th 2014).

This beta release adds an installer (jar autodeflated executable) that is expected to work well (although not all its features are implemented) with Linux and Windows (both 32 and 64) systems. The implementation of the installer mandates the use of Java 1.7. Apart from the source code and the old build system that is kept as it was, now two precompiled distributions for jTracer-1.03 are also downloadable one for Linux and one for Windows platforms. Next releases will embed these two installers into one. The installer itself will gradually involve to a separate generic purpose jar installer.

The latest source distribution is jTracer-1.03.tar.bz2
Alternatively, if you've already got the previous version (1.02) you can patch it to upgrade it to the latest release:

If you have both these files in the same directory, to apply the patch, execute:

tar -xjpf jTracer-1.02.tar.bz2
cd jTracer-1.02
patch -p1 < ../upgrade-1.03.patch

The project documentation can be recreated (with doxygen) in the source code distributions. It can also be separately downloaded in HTML: api-ref-jTracer-1.03.tar.bz2

The new binary distributions (installers) are available for Windows and Linux systems as two individual files:

If you want an overview of all project files check the libcsdbg project repository at sourceforge.net. Click on any file's info icon and obtain its SHA1 or MD5 checksum to verify the file you've downloaded.

Note

After you download any project file, remember to subscribe/follow jTracer in order to receive notification about new releases, updates, news, announcements and other jTracer related material in your mailbox. The easiest way to do so is to visit the jTracer project page at freecode.com and click on 'follow'


2.1. Compiling the sources (Linux/Unix)

jTracer although portable to all Java capable platforms at source level, as this is still a beta version, expect the build system and setup tools to be a little rough. Currently only a Makefile and a build script for Linux or Cygwin are offered for source level compilation. If you know how to use the Java Development Kit (JDK) it will be easy for you to replicate the steps needed to compile and install jTracer on your system.

After you download the source distribution, you need at least the following to compile the application or generate the project documentation:

  • JDK 1.7+
  • GNU make
  • UNIX standard tools such as rm, echo, mkdir, cd, cp, mv, grep, tar
  • You will need doxygen and graphviz, to recreate the project documentation

Unpack the archive, unless you already have done that. If you want to recreate the documentation you must unpack the tarball in /devel (or change the paths in the doxygen configuration files, more on this later):

mkdir -p /devel
mv jTracer-$VERSION.tar.bz2 /devel
cd /devel
tar -xjpf jTracer-$VERSION.tar.bz2

Then compile and install it (the JDK programs, javac, java and jar must be in your path!):

cd jTracer-$VERSION
sh ./build

The build script should compile without problems and install jTracer application and other project files with /usr as the prefix and your home directory as the resource, theme, log and configuration prefix (~/.jTracer). For an overview of all build script options and modes of operation use:

sh ./build -h
Usage: build [-c] [-k] [-s] [-d] [-h]

build will compile and install its target by default.
The following options change the default behaviour:

-c  Clear the source tree (make clean)
-k  Keep the current installation
-s  Don't parallelize compilation on multicore systems
-d  Create/update the documentation (make doc)
-h  Show this message

Although the build script can do all that you may need, to compile and install or uninstall, recreate the documentation or clear the source tree by calling the equivalent Makefile targets (in the right order), it is essential to describe these individual targets.

First of all clear the source tree from built binaries and documentation:

make clean

Compile the sources (the result binaries are stored in ./.bin):

make

Install:

make install

Optionally, generate the user manuals. This will create the API reference in HTML under ./doc. To see the HTML documentation, just point a browser to the file index.html in the ./doc/api-ref-jTracer-$VERSION directory.

make doc

Finally, if you need to uninstall all jTracer-related files from your system:

make uninstall


2.2. Installing using the installer (Windows/Linux/Unix)

To install from the binary distribution, all you have to do after you download the proper file for your platform and execute it (double click must suffice). Your system must be equiped with at least jre (Java Runtime Environment) 1.7
. Follow the wizard, to complete the installation. Currently desktop or other links (except a Linux bash script) are not created so to start jTracer, you must navigate to the installation prefix directory and invoke jTracer-1.03.jar (via console or double click).



3. Troubleshooting


3.1. Bug reports

Bugs are tracked in the tickets section of the libcsdbg page at sourceforge.net. Before submitting a new bug, first search through all the tickets (open and closed), if the same bug has already been submitted by others. If you believe you have found a new bug, please report it! If you are unsure whether or not something is a bug, you may ask help on the users forums first (subscription is not required, the forums are moderated).

So, you think you found a bug? You should report it either on the user forums or by sending an email to the project admin tasos42@users.sourceforge.net.

If you send only a (vague) description of a bug you are usually not very helpful and it will cost much more time to figure out what you mean. In the worst-case, your bug report may even be completely ignored, so always try to include the following information in your bug report:

  • The version of jTracer you are using (see the About dialog if unsure)
  • The name and version number of your operating system
  • The configuration you use
  • Possibly, the libcsdbg request that crashed jTracer

The easiest way for us to fix bugs is if you can attach a small example that demonstrates the problem you have to the bug report, so we can reproduce it on our machines. Please make sure the example is valid source code and that the problem is really captured by the example. If you intend to send more than one file please zip or tar the files together into a single file for easier processing.

You can (and are encouraged to) add a patch for a bug. If you do so please use PATCH as a keyword in the bug entry form or in the email subject. If you have ideas how to fix existing bugs and limitations please discuss them on the users forums. For patches please use diff -uprN or include the files you modified.


3.2. How to contribute

Donate time

You can contribute your time by helping with programming, testing and filing bug reports, improving documentation, translations or by answering questions on the mailing list. We always welcome users whose only contribution is simply using jTracer, giving us feedback on how to improve it and telling others about it. Thank you for supporting jTracer.

Donate money

If you don't have time to help but do find jTracer useful, then please consider making a financial donation. This will help to pay the bills and motivate us to contine working on jTracer. You can do so using the Paypal account indicated on the project page at sourcefore.net, or contact us for other payment methods.



4. Usage


Execute jTracer (/usr/bin/jTracer by default), this launches the application. As during compilation/installation, the JDK or the Java Runtime Environment (JRE) (version 1.6+) executables (java) must be in your path. The GUI is really very straightforward. All you have to do is start a server (The default configuration, binds the server to all local interfaces at port 4242). Then it's up to libcsdbg debugged applications to start sending trace data to jTracer. The easiest way to test functionality and get used to the jTracer GUI, is to try the libcsdbg example executables that implement LDP clients. You must have installed version 1.21 (at least) of libcsdbg for this to function properly.