X-Git-Url: http://git.liburcu.org/?a=blobdiff_plain;f=README.md;h=cf1c566693b8c8af35620ba31a9028c01de7c3a4;hb=HEAD;hp=f944a59e34aaae05c20f6cfeae120c282bd686c3;hpb=0b7cb7270cda3d22a57943488aa122f19d3f09a8;p=lttng-ust-java-tests.git diff --git a/README.md b/README.md index f944a59..cf1c566 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Prerequisites * Java 1.8 * [Apache Maven](https://maven.apache.org/) 3.0+ * A recent version of [LTTng-Tools](https://lttng.org/download/) -* A recent version of [Babeltrace](http://www.efficios.com/babeltrace) +* A recent version of [Babeltrace 2.x](http://www.efficios.com/babeltrace) * A git branch or version of LTTng-UST you want to test For example, on Ubuntu you can use the @@ -22,7 +22,7 @@ OpenJDK from the main repository: sudo apt-add-repository ppa:lttng/ppa sudo apt-get update - sudo apt-get install lttng-tools babeltrace maven openjdk-8-jre + sudo apt-get install lttng-tools babeltrace2 maven openjdk-8-jre Also make sure `mvn -version` reports a `Java version: 1.8` or higher. If it does not, you may need to set your `JAVA_HOME` accordingly. @@ -68,10 +68,11 @@ If for example, you installed into the `/usr` prefix instead of `/usr/local`, you can use the following properties to specify different locations for the lttng-ust-agent-java jars: - mvn clean verify - -Dcommon-jar-location=/usr/share/java/lttng-ust-agent-common.jar - -Djul-jar-location=/usr/share/java/lttng-ust-agent-jul.jar - -Dlog4j-jar-location=/usr/share/java/lttng-ust-agent-log4j.jar + mvn clean verify \ + -Dcommon-jar-location=/usr/share/java/lttng-ust-agent-common.jar \ + -Djul-jar-location=/usr/share/java/lttng-ust-agent-jul.jar \ + -Dlog4j-jar-location=/usr/share/java/lttng-ust-agent-log4j.jar \ + -Dlog4j2-jar-location=/usr/share/java/lttng-ust-agent-log4j2.jar To specify a different locations for the JNI .so libraries, you can set the `-Djava.library.path` property on the JVM: @@ -97,6 +98,20 @@ the first test set that is empty. See [2] for more info. [1] http://maven.apache.org/surefire/maven-failsafe-plugin/index.html [2] http://maven.apache.org/surefire/maven-failsafe-plugin/examples/single-test.html +Running tests by tags +--------------------- + +Tests can also be filtered by Junit tags or tag expressions [1], for example to +run only the Log4 1.x agent tests: + + mvn clean verify -Dgroups='agent:log4j' + +Or to exclude the tests of the Log4j2 domain: + + mvn clean verify -Dgroups='!domain:log4j2' + +[1] https://junit.org/junit5/docs/current/user-guide/#running-tests-tags + Debugging a test ---------------------- @@ -106,42 +121,49 @@ The fastest and "easiest" way of putting a breakpoint is to use eclipse. Download eclipse (for java dev). Import a maven project that points to this repo: - File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects - Point the root directory to this repo. Select all projects. Finish + File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects + Point the root directory to this repo. Select all projects. Finish Setup the Debug Configuration: - Run -> Debug Configurations. - Select Remote Java Application. - Press the New Configuration button. - Give it the name "Remote lttng maven". - Select the project and select `lttng-tools-java` - Set the port to 5005 - Go in the Source tab. - Click Add -> Java project -> Select all - Click Apply - Click Close + + Run -> Debug Configurations. + Select Remote Java Application. + Press the New Configuration button. + Give it the name "Remote lttng maven". + Select the project and select `lttng-tools-java` + Set the port to 5005 + Go in the Source tab. + Click Add -> Java project -> Select all + Click Apply + Click Close Now let's run a single test with debug: - mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug + mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug Wait for: - Listening for transport dt_socket at address: 5005 + + Listening for transport dt_socket at address: 5005 Now go back to eclipse: - Navigate to where you want to put a break point. For example, JulAppContextOrderingIT.registerAgent. - Ctrl + shift + b can be used to set a tracepoint at the desired line. + + Navigate to where you want to put a break point. For example, JulAppContextOrderingIT.registerAgent. + Ctrl + shift + b can be used to set a tracepoint at the desired line. Then attach to the debugger: - Run -> Debug Configurations. - Select on the right "Remote lttng maven" - Click Debug + + Run -> Debug Configurations. + Select on the right "Remote lttng maven" + Click Debug You should hit the breakpoint at some point and from there use steps etc. If you want to debug lttng-ust, you need to insert a breakpoint at a valid point in time for the test and then use gdb to hook yourself to the java process. From there debugging is the same as any C application. +You will need to ignore SIGSEV from java under gdb: + + handle SIGSEGV nostop noprint pass Running the benchmarks ----------------------