Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: java-application | |
3 | --- | |
4 | ||
5 | LTTng-UST provides a _logging_ back-end for Java applications using | |
c23b8cb1 PP |
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. | |
5e0cbfb0 | 12 | |
c23b8cb1 PP |
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> | |
5e0cbfb0 | 19 | |
c23b8cb1 PP |
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 | |
5e0cbfb0 PP |
26 | (see [Controlling tracing](#doc-controlling-tracing)): |
27 | ||
28 | * listing all logger names | |
29 | * enabling/disabling events per logger name | |
c23b8cb1 | 30 | * JUL/log4j log levels |
5e0cbfb0 | 31 | |
c23b8cb1 | 32 | Here's an example using **`java.util.logging`**: |
5e0cbfb0 PP |
33 | |
34 | ~~~ java | |
35 | import java.util.logging.Logger; | |
c23b8cb1 | 36 | import org.lttng.ust.agent.LTTngAgent; |
5e0cbfb0 PP |
37 | |
38 | public class Test | |
39 | { | |
c23b8cb1 PP |
40 | private static final int answer = 42; |
41 | ||
5e0cbfb0 PP |
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); | |
c23b8cb1 | 54 | logger.finer("finer information; the answer is " + answer); |
5e0cbfb0 PP |
55 | Thread.sleep(123); |
56 | logger.severe("error!"); | |
57 | ||
58 | // not mandatory, but cleaner | |
59 | lttngAgent.dispose(); | |
60 | } | |
61 | } | |
62 | ~~~ | |
63 | ||
c23b8cb1 PP |
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 | |
5e0cbfb0 PP |
102 | (saved as `Test.java`), do: |
103 | ||
104 | <pre class="term"> | |
c23b8cb1 | 105 | javac -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP Test.java |
5e0cbfb0 PP |
106 | </pre> |
107 | ||
c23b8cb1 PP |
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: | |
5e0cbfb0 PP |
111 | |
112 | <pre class="term"> | |
c23b8cb1 | 113 | java -cp /usr/lib/lttng/java/liblttng-ust-agent.jar:$LOG4JCP:. Test |
5e0cbfb0 PP |
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 | |
c23b8cb1 | 120 | version is directly supported. However, the LTTng-UST Java agent has |
5e0cbfb0 PP |
121 | also been tested with OpenJDK 6. |
122 | </p> | |
123 | </div> |