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 <a href="http://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html" class="ext">Java Util Logging</a> (JUL). This back-end is called the _LTTng-UST JUL agent_ and is
   7 responsible for communications with an LTTng session daemon.
   8
   9 From the user's point of view, once the LTTng-UST JUL agent has been
  10 initialized, JUL loggers may be created and used as usual. The agent
  11 adds its own handler to the _root logger_, so that all loggers may
  12 generate LTTng events with no effort.
  13
  14 Common JUL features are supported using the `lttng` tool
  15 (see [Controlling tracing](#doc-controlling-tracing)):
  16
  17   * listing all logger names
  18   * enabling/disabling events per logger name
  19   * JUL log levels
  20
  21 Here's an example:
  22
  23 ~~~ java
  24 import java.util.logging.Logger;
  25 import org.lttng.ust.jul.LTTngAgent;
  26
  27 public class Test
  28 {
  29     public static void main(String[] argv) throws Exception
  30     {
  31         // create a logger
  32         Logger logger = Logger.getLogger("jello");
  33
  34         // call this as soon as possible (before logging)
  35         LTTngAgent lttngAgent = LTTngAgent.getLTTngAgent();
  36
  37         // log at will!
  38         logger.info("some info");
  39         logger.warning("some warning");
  40         Thread.sleep(500);
  41         logger.finer("finer information...");
  42         Thread.sleep(123);
  43         logger.severe("error!");
  44
  45         // not mandatory, but cleaner
  46         lttngAgent.dispose();
  47     }
  48 }
  49 ~~~
  50
  51 The LTTng-UST JUL agent Java classes are packaged in a JAR file named
  52 `liblttng-ust-jul.jar`. It is typically located in
  53 `/usr/lib/lttng/java`. To compile the snippet above
  54 (saved as `Test.java`), do:
  55
  56 <pre class="term">
  57 javac -cp /usr/lib/lttng/java/liblttng-ust-jul.jar Test.java
  58 </pre>
  59
  60 You can run the resulting compiled class:
  61
  62 <pre class="term">
  63 java -cp /usr/lib/lttng/java/liblttng-ust-jul.jar:. Test
  64 </pre>
  65
  66 <div class="tip">
  67 <p>
  68     <span class="t">Note:</span><a href="http://openjdk.java.net/" class="ext">OpenJDK</a> 7
  69     is used for development and continuous integration, thus this
  70     version is directly supported. However, the LTTng-UST JUL agent has
  71     also been tested with OpenJDK 6.
  72 </p>
  73 </div>