2 * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
3 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
5 * SPDX-License-Identifier: LGPL-2.1-only
9 #ifndef LTTNG_SESSION_H
10 #define LTTNG_SESSION_H
16 #include <lttng/lttng-export.h>
19 @addtogroup api_session
23 #include <lttng/constant.h>
26 struct lttng_session_descriptor
;
27 struct lttng_destruction_handle
;
29 #define LTTNG_SESSION_PADDING1 8
33 Recording session summary.
35 The purpose of such a structure is to provide information about a
36 \lt_obj_session itself, but not about its \lt_obj_domains
37 and \lt_obj_channels (use lttng_list_domains() and lttng_list_channels()
40 lttng_list_sessions() sets a pointer to an array of all the available
41 recording session summaries.
43 struct lttng_session
{
45 char name
[LTTNG_NAME_MAX
];
49 <em>Human-readable</em> representation of the output (local
56 1 if this recording session is active (started), or 0
59 @sa lttng_start_tracing() --
60 Starts a recording session.
61 @sa lttng_stop_tracing() --
62 Stops a recording session.
64 uint32_t enabled
; /* enabled/started: 1, disabled/stopped: 0 */
68 1 if this recording session was created in
69 \ref api-session-snapshot-mode "snapshot mode",
73 If this member is 1, then the
74 lttng_session::live_timer_interval member is 0.
76 uint32_t snapshot_mode
;
80 Period (µs) of the \ref api-channel-live-timer "live timers"
81 of the channels of this recording session, or 0 if this
82 recording session wasn't created in
83 \ref api-session-live-mode "live mode".
86 If this member is \em not 0, then the
87 lttng_session::snapshot_mode member is 0.
89 unsigned int live_timer_interval
; /* usec */
92 * End of public attributes.
93 * The remaining fields are used to deal with ABI management concerns.
97 * 32-bit architectures are already naturally aligned on 4 bytes after
98 * 'live_timer_interval'. However, the offset does not result in a
99 * natural alignment on 64-bit architectures. Adding 4 bytes of
100 * padding here results in an aligned offset after 'alignement_padding'
101 * for both bitnesses.
103 * This was added since not all compilers appear to align unions in the
104 * same way. Some (e.g. MSVC) do not seem to impose an alignement
105 * constraint while others (e.g. gcc, clang, icc) seem to align it to
106 * ensure 'ptr' is naturally aligned.
108 char alignment_padding
[4];
111 * Ensure the 'extended' union has the same size for both
112 * 32-bit and 64-bit builds.
114 char padding
[LTTNG_SESSION_PADDING1
];
121 Creates a recording session from the recording session descriptor
122 \lt_p{session_descriptor}.
124 See \ref api_session_descr to learn how to create a recording session
127 On success, if the name property of \lt_p{session_descriptor} isn't set,
128 this function sets it to the automatically generated name of the
129 recording session. Get the recording session name with
130 lttng_session_descriptor_get_session_name().
132 @param[in] session_descriptor
133 Descriptor from which to create a recording session.
136 #LTTNG_OK on success, or a \em negative enumerator otherwise.
139 @lt_pre_not_null{session_descriptor}
141 If the name property of \lt_p{session_descriptor} is set, then no
142 available recording session has this name.
144 @sa \ref api_session_descr.
145 @sa \lt_man{lttng-create,1}
147 LTTNG_EXPORT
extern enum lttng_error_code
148 lttng_create_session_ext(struct lttng_session_descriptor
*session_descriptor
);
152 Creates a recording session named \lt_p{session_name} in
153 \ref api-session-local-mode "local"
154 or \ref api-session-net-mode "network streaming" mode, optionally
155 setting its output URL to \lt_p{output_url}.
158 Use lttng_create_session_ext() with a dedicated
159 local or network streaming
160 \ref api_session_descr "recording session descriptor".
162 @param[in] session_name
163 Name of the new recording session.
164 @param[in] output_url
166 \ref api-session-url "Output URL" of the recording session to
169 If it's a \ref api-session-one-port-url "single-port output URL",
170 then the trace data port is \lt_def_net_data_port.
172 If \c NULL, LTTng doesn't write any trace data for this recording
177 0 on success, or a \em negative #lttng_error_code enumerator
181 @lt_pre_not_null{session_name}
182 @lt_pre_sess_name_not_auto{session_name}
184 No available recording session is named \lt_p{session_name}.
186 <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid
187 \ref api-session-url "output URL".
189 @sa lttng_create_session_snapshot() --
190 Creates a recording session in snapshot mode.
191 @sa lttng_create_session_live() --
192 Creates a recording session in live mode.
193 @sa \lt_man{lttng-create,1}
195 LTTNG_EXPORT
extern int lttng_create_session(const char *session_name
, const char *output_url
);
199 Creates a recording session named \lt_p{session_name} in
200 \ref api-session-snapshot-mode "snapshot" mode, optionally setting
201 the URL of its initial snapshot output to \lt_p{output_url}.
204 Use lttng_create_session_ext() with a dedicated snapshot
205 \ref api_session_descr "recording session descriptor".
207 @param[in] session_name
208 Name of the new recording session.
209 @param[in] output_url
211 \ref api-session-url "URL" of an initial snapshot output
212 which LTTng adds to this recording session.
214 If it's a \ref api-session-one-port-url "single-port output URL",
215 then the trace data port is \lt_def_net_data_port.
217 This initial snapshot output is named <code>snapshot-0</code>.
219 If \c NULL, then the created recording session has no initial
220 snapshot output: you need to either add one with
221 lttng_snapshot_add_output() or provide one when you take a snapshot
222 with lttng_snapshot_record().
226 0 on success, or a \em negative #lttng_error_code enumerator
230 @lt_pre_not_null{session_name}
231 @lt_pre_sess_name_not_auto{session_name}
233 No available recording session is named \lt_p{session_name}.
235 <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid
236 \ref api-session-url "output URL".
238 @sa lttng_create_session() --
239 Creates a recording session in local or network streaming mode.
240 @sa lttng_create_session_live() --
241 Creates a recording session in live mode.
242 @sa \lt_man{lttng-create,1}
244 LTTNG_EXPORT
extern int lttng_create_session_snapshot(const char *session_name
,
245 const char *output_url
);
249 Creates a recording session named \lt_p{session_name} in
250 \ref api-session-live-mode "live" mode, optionally setting its
251 URL to \lt_p{output_url}.
254 Use lttng_create_session_ext() with a dedicated live
255 \ref api_session_descr "recording session descriptor".
257 @param[in] session_name
258 Name of the new recording session.
259 @param[in] output_url
261 \ref api-session-url "Output URL" of the recording session to
262 create: \ref api-session-one-port-url "single-port" or
263 \ref api-session-two-port-url "two-port".
265 If it's a \ref api-session-one-port-url "single-port output URL",
266 then the trace data port is \lt_def_net_data_port.
268 If \c NULL, this function uses \lt_def_net_url.
270 @param[in] live_timer_period
271 Period (µs) of the \ref api-channel-live-timer "live timers" of all
272 the channels of the created recording session.
275 0 on success, or a \em negative #lttng_error_code enumerator
279 @lt_pre_not_null{session_name}
280 @lt_pre_sess_name_not_auto{session_name}
282 No available recording session is named \lt_p{session_name}.
284 <strong>If not \c NULL</strong>, \lt_p{output_url} is a valid
285 \ref api-session-one-port-url "single-port output URL" or
286 \ref api-session-two-port-url "two-port output URL".
288 \lt_p{live_timer_period} ≥ 1
290 @sa lttng_create_session() --
291 Creates a recording session in local or network streaming mode.
292 @sa lttng_create_session_snapshot() --
293 Creates a recording session in snapshot mode.
294 @sa \lt_man{lttng-create,1}
296 LTTNG_EXPORT
extern int lttng_create_session_live(const char *session_name
,
297 const char *output_url
,
298 unsigned int live_timer_period
);
302 Destroys the recording session named \lt_p{session_name}, blocking
303 until the operation completes.
306 Use lttng_destroy_session_ext().
308 "Destroying" a recording session means freeing the resources which the
309 LTTng daemons and tracers acquired for it, also making sure to flush all
310 the recorded trace data to either the local file system or the connected
311 LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the
312 \ref api-session-modes "recording session mode".
314 This function stops any recording activity within the recording session
315 named \lt_p{session_name}.
317 This function implicitly calls lttng_stop_tracing(), blocking until the
318 trace data of the recording session becomes valid. Use
319 lttng_destroy_session_no_wait() to avoid a blocking call.
321 @param[in] session_name
322 Name of the recording session to destroy.
325 0 on success, or a \em negative #lttng_error_code enumerator
329 @lt_pre_not_null{session_name}
330 @lt_pre_sess_exists{session_name}
332 @sa lttng_destroy_session_no_wait() --
333 Initiates the destruction operation of a recording session,
334 returning immediately.
335 @sa \lt_man{lttng-destroy,1}
337 LTTNG_EXPORT
extern int lttng_destroy_session(const char *session_name
);
341 Initiates the destruction operation of the recording session named
345 Use lttng_destroy_session_ext().
347 "Destroying" a recording session means freeing the resources which the
348 LTTng daemons and tracers acquired for it, also making sure to flush all
349 the recorded trace data to either the local file system or the connected
350 LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the
351 \ref api-session-modes "recording session mode".
353 Unlike lttng_destroy_session(), this function does \em not block until
354 the destruction operation is complete: it returns immediately. This
355 means the trace(s) of the recording session might not be valid when
356 this function returns, and there's no way to know when it/they become
359 @param[in] session_name
360 Name of the recording session to destroy.
363 0 on success, or a \em negative #lttng_error_code enumerator
367 @lt_pre_not_null{session_name}
368 @lt_pre_sess_exists{session_name}
370 No destruction operation is in progress for the recording session
371 named \lt_p{session_name}.
373 @sa lttng_destroy_session() --
374 Destroys a recording session, blocking until the operation
376 @sa \lt_man{lttng-destroy,1}
378 LTTNG_EXPORT
extern int lttng_destroy_session_no_wait(const char *session_name
);
382 Initiates a destruction operation of the recording session
383 named \lt_p{session_name}.
385 "Destroying" a recording session means freeing the resources which the
386 LTTng daemons and tracers acquired for it, also making sure to flush all
387 the recorded trace data to either the local file system or the connected
388 LTTng relay daemon (see \lt_man{lttng-relayd,8}), depending on the
389 \ref api-session-modes "recording session mode".
391 This function doesn't block until the destruction operation completes:
392 it only initiates the operation.
393 Use \lt_p{*handle} to wait for the operation to complete.
395 @param[in] session_name
396 Name of the recording session to destroy.
399 <strong>On success</strong>, this function sets \lt_p{*handle} to
400 a handle which identifies this recording session destruction
405 Wait for the completion of this destruction operation with
406 lttng_destruction_handle_wait_for_completion().
408 Destroy \lt_p{*handle} with lttng_destruction_handle_destroy().
412 #LTTNG_OK on success, or a \em negative enumerator otherwise.
415 @lt_pre_not_null{session_name}
416 @lt_pre_sess_exists{session_name}
418 No destruction operation is in progress for the recording session
419 named \lt_p{session_name}.
421 @sa \lt_man{lttng-destroy,1}
423 LTTNG_EXPORT
extern enum lttng_error_code
424 lttng_destroy_session_ext(const char *session_name
, struct lttng_destruction_handle
**handle
);
428 Sets \lt_p{*sessions} to the summaries of all the available
433 <strong>On success</strong>, this function sets \lt_p{*sessions} to
434 the summaries of the available recording sessions.
436 Free \lt_p{*sessions} with <code>free()</code>.
440 The number of items in \lt_p{*sessions} on success, or a \em
441 negative #lttng_error_code enumerator otherwise.
444 @lt_pre_not_null{sessions}
446 @sa \lt_man{lttng-list,1}
448 LTTNG_EXPORT
extern int lttng_list_sessions(struct lttng_session
**sessions
);
452 Sets \lt_p{*creation_timestamp} to the timestamp of the creation of
453 the recording session summarized by \lt_p{session}.
456 Summary of the recording session of which to get the creation
457 timestamp, as obtained with lttng_list_sessions().
458 @param[out] creation_timestamp
459 <strong>On success</strong>, this function sets
460 \lt_p{*creation_timestamp} to the Unix timestamp of the creation of
464 #LTTNG_OK on success, or a \em negative enumerator otherwise.
467 @lt_pre_not_null{session}
469 The recording session summarized by \lt_p{session} is accessible
470 within the connected session daemon.
471 @lt_pre_not_null{creation_timestamp}
473 LTTNG_EXPORT
extern enum lttng_error_code
474 lttng_session_get_creation_time(const struct lttng_session
*session
, uint64_t *creation_timestamp
);
478 Sets the path of the directory containing the shared memory files
479 holding the channel ring buffers of the recording session named
480 \lt_p{session_name} on the local file sytem to \lt_p{shm_dir}.
482 Specifying a location on an
483 <a href="https://en.wikipedia.org/wiki/Non-volatile_random-access_memory">NVRAM</a>
484 file system makes it possible to recover the latest recorded trace data
485 when the system reboots after a crash with the \lt_man{lttng-crash,1}
488 @param[in] session_name
489 Name of the recording session of which to set the shared memory
492 Path of the directory containing the shared memory files of the
493 recording session named \lt_p{session_name}.
496 0 on success, or a \em negative #lttng_error_code enumerator
500 @lt_pre_not_null{session_name}
501 @lt_pre_sess_exists{session_name}
502 @lt_pre_sess_never_active{session_name}
503 @lt_pre_not_null{shm_dir}
505 \lt_p{shm_dir} is a writable directory.
507 LTTNG_EXPORT
extern int lttng_set_session_shm_path(const char *session_name
, const char *shm_dir
);
515 #endif /* LTTNG_SESSION_H */
This page took 0.044156 seconds and 4 git commands to generate.