include/lttng/session-descriptor.h

   1 /*
   2  * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License, version 2.1 only,
   6  * as published by the Free Software Foundation.
   7  *
   8  * This library is distributed in the hope that it will be useful, but WITHOUT
   9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this library; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16  */
  17
  18 #ifndef LTTNG_SESSION_DESCRIPTOR_H
  19 #define LTTNG_SESSION_DESCRIPTOR_H
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25 struct lttng_session_descriptor;
  26
  27 /*
  28  * Session descriptor API.
  29  *
  30  * A session descriptor is an object describing the immutable configuration
  31  * options of an LTTng tracing session.
  32  *
  33  * When used with the lttng_create_session_ext() function, a session descriptor
  34  * allows the creation of a tracing session of the following types: regular,
  35  * snapshot, and live.
  36  *
  37  * Certain parameters can be omitted at the time of creation of a session
  38  * descriptor to use default or auto-generated values selected by the
  39  * session daemon. For instance, a session's name can be left unspecified,
  40  * in which case one that is guaranteed not to clash with pre-existing
  41  * sessions will be automatically be generated by the session daemon.
  42  *
  43  * Most session descriptors can be created in either "no output", local, or
  44  * network output modes. The various output modes supported vary by session
  45  * type.
  46  *
  47  * Regular session creation functions and output modes:
  48  *   * "no output": lttng_session_descriptor_create()
  49  *   * local:       lttng_session_descriptor_local_create()
  50  *   * network:     lttng_session_descriptor_network_create()
  51  *
  52  * Snapshot session creation functions and output modes:
  53  *   * "no output": lttng_session_descriptor_snapshot_create()
  54  *   * local:       lttng_session_descriptor_snapshot_local_create()
  55  *   * network:     lttng_session_descriptor_snapshot_network_create()
  56  *
  57  * Live session creation functions and output modes:
  58  *   * "no output": lttng_session_descriptor_live_create()
  59  *   * network:     lttng_session_descriptor_live_network_create()
  60  *
  61  * Local output functions accept a 'path' parameter that must be an absolute
  62  * path to which the user has write access. When a local output is automatically
  63  * generated, it adopts the form:
  64  *   $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME
  65  *
  66  * Where CREATION_TIME is time of the creation of the session on the session
  67  * daemon in the form "yyyymmdd-hhmmss".
  68  *
  69  * Network output locations can also be auto-genated by leaving the
  70  * 'control_url' and 'data_url' output parameters unspecified. In such cases,
  71  * the session daemon will create a default output targeting a relay daemon
  72  * at net://127.0.0.1, using the default 'control' and 'data' ports.
  73  *
  74  * The format of the 'control_url' and 'data_url' paramaters is:
  75  *   NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
  76  *
  77  * NETPROTO: Network protocol, amongst:
  78  *   * net:  TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
  79  *           are defined at build time of the lttng toolchain.
  80  *   * net6: TCP over IPv6: same default ports as the 'net' protocol.
  81  *   * tcp:  Same as the 'net' protocol.
  82  *   * tcp6: Same as the 'net6' protocol.
  83  *
  84  * HOST | IPADDR:  Hostname or IP address (IPv6 address *must* be enclosed
  85  *                 in brackets; see RFC 2732).
  86  *
  87  * CTRLPORT: Control port.
  88  *
  89  * DATAPORT: Data port.
  90  *
  91  * TRACEPATH: Path of trace files on the remote file system. This path is
  92  *            relative to the base output directory set on the relay daemon
  93  *            end.
  94  *
  95  * The 'data_url' parameter is optional:
  96  *   * This parameter is meaningless for local tracing.
  97  *   * If 'control_url' is specified and a network protocol is used, the
  98  *     default data port, and the 'control_url' host will be used.
  99  */
 100
 101 enum lttng_session_descriptor_status {
 102         /* Invalid session descriptor parameter. */
 103         LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1,
 104         LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0,
 105         /* Session descriptor parameter is unset. */
 106         LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET = 1,
 107 };
 108
 109 /*
 110  * Create a session descriptor in no-output mode.
 111  *
 112  * The 'name' parameter can be left NULL to auto-generate a session name.
 113  *
 114  * Returns an lttng_session_descriptor instance on success, NULL on error.
 115  */
 116 extern struct lttng_session_descriptor *
 117 lttng_session_descriptor_create(const char *name);
 118
 119 /*
 120  * Create a session descriptor with a local output destination.
 121  *
 122  * The 'name' parameter can be left NULL to auto-generate a session name.
 123  *
 124  * The 'path' must either be an absolute path or it can be left NULL to
 125  * use the default local outout destination.
 126  *
 127  * Returns an lttng_session_descriptor instance on success, NULL on error.
 128  */
 129 extern struct lttng_session_descriptor *
 130 lttng_session_descriptor_local_create(const char *name, const char *path);
 131
 132 /*
 133  * Create a session descriptor with a remote output destination.
 134  *
 135  * The 'name' parameter can be left NULL to auto-generate a session name.
 136  *
 137  * The 'control_url' and 'data_url' must conform to the URL format
 138  * described above or can be left NULL to use the default network output.
 139  *
 140  * Returns an lttng_session_descriptor instance on success, NULL on error.
 141  */
 142 extern struct lttng_session_descriptor *
 143 lttng_session_descriptor_network_create(const char *name,
 144                 const char *control_url, const char *data_url);
 145
 146 /*
 147  * Create a snapshot session descriptor without a default output.
 148  *
 149  * The 'name' parameter can be left NULL to auto-generate a session name.
 150  *
 151  * Returns an lttng_session_descriptor instance on success, NULL on error.
 152  */
 153 extern struct lttng_session_descriptor *
 154 lttng_session_descriptor_snapshot_create(const char *name);
 155
 156 /*
 157  * Create a snapshot session descriptor with a local output destination.
 158  *
 159  * The 'name' parameter can be left NULL to auto-generate a session name.
 160  *
 161  * The 'path' must either be an absolute path or it can be left NULL to
 162  * use the default local output destination as the default snapshot output.
 163  *
 164  * Returns an lttng_session_descriptor instance on success, NULL on error.
 165  */
 166 extern struct lttng_session_descriptor *
 167 lttng_session_descriptor_snapshot_local_create(const char *name,
 168                 const char *path);
 169
 170 /*
 171  * Create a snapshot session descriptor with a remote output destination.
 172  *
 173  * The 'name' parameter can be left NULL to auto-generate a session name.
 174  *
 175  * The 'control_url' and 'data_url' must conform to the URL format
 176  * described above or can be left NULL to use the default network output as
 177  * the default snapshot output.
 178  *
 179  * Returns an lttng_session_descriptor instance on success, NULL on error.
 180  */
 181 extern struct lttng_session_descriptor *
 182 lttng_session_descriptor_snapshot_network_create(const char *name,
 183                 const char *control_url, const char *data_url);
 184
 185 /*
 186  * Create a live session descriptor without an output.
 187  *
 188  * The 'name' parameter can be left NULL to auto-generate a session name.
 189  *
 190  * The 'live_timer_interval_us' parameter is the live timer's period, specified
 191  * in microseconds.
 192  *
 193  * This parameter can't be 0. There is no default value defined for a live
 194  * timer's period.
 195  *
 196  * Returns an lttng_session_descriptor instance on success, NULL on error.
 197  */
 198 extern struct lttng_session_descriptor *
 199 lttng_session_descriptor_live_create(
 200                 const char *name, unsigned long long live_timer_interval_us);
 201
 202 /*
 203  * Create a live session descriptor with a remote output destination.
 204  *
 205  * The 'name' parameter can be left NULL to auto-generate a session name.
 206  *
 207  * The 'control_url' and 'data_url' must conform to the URL format
 208  * described above or can be left NULL to use the default network output.
 209  *
 210  * The 'live_timer_interval_us' parameter is the live timer's period, specified
 211  * in microseconds.
 212  *
 213  * This parameter can't be 0. There is no default value defined for a live
 214  * timer's period.
 215  *
 216  * Returns an lttng_session_descriptor instance on success, NULL on error.
 217  */
 218 extern struct lttng_session_descriptor *
 219 lttng_session_descriptor_live_network_create(
 220                 const char *name,
 221                 const char *control_url, const char *data_url,
 222                 unsigned long long live_timer_interval_us);
 223
 224 /*
 225  * Get a session descriptor's session name.
 226  *
 227  * The 'name' parameter is used as an output parameter and will point to
 228  * the session descriptor's session name on success
 229  * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
 230  * for other return codes. The pointer returned through 'name' is only
 231  * guaranteed to remain valid until the next method call on the session
 232  * descriptor.
 233  *
 234  * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
 235  * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are
 236  * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
 237  * name parameter is unset.
 238  */
 239 extern enum lttng_session_descriptor_status
 240 lttng_session_descriptor_get_session_name(
 241                 const struct lttng_session_descriptor *descriptor,
 242                 const char **name);
 243
 244 /*
 245  * Destroy a local lttng_session object.
 246  *
 247  * This does not destroy the session on the session daemon; it releases
 248  * the resources allocated by the descriptor object.
 249  */
 250 extern void lttng_session_descriptor_destroy(
 251                 struct lttng_session_descriptor *descriptor);
 252
 253 #ifdef __cplusplus
 254 }
 255 #endif
 256
 257 #endif /* LTTNG_SESSION_DESCRIPTOR_H */