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
  23 /**
  24  * Java representation of a LTTng tracing session.
  25  *
  26  * @author Alexandre Montplaisir
  27  */
  28 public interface ILttngSession extends AutoCloseable {
  29
  30     /**
  31      * Tracing domains as they are defined by lttng-tools
  32      */
  33     enum Domain {
  34         /** The JUL (java.util.logging) domain */
  35         JUL("-j"), /** The log4j (org.apache.log4j) domain */
  36         LOG4J("-l");
  37
  38         private final String flag;
  39
  40         private Domain(String flag) {
  41             this.flag = flag;
  42         }
  43
  44         /**
  45          * @return The corresponding command-line flag to pass to options like
  46          *         "lttng enable-event"
  47          */
  48         public String flag() {
  49             return flag;
  50         }
  51     }
  52
  53     // ------------------------------------------------------------------------
  54     // Factory methods
  55     // ------------------------------------------------------------------------
  56
  57     /**
  58      * Create a new LTTng tracing session using the default backend.
  59      *
  60      * @param sessionName
  61      *            The name of the session to use. It can be null, in which case
  62      *            we will provide a unique random name.
  63      * @param domain
  64      *            The tracing domain of this session
  65      * @return The new session object
  66      */
  67     static ILttngSession createSession(String sessionName, Domain domain) {
  68         return createCommandLineSession(sessionName, domain);
  69     }
  70
  71     /**
  72      * Create a new LTTng tracing session, which will use the command-line
  73      * "lttng" utility.
  74      *
  75      * @param sessionName
  76      *            The name of the session to use. It can be null, in which case
  77      *            we will provide a unique random name.
  78      * @param domain
  79      *            The tracing domain of this session
  80      * @return The new session object
  81      */
  82     static ILttngSession createCommandLineSession(String sessionName, Domain domain) {
  83         return new LttngCommandLineSession(sessionName, domain);
  84     }
  85
  86     // ------------------------------------------------------------------------
  87     // AutoCloseable
  88     // ------------------------------------------------------------------------
  89
  90     /**
  91      * Should be used to destroy the LTTng session.
  92      */
  93     @Override
  94     void close();
  95
  96     // ------------------------------------------------------------------------
  97     // Session management
  98     // ------------------------------------------------------------------------
  99
 100     /**
 101      * Enable an individual event, specifying a loglevel and filter string.
 102      *
 103      * @param eventName
 104      *            The name of the event to enable
 105      * @param loglevel
 106      *            The loglevel, will be passed as-is to lttng. May be null to
 107      *            not specify it.
 108      * @param loglevelOnly
 109      *            True to use this log level only (--loglevel-only), or false to
 110      *            include all more severe levels (--loglevel). Ignored if
 111      *            "loglevel" is null.
 112      * @param filter
 113      *            The filter string, may be null to not specify one.
 114      * @return If the command executed successfully (return code = 0)
 115      */
 116     boolean enableEvent(String eventName, String loglevel, boolean loglevelOnly, String filter);
 117
 118     /**
 119      * Enable individual event(s) with no loglevel/filter specified.
 120      *
 121      * @param enabledEvents
 122      *            The list of events to enable. Should not be null or empty
 123      * @return If the command executed successfully (return code = 0).
 124      */
 125     boolean enableEvents(String... enabledEvents);
 126
 127     /**
 128      * Enable all events in the session (as with "enable-event -a").
 129      *
 130      * @return If the command executed successfully (return code = 0).
 131      */
 132     boolean enableAllEvents();
 133
 134     /**
 135      * Send a disable-event command. Used to disable event(s) that were previously
 136      * enabled.
 137      *
 138      * @param disabledEvents
 139      *            The list of disabled events. Should not be null or empty
 140      * @return If the command executed successfully (return code = 0).
 141      */
 142     boolean disableEvents(String... disabledEvents);
 143
 144     /**
 145      * Disable all events currently enabled in the session
 146      * ("lttng disable-event -a").
 147      *
 148      * @return If the command executed successfully (return code = 0)
 149      */
 150     boolean disableAllEvents();
 151
 152     /**
 153      * Get a list of events currently available (exposed by applications) in the
 154      * session's domain.
 155      *
 156      * @return The list of available events
 157      */
 158     List<String> listEvents();
 159
 160     /**
 161      * Enable an application context with the provided retriever/context names.
 162      *
 163      * There is currently no direct command to remove an existing context, the
 164      * session has to be destroyed and re-created to do so.
 165      *
 166      * @param retrieverName
 167      *            The name of the retriever (or "namespace" of the context)
 168      * @param contextName
 169      *            The name of the context
 170      * @return If the command executed successfully (return code = 0)
 171      */
 172     boolean enableAppContext(String retrieverName, String contextName);
 173
 174     /**
 175      * Start tracing
 176      *
 177      * @return If the command executed successfully (return code = 0).
 178      */
 179     boolean start();
 180
 181     /**
 182      * Stop the tracing session
 183      *
 184      * @return If the command executed successfully (return code = 0).
 185      */
 186     boolean stop();
 187
 188     /**
 189      * Issue a "lttng view" command on the session, and returns its output. This
 190      * effectively returns the current content of the trace in text form.
 191      *
 192      * @return The output of Babeltrace on the session's current trace
 193      */
 194     List<String> view();
 195 }