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 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
 110     File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects
 111     Point the root directory to this repo. Select all projects. Finish
 112
 113 Setup the Debug Configuration:
 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
 125
 126 Now let's run a single test with debug:
 127
 128     mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug
 129
 130 Wait for:
 131
 132     Listening for transport dt_socket at address: 5005
 133
 134 Now go back to eclipse:
 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.
 138
 139 Then attach to the debugger:
 140
 141     Run -> Debug Configurations.
 142     Select on the right "Remote lttng maven"
 143     Click Debug
 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.
 150 You will need to ignore SIGSEV from java under gdb:
 151
 152     handle SIGSEGV nostop noprint pass
 153
 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