Commit | Line | Data |
---|---|---|
08d409fb AM |
1 | LTTng-UST Java Agent Test Package |
2 | ================================= | |
3 | ||
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 | |
7 | package for now. | |
8 | ||
9 | ||
10 | Prerequisites | |
11 | ------------- | |
12 | ||
13 | * Java 1.8 | |
14 | * [Apache Maven](https://maven.apache.org/) 3.0+ | |
15 | * A recent version of [LTTng-Tools](https://lttng.org/download/) | |
fd2b8059 | 16 | * A recent version of [Babeltrace 2.x](http://www.efficios.com/babeltrace) |
08d409fb AM |
17 | * A git branch or version of LTTng-UST you want to test |
18 | ||
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: | |
22 | ||
23 | sudo apt-add-repository ppa:lttng/ppa | |
24 | sudo apt-get update | |
fd2b8059 | 25 | sudo apt-get install lttng-tools babeltrace2 maven openjdk-8-jre |
08d409fb AM |
26 | |
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. | |
29 | ||
30 | ||
31 | Usage | |
32 | ----- | |
33 | ||
34 | First you need to `make install` the LTTng-UST git branch you want to test. | |
35 | For example: | |
36 | ||
37 | git clone git://git.lttng.org/lttng-ust.git | |
38 | cd lttng-ust/ | |
39 | (do some modifications, checkout a different branch, etc.) | |
40 | ./bootstrap | |
41 | ./configure --enable-java-agent-all | |
42 | make | |
43 | sudo make install | |
44 | ||
45 | Then, `cd` back to the directory where you cloned the present git tree, and | |
46 | issue a | |
47 | ||
48 | mvn clean verify | |
49 | ||
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. | |
53 | ||
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! | |
56 | ||
7b82be36 | 57 | Detailed JUnit test reports will be available under |
4821eac9 | 58 | `lttng-ust-java-tests-{jul|log4j}/target/failsafe-reports/` |
08d409fb AM |
59 | |
60 | ||
ca5cfa43 AM |
61 | Setting library paths |
62 | --------------------- | |
63 | ||
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.) | |
66 | ||
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: | |
70 | ||
eca1a136 MJ |
71 | mvn clean verify \ |
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 | |
ca5cfa43 AM |
76 | |
77 | To specify a different locations for the JNI .so libraries, you can set the | |
78 | `-Djava.library.path` property on the JVM: | |
79 | ||
80 | mvn (...) -DargLine=-Djava.library.path=/usr/lib | |
81 | ||
82 | Note: do not use `MAVEN_OPTS` to set the library path, since the `argLine` | |
83 | property defined in the build will overwrite it. | |
84 | ||
0b7cb727 JR |
85 | Running a single test |
86 | ---------------------- | |
87 | ||
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 | |
90 | following command: | |
91 | ||
92 | mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false | |
93 | ||
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. | |
96 | ||
97 | ||
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 | |
100 | ||
101 | Debugging a test | |
102 | ---------------------- | |
103 | ||
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. | |
106 | ||
107 | Download eclipse (for java dev). | |
108 | Import a maven project that points to this repo: | |
109 | ||
9a24d281 JRJ |
110 | File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects |
111 | Point the root directory to this repo. Select all projects. Finish | |
0b7cb727 JR |
112 | |
113 | Setup the Debug Configuration: | |
9a24d281 JRJ |
114 | |
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` | |
120 | Set the port to 5005 | |
121 | Go in the Source tab. | |
122 | Click Add -> Java project -> Select all | |
123 | Click Apply | |
124 | Click Close | |
0b7cb727 JR |
125 | |
126 | Now let's run a single test with debug: | |
127 | ||
9a24d281 | 128 | mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug |
0b7cb727 JR |
129 | |
130 | Wait for: | |
9a24d281 JRJ |
131 | |
132 | Listening for transport dt_socket at address: 5005 | |
0b7cb727 JR |
133 | |
134 | Now go back to eclipse: | |
9a24d281 JRJ |
135 | |
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. | |
0b7cb727 JR |
138 | |
139 | Then attach to the debugger: | |
9a24d281 JRJ |
140 | |
141 | Run -> Debug Configurations. | |
142 | Select on the right "Remote lttng maven" | |
143 | Click Debug | |
0b7cb727 JR |
144 | |
145 | You should hit the breakpoint at some point and from there use steps etc. | |
146 | ||
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. | |
964084b4 JRJ |
150 | You will need to ignore SIGSEV from java under gdb: |
151 | ||
152 | handle SIGSEGV nostop noprint pass | |
ca5cfa43 | 153 | |
08d409fb AM |
154 | Running the benchmarks |
155 | ---------------------- | |
156 | ||
157 | By default only the unit/integration tests are run. To also run the benchmarks, | |
158 | run Maven with the `benchmark` profile, as follows: | |
159 | ||
160 | mvn clean verify -Pbenchmark | |
161 | ||
162 | The benchmark results should be part of the standard output. | |
163 |