README.md

   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