1 LTTng-UST Java Agent Test Package
2 =================================
4 This git tree contains integration tests and benchmarks for the
5 [LTTng-UST](https://lttng.org/) Java Agent. It requires many additional
6 dependencies compared to the library itself, so it is shipped as a separate
14 * [Apache Maven](https://maven.apache.org/) 3.0+
15 * A recent version of [LTTng-Tools](https://lttng.org/download/)
16 * A recent version of [Babeltrace 2.x](http://www.efficios.com/babeltrace)
17 * A git branch or version of LTTng-UST you want to test
19 For example, on Ubuntu you can use the
20 [LTTng PPA](https://launchpad.net/~lttng/+archive/ubuntu/ppa), then Maven and
21 OpenJDK from the main repository:
23 sudo apt-add-repository ppa:lttng/ppa
25 sudo apt-get install lttng-tools babeltrace2 maven openjdk-8-jre
27 Also make sure `mvn -version` reports a `Java version: 1.8` or higher. If it
28 does not, you may need to set your `JAVA_HOME` accordingly.
34 First you need to `make install` the LTTng-UST git branch you want to test.
37 git clone git://git.lttng.org/lttng-ust.git
39 (do some modifications, checkout a different branch, etc.)
41 ./configure --enable-java-agent-all
45 Then, `cd` back to the directory where you cloned the present git tree, and
50 This will run all the tests on the UST agent that was `make install`'ed. Tests
51 will be skipped if they cannot find their required classes or native libraries,
52 so make sure the output mentions succesful tests and not skipped ones.
54 Please make sure you have no `lttng` session active prior to or during the
55 tests, or it might interfere with the test runs!
57 Detailed JUnit test reports will be available under
58 `lttng-ust-java-tests-{jul|log4j}/target/failsafe-reports/`
64 By default, the tests will look for the Java and JNI libraries in the default
65 locations of `make install` (`/usr/local/lib`, `/usr/local/share/java`, etc.)
67 If for example, you installed into the `/usr` prefix instead of `/usr/local`,
68 you can use the following properties to specify different locations for the
69 lttng-ust-agent-java jars:
72 -Dcommon-jar-location=/usr/share/java/lttng-ust-agent-common.jar \
73 -Djul-jar-location=/usr/share/java/lttng-ust-agent-jul.jar \
74 -Dlog4j-jar-location=/usr/share/java/lttng-ust-agent-log4j.jar \
75 -Dlog4j2-jar-location=/usr/share/java/lttng-ust-agent-log4j2.jar
77 To specify a different locations for the JNI .so libraries, you can set the
78 `-Djava.library.path` property on the JVM:
80 mvn (...) -DargLine=-Djava.library.path=/usr/lib
82 Note: do not use `MAVEN_OPTS` to set the library path, since the `argLine`
83 property defined in the build will overwrite it.
86 ----------------------
88 This test suite is comprised of integration tests. We use the failsafe
89 maven plugin [1]. To run a single test, one can use the test class name and the
92 mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false
94 The `-DfailIfNoTests=false` argument is necessary otherwise maven will fail on
95 the first test set that is empty. See [2] for more info.
98 [1] http://maven.apache.org/surefire/maven-failsafe-plugin/index.html
99 [2] http://maven.apache.org/surefire/maven-failsafe-plugin/examples/single-test.html
102 ----------------------
104 Note that for most tests, the test itself is the traced application.
105 The fastest and "easiest" way of putting a breakpoint is to use eclipse.
107 Download eclipse (for java dev).
108 Import a maven project that points to this repo:
110 File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects
111 Point the root directory to this repo. Select all projects. Finish
113 Setup the Debug Configuration:
115 Run -> Debug Configurations.
116 Select Remote Java Application.
117 Press the New Configuration button.
118 Give it the name "Remote lttng maven".
119 Select the project and select `lttng-tools-java`
121 Go in the Source tab.
122 Click Add -> Java project -> Select all
126 Now let's run a single test with debug:
128 mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug
132 Listening for transport dt_socket at address: 5005
134 Now go back to eclipse:
136 Navigate to where you want to put a break point. For example, JulAppContextOrderingIT.registerAgent.
137 Ctrl + shift + b can be used to set a tracepoint at the desired line.
139 Then attach to the debugger:
141 Run -> Debug Configurations.
142 Select on the right "Remote lttng maven"
145 You should hit the breakpoint at some point and from there use steps etc.
147 If you want to debug lttng-ust, you need to insert a breakpoint at a valid point
148 in time for the test and then use gdb to hook yourself to the java process.
149 From there debugging is the same as any C application.
150 You will need to ignore SIGSEV from java under gdb:
152 handle SIGSEGV nostop noprint pass
154 Running the benchmarks
155 ----------------------
157 By default only the unit/integration tests are run. To also run the benchmarks,
158 run Maven with the `benchmark` profile, as follows:
160 mvn clean verify -Pbenchmark
162 The benchmark results should be part of the standard output.