src/test/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      * Constructor to create a new LTTng tracing session, which will use the
  59      * command-line "lttng" utility.
  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 newCommandLineSession(String sessionName, Domain domain) {
  69         return new LttngCommandLineSession(sessionName, domain);
  70     }
  71
  72     // ------------------------------------------------------------------------
  73     // AutoCloseable
  74     // ------------------------------------------------------------------------
  75
  76     /**
  77      * Should be used to destroy the LTTng session.
  78      */
  79     @Override
  80     void close();
  81
  82     // ------------------------------------------------------------------------
  83     // Session management
  84     // ------------------------------------------------------------------------
  85
  86     /**
  87      * Enable all events in the session (as with "enable-event -a").
  88      *
  89      * @return If the command executed successfully (return code = 0).
  90      */
  91     boolean enableAllEvents();
  92
  93     /**
  94      * Enable individual event(s).
  95      *
  96      * @param enabledEvents
  97      *            The list of events to enable. Should not be null or empty
  98      * @return If the command executed successfully (return code = 0).
  99      */
 100     boolean enableEvents(String... enabledEvents);
 101
 102     /**
 103      * Send a disable-event command. Used to disable events that were previously
 104      * enabled.
 105      *
 106      * @param disabledEvents
 107      *            The list of disabled events. Should not be null or empty
 108      * @return If the command executed successfully (return code = 0).
 109      */
 110     boolean disableEvents(String... disabledEvents);
 111
 112     /**
 113      * Start tracing
 114      *
 115      * @return If the command executed successfully (return code = 0).
 116      */
 117     boolean start();
 118
 119     /**
 120      * Stop the tracing session
 121      *
 122      * @return If the command executed successfully (return code = 0).
 123      */
 124     boolean stop();
 125
 126     /**
 127      * Issue a "lttng view" command on the session, and returns its output. This
 128      * effectively returns the current content of the trace in text form.
 129      *
 130      * @return The output of Babeltrace on the session's current trace
 131      */
 132     List<String> view();
 133 }