[lttng-dev] [PATCH lttng-ust] Update Java agent documentation

[Mathieu Desnoyers]

Merged, thanks!

Mathieu

----- Original Message -----
> From: "Christian Babeux" <christian.babeux at efficios.com>
> To: lttng-dev at lists.lttng.org
> Cc: "mathieu desnoyers" <mathieu.desnoyers at efficios.com>, "Christian Babeux" <christian.babeux at efficios.com>
> Sent: Friday, October 31, 2014 3:33:40 PM
> Subject: [PATCH lttng-ust] Update Java agent documentation
> 
> Signed-off-by: Christian Babeux <christian.babeux at efficios.com>
> ---
>  doc/Makefile.am           |  2 +-
>  doc/java-agent.txt        | 51
>  +++++++++++++++++++++++++++++++++++++++++++++++
>  doc/java-util-logging.txt | 41 -------------------------------------
>  3 files changed, 52 insertions(+), 42 deletions(-)
>  create mode 100644 doc/java-agent.txt
>  delete mode 100644 doc/java-util-logging.txt
> 
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 72dcde2..ba21e9f 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -5,4 +5,4 @@ dist_man_MANS = man/lttng-gen-tp.1 \
>  	man/lttng-ust-dl.3 \
>  	man/lttng-ust-cyg-profile.3
>  
> -dist_doc_DATA = java-util-logging.txt
> +dist_doc_DATA = java-agent.txt
> diff --git a/doc/java-agent.txt b/doc/java-agent.txt
> new file mode 100644
> index 0000000..51b0e8c
> --- /dev/null
> +++ b/doc/java-agent.txt
> @@ -0,0 +1,51 @@
> +The agent can now be built in three different configurations:
> +
> +1) Java agent with JUL support:
> +
> +$ ./configure --enable-java-agent-jul
> +
> +2) Java agent with Log4j support:
> +
> +$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
> +$ ./configure --enable-java-agent-log4j
> +
> +3) Java agent with JUL + Log4j support
> +
> +$ export CLASSPATH=$CLASSPATH:/path/to/log4j.jar
> +$ ./configure --enable-java-agent-all
> +
> +To build the agent with log4j support, make sure that the log4j jar
> +is in your Java classpath.
> +
> +The configure script will automatically detect the appropriate Java
> +binaries to use in order to build the Java agent.
> +
> +The name of the agent jar file is now "liblttng-ust-agent.jar".
> +It will be installed in the arch-agnostic "$prefix/share/java" path
> +e.g: "/usr/share/java".
> +
> +In order to support older applications using the "org.lttng.ust.jul"
> +package, a transitional package is built with the same name.
> +
> +All applications should move to use the "org.lttng.ust.agent" package.
> +
> +After building, you can use the "liblttng-ust-agent.jar" file in a
> +Java project.  Depending on your configuration, the agent will
> +requires shared objects (e.g: "liblttng-ust-jul.so") which is installed
> +by the build system when doing "make install". Make sure that your
> +Java application can find this shared object with the
> +"java.library.path".
> +
> +In order to enable the agent in your Java application, you simply have to
> add
> +this as early as you can in the runtime process.
> +
> +import org.lttng.ust.agent.LTTngAgent;
> +[...]
> +	private static LTTngAgent lttngAgent;
> +	[...]
> +	lttngAgent = LTTngAgent.getLTTngAgent();
> +
> +This will initialize automatically the singleton LTTngAgent, and will
> +return when the session daemon registration is done. If no session daemon is
> +available, the execution will continue and the agent will retry every
> +3 seconds.
> diff --git a/doc/java-util-logging.txt b/doc/java-util-logging.txt
> deleted file mode 100644
> index 9f827e6..0000000
> --- a/doc/java-util-logging.txt
> +++ /dev/null
> @@ -1,41 +0,0 @@
> -The support for JUL needs to be explicitly enabled when lttng-ust is
> -configured, e.g.:
> -
> -dependency: openjdk-7-jdk
> -    ./configure --with-java-jdk=/usr/lib/jvm/java-7-openjdk
> --with-jni-interface
> -
> -On Debian system for instance you can simply use the "default-java" path:
> -
> -    ./configure --with-java-jdk=/usr/lib/jvm/default-java
> --with-jni-interface
> -
> -Note that the OpenJDK 7 is used for development and continuous integration
> thus
> -we directly support that version for this library. However, it has been
> tested
> -with OpenJDK 6 also. Please let us know if other Java version (commercial or
> -not) work with this library.
> -
> -The LTTng Java Agent for JUL support is typically installed here:
> -
> -/usr/local/lib/lttng/java/liblttng-ust-jul.jar
> -
> -After building, you can use the "liblttng-ust-jul.jar" file in a Java
> project.
> -It requires "liblttng-ust-jul.so" which is installed by the build system
> when
> -doing "make install". Make sure that your Java application can find this
> shared
> -object with the "java.library.path".
> -
> -In order to enable the agent in your Java application, you simply have to
> add
> -this as early as you can in the runtime process.
> -
> -import org.lttng.ust.jul.LTTngAgent;
> -[...]
> -	private static LTTngAgent lttngAgent;
> -	[...]
> -	lttngAgent = LTTngAgent.getLTTngAgent();
> -
> -This will initialize automatically the singleton LTTngAgent, and will
> -return when session daemon registration is done. If no session daemon is
> -available, the execution will continue and the agent will retry every
> -3 seconds.
> -
> -Once registered, it is adds a thread inside your Java application and will
> be
> -able to automatically use every Logger object and map them to the jul_event
> -tracepoint of the JNI interface.
> --
> 2.1.1
> 
> 

-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com