This document describes how to install and configure the LTTv C-code library in order to load and parse LTTng traces with the Eclipse LTTng plugin.
For each trace format version (v2.3, v2.5 and/or v2.6) you want to process :
Download LTTv application, from http://git.dorsal.polymtl.ca/?p=liblttngtrace.git;a=summary
Compile it with the JNI support activated :
./configure --with-jni-interface && make && make install
Start Eclipse application making sure the library is in LD_LIBRARY_PATH.
Note: Unless you plan to process legacy traces, version 2.5 and 2.6 should be sufficient for most needs.
It didn't work? Please read “Installation steps” section.
Make sure you install the latest version last (currently v2.6).
LTTng and LTTv are mostly coded in C (with some parts in even more evil stuff) so their functionalities are not directly available in Java. Also, for the sake of performance, it was decided to re-use the native, multi-platform C library for the low-level functions rather than re-implement them in Java. Also, the C library is under constant development and it would have been a bad idea to branch this one just yet.
So right now, the normal path for an event through LTTng would be the following :
Linux Kernel -> Trace Directory
(Trace Directory read by) LTTv C Library -> JNI (C side) -> JNI (Java Side) -> Eclipse LTTng Plugin
(Note that the kernel is only used to record at trace).
For all these reasons, the LTTv C library and a JNI (Java Native Interface) is needed for java to process LTTng trace. The JNI itself, however, is already included in LTTv and it should be easy to build and to install (using this very installation guide).
First on all, we need to download and compile the source of the LTTv application, with the JNI support enabled. To do so, follow the 4 steps described in this section.
Note : LTTv is responsible of handling the trace format for Eclipse. However, as the trace format changed overtime, you might need to compile several versions of LTTv if you plan to support multiple trace formats. Each “branch” of LTTv should tell you by its name which version of the LTTng trace it supports. If you did not generate a trace already, you might want to stick with the latest LTTv version, otherwise, it is recommended to compile all available versions (currently v2.3, v2.5 and v2.6).
NOTE: If you don't know which trace format you need, you may want to get all of them to support multiple versions of traces (2.5 and 2.6 are more or less mandatory). Just perform the following instructions for each trace format.
In all case, make sure you install the latest version last (currently v2.6).
Downloading LTTv
There are actually three variants of the LTTv library available for download.
- Beta JNI build (git) (PLEASE USE THIS)
This is the very beta tree of LTTv that include the newest JNI changes. It is under constant development, so there might be some bugs left, but it contains the newer JNI interface, which is probably what you need.
This is definitely what you should use. You can get it from :
http://git.dorsal.polymtl.ca/?p=liblttngtrace.git;a=summary
Then, in the “heads” section (below the “shortlog”section), click on the trace format that suits your need . In the new download page, click the “snapshot” link of the top entry (with a marker of the form 'traceformat-n.n') to download the corresponding archive.
- Development build (git)
This is the release candidate of the LTTv application. It contains features that are under development or too experimental to make it to the main tree. It also includes the JNI interface that you need to use Eclipse; however, this branch could be a little late on the beta, so use at your own risk.
If
you want to try, get it from :
http://lttng.org/cgi-bin/gitweb.cgi?p=lttv.git;a=summary
Then, in the “heads” section (below the “shortlog” and “tags”section), click on the trace format that suits your need . In the new download page, click the “snapshot” link of the top entry (with a marker of the form 'traceformat-n.n') to download the corresponding archive.
Then, in the “head” section, click on the traceformat that suite your need and then choose “snapshot” to download its archive.
- Stable release
This is the main LTTv tree. Actually missing the JNI fonctionnality but this might be added soon. Until this is done, you should stick with development version.
If you want to try it anyways, you can get it from http://www.lttng.org/?q=node/3
Then, select “Download the latest lttv-[version].tar.gz” in the menu and pick the most recent (usually on top) release.
Decompressing the archive(s)
You now need to archive files where you want them and to uncompress them. You need to do this for each LTTv version you downloaded.
The way to do it in command line would be something like :
mv archive_name.tar.gz /where/you/want
tar -xvzf archive_name.tar.gz
As example, this is what I would do for myself :
mv liblttngtrace-bcaf565bbfb26d0ac7e4647528230feb61443a01.tar.gz /home/william
tar -xvzf liblttngtrace-bcaf565bbfb26d0ac7e4647528230feb61443a01.tar.gz
Configuration
At First
Enter one of the uncompressed directory, you should use a command like :
cd liblttngtrace
(Of course “liblttngtrace” need to be the name of the uncompressed directory).
If you are using any “Development build” (first or second choice of the download section), before doing anything, you need to do the following :
./autogen.sh
You can safetly ignore any errors you get there, we will take care of them next.
Dependencies
To build LTTv, the folowing dependencies need to be met. A (very) incomplete list is the following. Most distribution should have most of this stuff, except maybe gtk-dev, glib-dev and libopt that are probably missing on most systems.
Install the missing dependencies using your distribution package manager and then jump to the “configure script” step.
libtool (and its dependencies like autotools, autoconf, automake and such...)
(Debian/Ubuntu : libtool)
(Fedora/Redhat : libtool-2)
gcc 3.2 (or better)
(Debian/Ubuntu : gcc-3.2)
(Fedora/Redhat : gcc-3.2)
gtk 2.4 development libraries (or better)
(Debian/Ubuntu : libgtk2.0, libgtk2.0-dev)
(Fedora/Redhat : gtk2, gtk2-devel)
glib 2.4 development libraries (or better)
(Debian/Ubuntu : libglib2.0-0, libglib2.0-dev)
(Fedora/Redhat : glib2, glib2-devel)
libpopt development libraries
(Debian/Ubuntu : libpopt0, libpopt-dev)
(Fedora/Redhat : popt)
libpango development libraries
(Debian : libpango1.0, libpango1.0-dev)
(Fedora : pango, pango-devel)
libc6 development librairies
(Debian : libc6, libc6-dev)
(Fedora
: glibc, glibc)
Configure step
LTTv have several compile options that you can turn on/off. To see a full list, type the following :
./configure
–help
The following option is essential for Eclipse to work :
--with-jni-interface
Build JNI interface between C and java. Need java include files.
[default=no]
The following options may be useful for you as well :
1) --prefix=PREFIX install architecture-independent files in PREFIX [/usr/local]
2) --with-lttv Build whole LTTV system, as opposed to only the trace reading library [default=yes]
3) --with-java-jdk=DIR Use java jdk from DIR. Ex : $JAVA_HOME.
1) Change PREFIX to something in your home if you don't have root access on your system.
Use a flag like : --prefix=/home/your_name/a_directory
2) Unless you need LTTv Gtk gui, you better turn off turn off LTTv UI compilation.
Use the flag : --without-lttv
3) On some (most?) system, configure will need you to indicate where it can find the java JDK to compile the JNI.
Use a flag like : --with-java-jdk=/where/java-jdk/is
As example, here is what I would use :
./configure --prefix=/home/william/apps --without-lttv --with-java-jdk=/usr/local/jdk1.6.0_13 --with-jni-interface
Fix any missing dependencies errors and move to the next step.
Build and install
Now that program is correctly configured, we can try to build it. Type the following command (this can take a while) :
make
When it is over, make sure there were no error during the compilation and issue the following command :
sudo make install
OR if you don't have root acess AND changed the --prefix=PREFIX flag during the configuration :
make install
LTTv should now be installed on your system.
Get back to the step 3) “Configuration” and do the same operations for all the LTTv version that were downloaded to install them on your system.
Set library path
Now that LTTv is installed, we need to make sure Eclipse can find its library easily. The best way to do so is to ajust the LD_LIBRARY_PATH.
The following should work on most system if your shell is BASH or KSH (in case of doubt try this one) :
export LD_LIBRARY_PATH=”/usr/local/lib:$LD_LIBRARY_PATH”
OR if you changed the --prefix=PREFIX flag during the configuration :
export LD_LIBRARY_PATH=”/where_you_set_prefix/lib:$LD_LIBRARY_PATH”
If you are using a CSH or TCSH shell, this might be what you need :
setenv LD_LIBRARY_PATH /usr/local/lib\:$LD_LIBRARY_PATH
OR if you changed the --prefix=PREFIX flag during the configuration :
setenv LD_LIBRARY_PATH /where_you_set_prefix/lib\:$LD_LIBRARY_PATH
If you have root access on the system, if can be a good idea to run ldconfig as well :
sudo ldconfig
Note these settings will disapears on logout, you mght consider adding this to your autostart or setting it system wide!
You should be ready to start Eclipse now.
When
trying to start LTTng in Eclipse, I end up with the following
exception :
org.eclipse.linuxtools.lttng.trace.LTTngTraceException:
Failed to initialize library! Is the trace version supported?
Make sure you have the correct LTTv library compiled. (openTrace)
This mean you do not have the correct LTTv library available on your system. Go back to the section "1) – Download” and make sure you downloaded (and installed) the correct version of LTTv to support the format of trace you want to read. As example, if your trace is of LTTng format 2.3, you will need to download and install the archive marked as “traceformat-2.3”.
When
trying to import a trace, I get an error message and I have one of
the following exception in the Eclipse Console :
org.eclipse.linuxtools.lttng.trace.LTTngTraceException:
ERROR : Unrecognized/unsupported trace version.
OR
org.eclipse.linuxtools.lttng.trace.LTTngTraceException: ERROR : Call to JniTraceVersion() failed.
In that case, either your LTTv version is very old and does not recognize your trace version or you are using a very new trace version that is not yet supported. You probably want to check if there is a newer version of LTTv that you could use. Please refer to the section "1) – Download” for the correct links.
When
trying to start LTTng in Eclipse, I end up with the following
exception :
Exception
in thread "main" java.lang.UnsatisfiedLinkError: no
lttvtraceread in java.library.path
This basically mean that Java can not find the C library you just compile. To find any C library, java would normally need to be passed a flag like “-Djava.library.path=/somewhere/lib” but there seems to be a bug in Eclipse about it, as defined here : https://bugs.eclipse.org/bugs/show_bug.cgi?id=290068
Therefore, the workaround is to make sure to pass a correct LD_LIBRARY_PATH to Eclipse (see section above about “Set library path”). The best way to make sure the flag is corerctly passed is to add it in front of the command that is called to start Eclipse, on the command line or in the desktop shortcut itself.
As example, here is the shortcut I use to call Eclipse :
export LD_LIBRARY_PATH="/usr/local/lib"; /usr/local/eclipse/eclipse
I
did what you said in 1) but I'm still getting the same error
:
Exception
in thread "main" java.lang.UnsatisfiedLinkError: no
lttvtraceread in java.library.path
If
your LD_LIBRARY_PATH is correct, then the only reason why you might
get this error is that you did not compile the JNI interface inside
LTTv.
Go back to “Installation steps” and make sure
you used the development version of LTTv and that you compiled it
with the --with-jni-interface flag.
When I run LTTng in Eclipse, at some point, I am getting an error like this :
Exception in thread "main" java.lang.Error: Unresolved compilation problem:
The method ltt_someFunction() is undefined for the type JniXYZ
This may happen if the LTTv version you are using is not recent enought. Make sure you are using the latest development version, recompile the latest one if needed. If this doesn't work, make sure you use the “Beta” JNI Build, as described in “Download” section. If nothing work, please submit a bug report.