| 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/) |
| 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 |
| 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 |
| 25 | sudo apt-get install lttng-tools babeltrace2 maven openjdk-8-jre |
| 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 | |
| 57 | Detailed JUnit test reports will be available under |
| 58 | `lttng-ust-java-tests-{jul|log4j}/target/failsafe-reports/` |
| 59 | |
| 60 | |
| 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 | |
| 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 |
| 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 | |
| 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 | Running tests by tags |
| 102 | --------------------- |
| 103 | |
| 104 | Tests can also be filtered by Junit tags or tag expressions [1], for example to |
| 105 | run only the Log4 1.x agent tests: |
| 106 | |
| 107 | mvn clean verify -Dgroups='agent:log4j' |
| 108 | |
| 109 | Or to exclude the tests of the Log4j2 domain: |
| 110 | |
| 111 | mvn clean verify -Dgroups='!domain:log4j2' |
| 112 | |
| 113 | [1] https://junit.org/junit5/docs/current/user-guide/#running-tests-tags |
| 114 | |
| 115 | Debugging a test |
| 116 | ---------------------- |
| 117 | |
| 118 | Note that for most tests, the test itself is the traced application. |
| 119 | The fastest and "easiest" way of putting a breakpoint is to use eclipse. |
| 120 | |
| 121 | Download eclipse (for java dev). |
| 122 | Import a maven project that points to this repo: |
| 123 | |
| 124 | File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects |
| 125 | Point the root directory to this repo. Select all projects. Finish |
| 126 | |
| 127 | Setup the Debug Configuration: |
| 128 | |
| 129 | Run -> Debug Configurations. |
| 130 | Select Remote Java Application. |
| 131 | Press the New Configuration button. |
| 132 | Give it the name "Remote lttng maven". |
| 133 | Select the project and select `lttng-tools-java` |
| 134 | Set the port to 5005 |
| 135 | Go in the Source tab. |
| 136 | Click Add -> Java project -> Select all |
| 137 | Click Apply |
| 138 | Click Close |
| 139 | |
| 140 | Now let's run a single test with debug: |
| 141 | |
| 142 | mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug |
| 143 | |
| 144 | Wait for: |
| 145 | |
| 146 | Listening for transport dt_socket at address: 5005 |
| 147 | |
| 148 | Now go back to eclipse: |
| 149 | |
| 150 | Navigate to where you want to put a break point. For example, JulAppContextOrderingIT.registerAgent. |
| 151 | Ctrl + shift + b can be used to set a tracepoint at the desired line. |
| 152 | |
| 153 | Then attach to the debugger: |
| 154 | |
| 155 | Run -> Debug Configurations. |
| 156 | Select on the right "Remote lttng maven" |
| 157 | Click Debug |
| 158 | |
| 159 | You should hit the breakpoint at some point and from there use steps etc. |
| 160 | |
| 161 | If you want to debug lttng-ust, you need to insert a breakpoint at a valid point |
| 162 | in time for the test and then use gdb to hook yourself to the java process. |
| 163 | From there debugging is the same as any C application. |
| 164 | You will need to ignore SIGSEV from java under gdb: |
| 165 | |
| 166 | handle SIGSEGV nostop noprint pass |
| 167 | |
| 168 | Running the benchmarks |
| 169 | ---------------------- |
| 170 | |
| 171 | By default only the unit/integration tests are run. To also run the benchmarks, |
| 172 | run Maven with the `benchmark` profile, as follows: |
| 173 | |
| 174 | mvn clean verify -Pbenchmark |
| 175 | |
| 176 | The benchmark results should be part of the standard output. |
| 177 | |