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](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 babeltrace 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
  76 To specify a different locations for the JNI .so libraries, you can set the
  77 `-Djava.library.path` property on the JVM:
  78
  79     mvn (...) -DargLine=-Djava.library.path=/usr/lib
  80
  81 Note: do not use `MAVEN_OPTS` to set the library path, since the `argLine`
  82 property defined in the build will overwrite it.
  83
  84 Running a single test
  85 ----------------------
  86
  87 This test suite is comprised of integration tests. We use the failsafe
  88 maven plugin [1]. To run a single test, one can use the test class name and the
  89 following command:
  90
  91    mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false
  92
  93 The `-DfailIfNoTests=false` argument is necessary otherwise maven will fail on
  94 the first test set that is empty. See [2] for more info.
  95
  96
  97 [1] http://maven.apache.org/surefire/maven-failsafe-plugin/index.html
  98 [2] http://maven.apache.org/surefire/maven-failsafe-plugin/examples/single-test.html
  99
 100 Debugging a test
 101 ----------------------
 102
 103 Note that for most tests, the test itself is the traced application.
 104 The fastest and "easiest" way of putting a breakpoint is to use eclipse.
 105
 106 Download eclipse (for java dev).
 107 Import a maven project that points to this repo:
 108
 109    File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects
 110    Point the root directory to this repo. Select all projects. Finish
 111
 112 Setup the Debug Configuration:
 113    Run -> Debug Configurations.
 114    Select Remote Java Application.
 115    Press the New Configuration button.
 116    Give it the name "Remote lttng maven".
 117    Select the project and select `lttng-tools-java`
 118    Set the port to 5005
 119    Go in the Source tab.
 120    Click Add -> Java project -> Select all
 121    Click Apply
 122    Click Close
 123
 124 Now let's run a single test with debug:
 125
 126    mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug
 127
 128 Wait for:
 129    Listening for transport dt_socket at address: 5005
 130
 131 Now go back to eclipse:
 132    Navigate to where you want to put a break point. For example, JulAppContextOrderingIT.registerAgent.
 133    Ctrl + shift + b can be used to set a tracepoint at the desired line.
 134
 135 Then attach to the debugger:
 136    Run -> Debug Configurations.
 137    Select on the right "Remote lttng maven"
 138    Click Debug
 139
 140 You should hit the breakpoint at some point and from there use steps etc.
 141
 142 If you want to debug lttng-ust, you need to insert a breakpoint at a valid point
 143 in time for the test and then use gdb to hook yourself to the java process.
 144 From there debugging is the same as any C application.
 145
 146 Running the benchmarks
 147 ----------------------
 148
 149 By default only the unit/integration tests are run. To also run the benchmarks,
 150 run Maven with the `benchmark` profile, as follows:
 151
 152     mvn clean verify -Pbenchmark
 153
 154 The benchmark results should be part of the standard output.
 155