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