From 215610ebba8ba215eca082c9f3399c73b00e1500 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 4 Sep 2015 12:56:40 -0400 Subject: [PATCH] java-application: split Signed-off-by: Philippe Proulx --- .../instrumenting/java-application.md | 123 ------------------ .../instrumenting/java-application/intro.md | 23 ++++ .../instrumenting/java-application/jul.md | 60 +++++++++ .../instrumenting/java-application/log4j.md | 64 +++++++++ toc/docs.yml | 5 + 5 files changed, 152 insertions(+), 123 deletions(-) delete mode 100644 contents/using-lttng/instrumenting/java-application.md create mode 100644 contents/using-lttng/instrumenting/java-application/intro.md create mode 100644 contents/using-lttng/instrumenting/java-application/jul.md create mode 100644 contents/using-lttng/instrumenting/java-application/log4j.md diff --git a/contents/using-lttng/instrumenting/java-application.md b/contents/using-lttng/instrumenting/java-application.md deleted file mode 100644 index af51664..0000000 --- a/contents/using-lttng/instrumenting/java-application.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -id: java-application ---- - -LTTng-UST provides a _logging_ back-end for Java applications using -either -java.util.logging -(JUL), or -Apache log4j 1.2. -This back-end is called the _LTTng-UST Java agent_, and is responsible -for communications with an LTTng session daemon. - -
-

- Note:The latest stable version of LTTng - does not support Log4j 2. -

-
- -From the user's point of view, once the LTTng-UST Java agent has been -initialized, JUL and log4j loggers may be created and used as usual. -The agent adds its own handler to the _root logger_, so that all -loggers may generate LTTng events with no effort. - -Common JUL/log4j features are supported using the `lttng` tool -(see [Controlling tracing](#doc-controlling-tracing)): - - * listing all logger names - * enabling/disabling events per logger name - * JUL/log4j log levels - -Here's an example using **`java.util.logging`**: - -~~~ java -import java.util.logging.Logger; -import org.lttng.ust.agent.LTTngAgent; - -public class Test -{ - private static final int answer = 42; - - public static void main(String[] argv) throws Exception - { - // create a logger - Logger logger = Logger.getLogger("jello"); - - // call this as soon as possible (before logging) - LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent(); - - // log at will! - logger.info("some info"); - logger.warning("some warning"); - Thread.sleep(500); - logger.finer("finer information; the answer is " + answer); - Thread.sleep(123); - logger.severe("error!"); - - // not mandatory, but cleaner - lttngAgent.dispose(); - } -} -~~~ - -Here's the same example, this time using **log4j**: - -~~~ java -import org.apache.log4j.Logger; -import org.apache.log4j.BasicConfigurator; -import org.lttng.ust.agent.LTTngAgent; - -public class Test -{ - private static final int answer = 42; - - public static void main(String[] argv) throws Exception - { - // create and configure a logger - Logger logger = Logger.getLogger(Test.class); - BasicConfigurator.configure(); - - // call this as soon as possible (before logging) - LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent(); - - // log at will! - logger.info("some info"); - logger.warn("some warning"); - Thread.sleep(500); - logger.debug("debug information; the answer is " + answer); - Thread.sleep(123); - logger.error("error!"); - logger.fatal("fatal error!"); - - // not mandatory, but cleaner - lttngAgent.dispose(); - } -} -~~~ - -The LTTng-UST Java agent classes are packaged in a JAR file named -`liblttng-ust-agent.jar`. It is typically located in -`/usr/lib/lttng/java`. To compile the snippets above -(saved as `Test.java`), do: - -
-javac -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP Test.java
-
- -where `$LOG4JCP` is the log4j 1.2 JAR file path, if you're using log4j. - -You can run the resulting compiled class like this: - -
-java -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP:. Test
-
- -
-

- Note:OpenJDK 7 - is used for development and continuous integration, thus this - version is directly supported. However, the LTTng-UST Java agent has - also been tested with OpenJDK 6. -

-
diff --git a/contents/using-lttng/instrumenting/java-application/intro.md b/contents/using-lttng/instrumenting/java-application/intro.md new file mode 100644 index 0000000..31e49d2 --- /dev/null +++ b/contents/using-lttng/instrumenting/java-application/intro.md @@ -0,0 +1,23 @@ +--- +id: java-application +--- + +LTTng-UST provides a _logging_ back-end for Java applications using +either +java.util.logging +(JUL) or +Apache log4j 1.2. +This back-end is called the _LTTng-UST Java agent_, and it is responsible +for the communications with an LTTng session daemon. + +From the user's point of view, once the LTTng-UST Java agent has been +initialized, JUL and log4j loggers may be created and used as usual. +The agent adds its own handler to the _root logger_, so that all +loggers may generate LTTng events with no effort. + +Common JUL/log4j features are supported using the `lttng` tool +(see [Controlling tracing](#doc-controlling-tracing)): + + * listing all logger names + * enabling/disabling events per logger name + * JUL/log4j log levels diff --git a/contents/using-lttng/instrumenting/java-application/jul.md b/contents/using-lttng/instrumenting/java-application/jul.md new file mode 100644 index 0000000..504d737 --- /dev/null +++ b/contents/using-lttng/instrumenting/java-application/jul.md @@ -0,0 +1,60 @@ +--- +id: jul +--- + +Here's an example of tracing a Java application which is using +**`java.util.logging`**: + +~~~ java +import java.util.logging.Logger; +import org.lttng.ust.agent.LTTngAgent; + +public class Test +{ + private static final int answer = 42; + + public static void main(String[] argv) throws Exception + { + // create a logger + Logger logger = Logger.getLogger("jello"); + + // call this as soon as possible (before logging) + LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent(); + + // log at will! + logger.info("some info"); + logger.warning("some warning"); + Thread.sleep(500); + logger.finer("finer information; the answer is " + answer); + Thread.sleep(123); + logger.severe("error!"); + + // not mandatory, but cleaner + lttngAgent.dispose(); + } +} +~~~ + +The LTTng-UST Java agent is packaged in a JAR file named +`liblttng-ust-agent.jar` It is typically located in +`/usr/lib/lttng/java`. To compile the snippet above +(saved as `Test.java`), do: + +
+javac -cp /usr/lib/lttng/java/liblttng-ust-agent.jar Test.java
+
+ +You can run the resulting compiled class like this: + +
+java -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:. Test
+
+ +
+

+ Note:OpenJDK 7 + is used for development and continuous integration, thus this + version is directly supported. However, the LTTng-UST Java agent has + also been tested with OpenJDK 6. +

+
diff --git a/contents/using-lttng/instrumenting/java-application/log4j.md b/contents/using-lttng/instrumenting/java-application/log4j.md new file mode 100644 index 0000000..916fc08 --- /dev/null +++ b/contents/using-lttng/instrumenting/java-application/log4j.md @@ -0,0 +1,64 @@ +--- +id: log4j +since: 2.6 +--- + +LTTng features an Apache log4j 1.2 agent, which means your existing +Java applications using log4j 1.2 for logging can record events to +LTTng traces with just a minor source code modification. + +
+

+ Note:This version of LTTng does not + support Log4j 2. +

+
+ +Here's an example: + +~~~ java +import org.apache.log4j.Logger; +import org.apache.log4j.BasicConfigurator; +import org.lttng.ust.agent.LTTngAgent; + +public class Test +{ + private static final int answer = 42; + + public static void main(String[] argv) throws Exception + { + // create and configure a logger + Logger logger = Logger.getLogger(Test.class); + BasicConfigurator.configure(); + + // call this as soon as possible (before logging) + LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent(); + + // log at will! + logger.info("some info"); + logger.warn("some warning"); + Thread.sleep(500); + logger.debug("debug information; the answer is " + answer); + Thread.sleep(123); + logger.error("error!"); + logger.fatal("fatal error!"); + + // not mandatory, but cleaner + lttngAgent.dispose(); + } +} +~~~ + +To compile the snippet above, do: + +
+javac -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP Test.java
+
+ +where `$LOG4JCP` is the log4j 1.2 JAR file path. + +You can run the resulting compiled class like this: + +
+java -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP:. Test
+
diff --git a/toc/docs.yml b/toc/docs.yml index c0703c3..c8bfa6d 100644 --- a/toc/docs.yml +++ b/toc/docs.yml @@ -139,6 +139,11 @@ cats: title: Dynamic linker tracing - id: java-application title: Java application + cats: + - id: jul + title: java.util.logging + - id: log4j + title: Apache log4j 1.2 - id: instrumenting-linux-kernel title: Linux kernel cats: -- 2.34.1