contents/using-lttng/instrumenting/java-application.md

   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>