| 1 | --- |
| 2 | id: java-application |
| 3 | --- |
| 4 | |
| 5 | LTTng-UST provides a _logging_ back-end for Java applications using |
| 6 | either |
| 7 | <a href="http://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html" class="ext"><code>java.util.logging</code></a> |
| 8 | (JUL), or |
| 9 | <a href="http://logging.apache.org/log4j/1.2/" class="ext">Apache log4j 1.2</a>. |
| 10 | This back-end is called the _LTTng-UST Java agent_, and is responsible |
| 11 | for communications with an LTTng session daemon. |
| 12 | |
| 13 | <div class="tip"> |
| 14 | <p> |
| 15 | <span class="t">Note:</span>The latest stable version of LTTng |
| 16 | does not support Log4j 2. |
| 17 | </p> |
| 18 | </div> |
| 19 | |
| 20 | From the user's point of view, once the LTTng-UST Java agent has been |
| 21 | initialized, JUL and log4j loggers may be created and used as usual. |
| 22 | The agent adds its own handler to the _root logger_, so that all |
| 23 | loggers may generate LTTng events with no effort. |
| 24 | |
| 25 | Common JUL/log4j features are supported using the `lttng` tool |
| 26 | (see [Controlling tracing](#doc-controlling-tracing)): |
| 27 | |
| 28 | * listing all logger names |
| 29 | * enabling/disabling events per logger name |
| 30 | * JUL/log4j log levels |
| 31 | |
| 32 | Here's an example using **`java.util.logging`**: |
| 33 | |
| 34 | ~~~ java |
| 35 | import java.util.logging.Logger; |
| 36 | import org.lttng.ust.agent.LTTngAgent; |
| 37 | |
| 38 | public class Test |
| 39 | { |
| 40 | private static final int answer = 42; |
| 41 | |
| 42 | public static void main(String[] argv) throws Exception |
| 43 | { |
| 44 | // create a logger |
| 45 | Logger logger = Logger.getLogger("jello"); |
| 46 | |
| 47 | // call this as soon as possible (before logging) |
| 48 | LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent(); |
| 49 | |
| 50 | // log at will! |
| 51 | logger.info("some info"); |
| 52 | logger.warning("some warning"); |
| 53 | Thread.sleep(500); |
| 54 | logger.finer("finer information; the answer is " + answer); |
| 55 | Thread.sleep(123); |
| 56 | logger.severe("error!"); |
| 57 | |
| 58 | // not mandatory, but cleaner |
| 59 | lttngAgent.dispose(); |
| 60 | } |
| 61 | } |
| 62 | ~~~ |
| 63 | |
| 64 | Here's the same example, this time using **log4j**: |
| 65 | |
| 66 | ~~~ java |
| 67 | import org.apache.log4j.Logger; |
| 68 | import org.apache.log4j.BasicConfigurator; |
| 69 | import org.lttng.ust.agent.LTTngAgent; |
| 70 | |
| 71 | public class Test |
| 72 | { |
| 73 | private static final int answer = 42; |
| 74 | |
| 75 | public static void main(String[] argv) throws Exception |
| 76 | { |
| 77 | // create and configure a logger |
| 78 | Logger logger = Logger.getLogger(Test.class); |
| 79 | BasicConfigurator.configure(); |
| 80 | |
| 81 | // call this as soon as possible (before logging) |
| 82 | LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent(); |
| 83 | |
| 84 | // log at will! |
| 85 | logger.info("some info"); |
| 86 | logger.warn("some warning"); |
| 87 | Thread.sleep(500); |
| 88 | logger.debug("debug information; the answer is " + answer); |
| 89 | Thread.sleep(123); |
| 90 | logger.error("error!"); |
| 91 | logger.fatal("fatal error!"); |
| 92 | |
| 93 | // not mandatory, but cleaner |
| 94 | lttngAgent.dispose(); |
| 95 | } |
| 96 | } |
| 97 | ~~~ |
| 98 | |
| 99 | The LTTng-UST Java agent classes are packaged in a JAR file named |
| 100 | `liblttng-ust-agent.jar`. It is typically located in |
| 101 | `/usr/lib/lttng/java`. To compile the snippets above |
| 102 | (saved as `Test.java`), do: |
| 103 | |
| 104 | <pre class="term"> |
| 105 | javac -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP Test.java |
| 106 | </pre> |
| 107 | |
| 108 | where `$LOG4JCP` is the log4j 1.2 JAR file path, if you're using log4j. |
| 109 | |
| 110 | You can run the resulting compiled class like this: |
| 111 | |
| 112 | <pre class="term"> |
| 113 | java -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP:. Test |
| 114 | </pre> |
| 115 | |
| 116 | <div class="tip"> |
| 117 | <p> |
| 118 | <span class="t">Note:</span><a href="http://openjdk.java.net/" class="ext">OpenJDK</a> 7 |
| 119 | is used for development and continuous integration, thus this |
| 120 | version is directly supported. However, the LTTng-UST Java agent has |
| 121 | also been tested with OpenJDK 6. |
| 122 | </p> |
| 123 | </div> |