lttng-tools-java/src/main/java/org/lttng/tools/ILttngSession.java

   1 /*
   2  * Copyright (C) 2015, EfficiOS Inc., Alexandre Montplaisir <alexmonthy@efficios.com>
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17  */
  18
  19 package org.lttng.tools;
  20
  21 import java.util.List;
  22 import java.util.Set;
  23
  24 /**
  25  * Java representation of a LTTng tracing session.
  26  *
  27  * @author Alexandre Montplaisir
  28  */
  29 public interface ILttngSession extends AutoCloseable {
  30
  31     /**
  32      * Tracing domains as they are defined by lttng-tools
  33      */
  34     enum Domain {
  35         /** The JUL (java.util.logging) domain */
  36         JUL("-j"), /** The log4j (org.apache.log4j) domain */
  37         LOG4J("-l");
  38
  39         private final String flag;
  40
  41         private Domain(String flag) {
  42             this.flag = flag;
  43         }
  44
  45         /**
  46          * @return The corresponding command-line flag to pass to options like
  47          *         "lttng enable-event"
  48          */
  49         public String flag() {
  50             return flag;
  51         }
  52     }
  53
  54     // ------------------------------------------------------------------------
  55     // Factory methods
  56     // ------------------------------------------------------------------------
  57
  58     /**
  59      * Create a new LTTng tracing session using the default backend.
  60      *
  61      * @param sessionName
  62      *            The name of the session to use. It can be null, in which case
  63      *            we will provide a unique random name.
  64      * @param domain
  65      *            The tracing domain of this session
  66      * @return The new session object
  67      */
  68     static ILttngSession createSession(String sessionName, Domain domain) {
  69         return createCommandLineSession(sessionName, domain);
  70     }
  71
  72     /**
  73      * Create a new LTTng tracing session, which will use the command-line
  74      * "lttng" utility.
  75      *
  76      * @param sessionName
  77      *            The name of the session to use. It can be null, in which case
  78      *            we will provide a unique random name.
  79      * @param domain
  80      *            The tracing domain of this session
  81      * @return The new session object
  82      */
  83     static ILttngSession createCommandLineSession(String sessionName, Domain domain) {
  84         return new LttngCommandLineSession(sessionName, domain);
  85     }
  86
  87     // ------------------------------------------------------------------------
  88     // AutoCloseable
  89     // ------------------------------------------------------------------------
  90
  91     /**
  92      * Should be used to destroy the LTTng session.
  93      */
  94     @Override
  95     void close();
  96
  97     // ------------------------------------------------------------------------
  98     // Session management
  99     // ------------------------------------------------------------------------
 100
 101     /**
 102      * Enable an individual event, specifying a loglevel and filter string.
 103      *
 104      * @param eventName
 105      *            The name of the event to enable
 106      * @param loglevel
 107      *            The loglevel, will be passed as-is to lttng. May be null to
 108      *            not specify it.
 109      * @param loglevelOnly
 110      *            True to use this log level only (--loglevel-only), or false to
 111      *            include all more severe levels (--loglevel). Ignored if
 112      *            "loglevel" is null.
 113      * @param filter
 114      *            The filter string, may be null to not specify one.
 115      * @return If the command executed successfully (return code = 0)
 116      */
 117     boolean enableEvent(String eventName, String loglevel, boolean loglevelOnly, String filter);
 118
 119     /**
 120      * Enable individual event(s) with no loglevel/filter specified.
 121      *
 122      * @param enabledEvents
 123      *            The list of events to enable. Should not be null or empty
 124      * @return If the command executed successfully (return code = 0).
 125      */
 126     boolean enableEvents(String... enabledEvents);
 127
 128     /**
 129      * Enable all events in the session (as with "enable-event -a").
 130      *
 131      * @return If the command executed successfully (return code = 0).
 132      */
 133     boolean enableAllEvents();
 134
 135     /**
 136      * Send a disable-event command. Used to disable event(s) that were previously
 137      * enabled.
 138      *
 139      * @param disabledEvents
 140      *            The list of disabled events. Should not be null or empty
 141      * @return If the command executed successfully (return code = 0).
 142      */
 143     boolean disableEvents(String... disabledEvents);
 144
 145     /**
 146      * Disable all events currently enabled in the session
 147      * ("lttng disable-event -a").
 148      *
 149      * @return If the command executed successfully (return code = 0)
 150      */
 151     boolean disableAllEvents();
 152
 153     /**
 154      * Get a list of events currently available (exposed by applications) in the
 155      * session's domain.
 156      *
 157      * @return The list of available events
 158      */
 159     Set<String> listEvents();
 160
 161     /**
 162      * Start tracing
 163      *
 164      * @return If the command executed successfully (return code = 0).
 165      */
 166     boolean start();
 167
 168     /**
 169      * Stop the tracing session
 170      *
 171      * @return If the command executed successfully (return code = 0).
 172      */
 173     boolean stop();
 174
 175     /**
 176      * Issue a "lttng view" command on the session, and returns its output. This
 177      * effectively returns the current content of the trace in text form.
 178      *
 179      * @return The output of Babeltrace on the session's current trace
 180      */
 181     List<String> view();
 182 }