X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=doc%2Fexamples%2Fjava-jul%2FHello.java;h=cc800e6e78798bf5e9dd351c60167183156d52fd;hb=c0c0989ab70574e09b2f7e8b48c2da6af664a849;hp=87b4c1601e50c96f48ec864a95dbf1e6a286ac44;hpb=501f6777610d7f8d855453c0083a10912d5fac4b;p=deliverable%2Flttng-ust.git diff --git a/doc/examples/java-jul/Hello.java b/doc/examples/java-jul/Hello.java index 87b4c160..cc800e6e 100644 --- a/doc/examples/java-jul/Hello.java +++ b/doc/examples/java-jul/Hello.java @@ -1,102 +1,78 @@ /* - * Copyright (C) 2013 - David Goulet + * SPDX-License-Identifier: MIT * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to - * deal in the Software without restriction, including without limitation the - * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or - * sell copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS - * IN THE SOFTWARE. + * Copyright (C) 2015 EfficiOS Inc., Alexandre Montplaisir + * Copyright (C) 2013 David Goulet */ import java.io.IOException; -import java.util.logging.Level; +import java.util.logging.Handler; import java.util.logging.Logger; -/* - * That's the import you need being the path in the liblttng-ust-jul Jar file. +import org.lttng.ust.agent.jul.LttngLogHandler; + +/** + * Example application using the LTTng-UST Java JUL agent. + * + *

+ * Basically all that is required is to instantiate a {@link LttngLogHandler} + * and to attach it to a JUL {@link Logger}. Then use the Logger normally to log + * messages, which will be sent to UST as trace events. + *

+ *

+ * {@link Logger} names are used as event names on the UST side. This means that + * by enabling/disabling certain events in the tracing session, you are + * effectively enabling and disabling Loggers on the Java side. Note that this + * applies only to {@link LttngLogHandler}'s. If other handlers are attached to + * the Logger, those will continue logging events normally. + *

+ * + *

+ * To obtain LTTng trace events, you should run the following sequence of + * commands: + *

+ * + *
    + *
  • $ lttng create
    • + *
  • $ lttng enable-event -j -a
    • + *
  • $ lttng start
    • + *
  • (run this program)
    • + *
  • $ lttng stop
    • + *
  • $ lttng view
    • + *
  • $ lttng destroy
    • + *
+ * + * @author Alexandre Montplaisir + * @author David Goulet */ -import org.lttng.ust.agent.LTTngAgent; +public class Hello { -public class Hello -{ - /* Of course :) */ - private static final int answer = 42; + /** Class-wide JUL logger object */ + private static final Logger LOGGER = Logger.getLogger(Hello.class.getName()); - /* - * Static reference to the LTTngAgent. Used to dispose of it at the end - * which is recommended but not mandatory to do. + /** + * Application start + * + * @param args + * Command-line arguments + * @throws IOException + * If the required native libraries cannot be found. You may + * have to specify "-Djava.library.path=..." on the "java" + * command line. */ - private static LTTngAgent lttngAgent; - - public static void main(String args[]) throws Exception - { - /* - * For this example, a custom "hello" logger is created. Note that JUL - * has a default "global" that can also be used. - */ - Logger helloLog = Logger.getLogger("hello"); - - /* - * Get the LTTngAgent singelton reference. This will also initialize - * the Agent and make it register to the session daemon if available. - * When this returns, the Agent is registered and fully ready. If no - * session daemon is found, it will return and retry every 3 seconds in - * the background. TCP is used for communication. - * - * Note that the LTTngAgent once registered is a seperate thread in - * your Java application. - */ - lttngAgent = LTTngAgent.getLTTngAgent(); - - /* - * Gives you time to do some lttng commands before any event is hit. - */ - Thread.sleep(5000); - - /* Trigger a tracing event using the JUL Logger created before. */ - helloLog.info("Hello World, the answer is " + answer); - - /* - * From this point on, the above message will be collected in the trace - * if the event "hello" is enabled for the JUL domain using the lttng - * command line or the lttng-ctl API. For instance: - * - * $ lttng enable-event -j hello - * - * A new logger is created here and fired after. The Agent has an - * internal timer that is fired every 5 seconds in order to enable - * events that were not found at first but might need to be enabled - * when new Logger appears. Unfortunately, there is no way right now to - * get notify of that so we have to actively poll. - * - * Using the --all command for instance, it will make this Logger - * available in a LTTng trace after the internal Agent's timer is - * fired. (lttng enable-event -a -j). - */ - Logger helloLogDelayed = Logger.getLogger("hello_delay"); + public static void main(String args[]) throws IOException { - System.out.println("Firing hello delay in 10 seconds..."); - Thread.sleep(10000); - helloLogDelayed.info("Hello World delayed..."); + /* Instantiate a LTTngLogHandler object, and attach it to our logger */ + Handler lttngHandler = new LttngLogHandler(); + LOGGER.addHandler(lttngHandler); - System.out.println("Cleaning Hello"); + /* Log events using the JUL Logger created before. */ + LOGGER.info("Hello World, the answer is " + 42); + LOGGER.info("Another info event"); + LOGGER.severe("A severe event"); - /* - * Again, this is highly recommended so the session daemon socket gets - * cleaned up explicitely but it is not mandatory to do this step. - */ - lttngAgent.dispose(); + /* Cleanup */ + LOGGER.removeHandler(lttngHandler); + lttngHandler.close(); } }