include/lttng/session.h

   1 /*
   2  * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
   3  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-only
   6  *
   7  */
   8
   9 #ifndef LTTNG_SESSION_H
  10 #define LTTNG_SESSION_H
  11
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 #include <lttng/constant.h>
  17
  18 struct lttng_handle;
  19 struct lttng_session_descriptor;
  20 struct lttng_destruction_handle;
  21
  22 /*
  23  * Basic session information.
  24  *
  25  * The "enabled" field is only used when listing the sessions which indicate if
  26  * it's started or not.
  27  *
  28  * The structures should be initialized to zero before use.
  29  */
  30 #define LTTNG_SESSION_PADDING1             8
  31 struct lttng_session {
  32         char name[LTTNG_NAME_MAX];
  33         /*
  34          * Human-readable representation of the trace's destination.
  35          * In the case of a local tracing session, a path is provided:
  36          *     /path/to/the/output
  37          *
  38          * In the case of a remote (network) tracing session, the string has
  39          * the following format:
  40          *     net://hostname/path:ctrl_port [data: data_port]
  41          */
  42         char path[PATH_MAX];
  43         uint32_t enabled;       /* enabled/started: 1, disabled/stopped: 0 */
  44         uint32_t snapshot_mode;
  45         unsigned int live_timer_interval;       /* usec */
  46
  47         /*
  48          * End of public attributes.
  49          * The remaining fields are used to deal with ABI management concerns.
  50          */
  51
  52         /*
  53          * 32-bit architectures are already naturally aligned on 4 bytes after
  54          * 'live_timer_interval'. However, the offset does not result in a
  55          * natural alignment on 64-bit architectures. Adding 4 bytes of
  56          * padding here results in an aligned offset after 'alignement_padding'
  57          * for both bitnesses.
  58          *
  59          * This was added since not all compilers appear to align unions in the
  60          * same way. Some (e.g. MSVC) do not seem to impose an alignement
  61          * constraint while others (e.g. gcc, clang, icc) seem to align it to
  62          * ensure 'ptr' is naturally aligned.
  63          */
  64         char alignment_padding[4];
  65         union {
  66                 /*
  67                  * Ensure the 'extended' union has the same size for both
  68                  * 32-bit and 64-bit builds.
  69                  */
  70                 char padding[LTTNG_SESSION_PADDING1];
  71                 void *ptr;
  72         } extended;
  73 };
  74
  75 /*
  76  * Create a session on the session daemon from a session descriptor.
  77  *
  78  * See the session descriptor API description in session-descriptor.h
  79  *
  80  * Note that unspecified session descriptor parameters, such as a session's
  81  * name, are updated in the session descriptor if the creation of the session
  82  * succeeds. This allows users to query the session's auto-generated name
  83  * after its creation. Note that other attributes can be queried using the
  84  * session listing API.
  85  *
  86  * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other
  87  * return codes.
  88  */
  89 extern enum lttng_error_code lttng_create_session_ext(
  90                 struct lttng_session_descriptor *session_descriptor);
  91
  92 /*
  93  * Create a tracing session using a name and an optional URL.
  94  *
  95  * If _url_ is NULL, no consumer is created for the session. The name can't be
  96  * NULL here.
  97  *
  98  * Return 0 on success else a negative LTTng error code.
  99  */
 100 extern int lttng_create_session(const char *name, const char *url);
 101
 102 /*
 103  * Create a tracing session that will exclusively be used for snapshot meaning
 104  * the session will be in no output mode and every channel enabled for that
 105  * session will be set in overwrite mode and in mmap output since splice is not
 106  * supported.
 107  *
 108  * Name can't be NULL. If an url is given, it will be used to create a default
 109  * snapshot output using it as a destination. If NULL, no output will be
 110  * defined and an add-output call will be needed.
 111  *
 112  * Return 0 on success else a negative LTTng error code.
 113  */
 114 extern int lttng_create_session_snapshot(const char *name,
 115                 const char *snapshot_url);
 116
 117 /*
 118  * Create a session exclusively used for live reading.
 119  *
 120  * In this mode, the switch-timer parameter is forced for each UST channel, a
 121  * live-switch-timer is enabled for kernel channels, manually setting
 122  * switch-timer is forbidden. Synchronization beacons are sent to the relayd,
 123  * indexes are sent and metadata is checked for each packet.
 124  *
 125  * Name can't be NULL. If no URL is given, the default is to send the data to
 126  * net://127.0.0.1. The timer_interval is in usec.
 127  *
 128  * Return 0 on success else a negative LTTng error code.
 129  */
 130 extern int lttng_create_session_live(const char *name, const char *url,
 131                 unsigned int timer_interval);
 132
 133 /*
 134  * Destroy a tracing session.
 135  *
 136  * The session will not be usable, tracing will be stopped thus buffers will be
 137  * flushed.
 138  *
 139  * This call will wait for data availability for each domain of the session,
 140  * which can take an arbitrary amount of time. However, when returning the
 141  * tracing data is guaranteed to be ready to be read and analyzed.
 142  *
 143  * lttng_destroy_session_no_wait() may be used if such a guarantee is not
 144  * needed.
 145  *
 146  * The name can't be NULL here.
 147  *
 148  * Return 0 on success else a negative LTTng error code.
 149  */
 150 extern int lttng_destroy_session(const char *name);
 151
 152 /*
 153  * Destroy a tracing session.
 154  *
 155  * Performs the same function as lttng_destroy_session(), but provides
 156  * an lttng_destruction_handle which can be used to wait for the completion
 157  * of the session's destruction. The lttng_destroy_handle can also be used
 158  * obtain the status and archive location of any implicit session
 159  * rotation that may have occurred during the session's destruction.
 160  *
 161  * Returns LTTNG_OK on success. The returned handle is owned by the caller
 162  * and must be free'd using lttng_destruction_handle_destroy().
 163  */
 164 extern enum lttng_error_code lttng_destroy_session_ext(const char *session_name,
 165                 struct lttng_destruction_handle **handle);
 166
 167 /*
 168  * Behaves exactly like lttng_destroy_session but does not wait for data
 169  * availability.
 170  */
 171 extern int lttng_destroy_session_no_wait(const char *name);
 172
 173 /*
 174  * List all the tracing sessions.
 175  *
 176  * Return the number of entries of the "lttng_session" array. The caller
 177  * must free the returned sessions array directly using free().
 178  *
 179  * On error, a negative LTTng error code is returned.
 180  */
 181 extern int lttng_list_sessions(struct lttng_session **sessions);
 182
 183 /*
 184  * Get the creation time of an lttng_session object on the session daemon.
 185  *
 186  * This function must only be used with lttng_session objects returned
 187  * by lttng_list_sessions() or lttng_session_create().
 188  *
 189  * The creation time returned is a UNIX timestamp; the number of seconds since
 190  * Epoch (1970-01-01 00:00:00 +0000 (UTC)).
 191  *
 192  * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other
 193  * return codes.
 194  */
 195 extern enum lttng_error_code lttng_session_get_creation_time(
 196                 const struct lttng_session *session, uint64_t *creation_time);
 197
 198 /*
 199  * Set the shared memory path for a session.
 200  *
 201  * Sets the (optional) file system path where shared memory buffers will
 202  * be created for the session. This is useful for buffer extraction on
 203  * crash, when used with filesystems like pramfs.
 204  *
 205  * Return 0 on success else a negative LTTng error code.
 206  */
 207 extern int lttng_set_session_shm_path(const char *session_name,
 208                 const char *shm_path);
 209
 210 #ifdef __cplusplus
 211 }
 212 #endif
 213
 214 #endif /* LTTNG_SESSION_H */