include/lttng/session-descriptor.h

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