2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef LTTNG_SESSION_DESCRIPTOR_H
9 #define LTTNG_SESSION_DESCRIPTOR_H
15 #include <lttng/lttng-export.h>
18 @addtogroup api_session_descr
23 @struct lttng_session_descriptor
26 Recording session descriptor (opaque type).
28 struct lttng_session_descriptor
;
31 * Session descriptor API.
33 * A session descriptor is an object describing the immutable configuration
34 * options of an LTTng tracing session.
36 * When used with the lttng_create_session_ext() function, a session descriptor
37 * allows the creation of a tracing session of the following types: regular,
40 * Certain parameters can be omitted at the time of creation of a session
41 * descriptor to use default or auto-generated values selected by the
42 * session daemon. For instance, a session's name can be left unspecified,
43 * in which case one that is guaranteed not to clash with pre-existing
44 * sessions will be automatically be generated by the session daemon.
46 * Most session descriptors can be created in either "no output", local, or
47 * network output modes. The various output modes supported vary by session
50 * Regular session creation functions and output modes:
51 * * "no output": lttng_session_descriptor_create()
52 * * local: lttng_session_descriptor_local_create()
53 * * network: lttng_session_descriptor_network_create()
55 * Snapshot session creation functions and output modes:
56 * * "no output": lttng_session_descriptor_snapshot_create()
57 * * local: lttng_session_descriptor_snapshot_local_create()
58 * * network: lttng_session_descriptor_snapshot_network_create()
60 * Live session creation functions and output modes:
61 * * "no output": lttng_session_descriptor_live_create()
62 * * network: lttng_session_descriptor_live_network_create()
64 * Local output functions accept a 'path' parameter that must be an absolute
65 * path to which the user has write access. When a local output is automatically
66 * generated, it adopts the form:
67 * $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME
69 * Where CREATION_TIME is time of the creation of the session on the session
70 * daemon in the form "yyyymmdd-hhmmss".
72 * Network output locations can also be auto-generated by leaving the
73 * 'control_url' and 'data_url' output parameters unspecified. In such cases,
74 * the session daemon will create a default output targeting a relay daemon
75 * at net://127.0.0.1, using the default 'control' and 'data' ports.
77 * The format of the 'control_url' and 'data_url' parameters is:
78 * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
80 * NETPROTO: Network protocol, amongst:
81 * * net: TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
82 * are defined at build time of the lttng toolchain.
83 * * net6: TCP over IPv6: same default ports as the 'net' protocol.
84 * * tcp: Same as the 'net' protocol.
85 * * tcp6: Same as the 'net6' protocol.
87 * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed
88 * in brackets; see RFC 2732).
90 * CTRLPORT: Control port.
92 * DATAPORT: Data port.
94 * TRACEPATH: Path of trace files on the remote file system. This path is
95 * relative to the base output directory set on the relay daemon
98 * The 'data_url' parameter is optional:
99 * * This parameter is meaningless for local tracing.
100 * * If 'control_url' is specified and a network protocol is used, the
101 * default data port, and the 'control_url' host will be used.
106 Return type of recording session descriptor fuctions.
108 Error status enumerators have a negative value.
110 enum lttng_session_descriptor_status
{
112 LTTNG_SESSION_DESCRIPTOR_STATUS_OK
= 0,
114 /// Unsatisfied precondition.
115 LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID
= -1,
117 /// Recording session descriptor property is not set.
118 LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET
= 1,
123 Creates a recording session descriptor to create a no-output,
124 \ref api-session-local-mode "local" recording session
125 named \lt_p{session_name}.
127 LTTng won't write any trace data for a recording session created from
128 the returned descriptor.
130 @param[in] session_name
132 Recording session name.
134 If \c NULL, LTTng automatically generates a recording session name
135 when you call lttng_create_session_ext().
137 Call lttng_session_descriptor_get_session_name() with the returned
138 recording session descriptor after successfully calling
139 lttng_create_session_ext() to get the generated name.
144 Recording session descriptor on success, or \c NULL on error.
146 Destroy the returned descriptor with
147 lttng_session_descriptor_destroy().
150 @sa lttng_session_descriptor_local_create() --
151 Creates a recording session descriptor to create a
152 \ref api-session-local-mode "local" recording session with an
155 @lt_pre_sess_name_not_auto{session_name}
157 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
158 lttng_session_descriptor_create(const char *session_name
);
162 Creates a recording session descriptor to create a
163 \ref api-session-local-mode "local" recording session
164 named \lt_p{session_name}.
166 @param[in] session_name
168 Recording session name.
170 If \c NULL, LTTng automatically generates a recording session name
171 when you call lttng_create_session_ext().
173 Call lttng_session_descriptor_get_session_name() with the returned
174 recording session descriptor after successfully calling
175 lttng_create_session_ext() to get the generated name.
179 Absolute path of the directory containing the traces of the
180 recording session you create from the returned descriptor.
182 If \c NULL, the output directory is, after calling
183 lttng_create_session_ext(),
184 <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>,
188 <dt><code><em>$LTTNG_HOME</em></code>
190 The value of the \c LTTNG_HOME environment variable, or
191 of the \c HOME environment variable if \c LTTNG_HOME isn't
194 <dt><code><em>NAME</em></code>
196 Recording session name (\lt_p{session_name} if not \c NULL, or
197 an automatically generated name otherwise).
199 <dt><code><em>TS</em></code>
201 \link lttng_session_get_creation_time() Timestamp of the
202 creation\endlink of the recording session using the
203 <code>YYYYmmdd-HHMMSS</code> form.
209 Recording session descriptor on success, or \c NULL on error.
211 Destroy the returned descriptor with
212 lttng_session_descriptor_destroy().
215 @lt_pre_sess_name_not_auto{session_name}
217 <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path.
219 @sa lttng_session_descriptor_create() --
220 Creates a recording session descriptor to create a
221 \ref api-session-local-mode "local" recording session without an
224 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
225 lttng_session_descriptor_local_create(const char *session_name
, const char *trace_dir
);
229 Creates a recording session descriptor to create a
230 \ref api-session-net-mode "network streaming" recording session
231 named \lt_p{session_name}.
233 The valid combinations of \lt_p{control_url} and \lt_p{data_url} are:
237 <th>\lt_p{control_url}
244 Use \lt_def_net_ctrl_url as \lt_p{control_url}.
246 Use \lt_def_net_data_url as \lt_p{data_url}.
248 <td>\ref api-session-one-port-url "Single-port output URL"
251 Use the protocol, host, and trace directory (if any) of
252 \lt_p{control_url} and the port \lt_def_net_data_port
255 <td>Single-port output URL
257 Single-port output URL with the exact same protocol, host,
258 and trace directory (if any) as \lt_p{control_url}.
260 Use the specified output URLs.
262 <td>\ref api-session-two-port-url "Two-port output URL"
265 Use the protocol, host, data port, and trace directory (if any)
266 of \lt_p{control_url} as \lt_p{data_url}.
269 @param[in] session_name
271 Recording session name.
273 If \c NULL, LTTng automatically generates a recording session name
274 when you call lttng_create_session_ext().
276 Call lttng_session_descriptor_get_session_name() with the returned
277 recording session descriptor after successfully calling
278 lttng_create_session_ext() to get the generated name.
280 @param[in] control_url
285 <dt>\ref api-session-one-port-url "Single-port output URL"
287 Indicates where (to which relay daemon; see
288 \lt_man{lttng-relayd,8}) to send the control data.
290 <dt>\ref api-session-two-port-url "Two-port output URL"
292 Indicates where to send the control \em and trace data.
295 If \c NULL, this function uses \lt_def_net_url.
299 \ref api-session-one-port-url "Single-port output URL" which
300 indicates where to send the trace data.
302 May be <code>NULL</code>: see the table above for the default value
303 depending on \lt_p{control_url}.
308 Recording session descriptor on success, or \c NULL on error.
310 Destroy the returned descriptor with
311 lttng_session_descriptor_destroy().
314 @lt_pre_sess_name_not_auto{session_name}
316 \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid
317 combinations shown in the table above.
319 LTTNG_EXPORT
extern struct lttng_session_descriptor
*lttng_session_descriptor_network_create(
320 const char *session_name
, const char *control_url
, const char *data_url
);
324 Creates a recording session descriptor to create a
325 \ref api-session-snapshot-mode "snapshot" recording session
326 named \lt_p{session_name} without an initial output.
328 A recording session which lttng_create_session_ext() creates from the
329 returned descriptor has no initial snapshot output: you need to either
330 add one with lttng_snapshot_add_output() or provide one when you take a
331 snapshot with lttng_snapshot_record().
333 @param[in] session_name
335 Recording session name.
337 If \c NULL, LTTng automatically generates a recording session name
338 when you call lttng_create_session_ext().
340 Call lttng_session_descriptor_get_session_name() with the returned
341 recording session descriptor after successfully calling
342 lttng_create_session_ext() to get the generated name.
347 Recording session descriptor on success, or \c NULL on error.
349 Destroy the returned descriptor with
350 lttng_session_descriptor_destroy().
353 @lt_pre_sess_name_not_auto{session_name}
355 @sa lttng_session_descriptor_snapshot_local_create() --
356 Creates a recording session descriptor to create a
357 \ref api-session-snapshot-mode "snapshot" recording session
358 with an initial local output.
359 @sa lttng_session_descriptor_snapshot_network_create() --
360 Creates a recording session descriptor to create a
361 \ref api-session-snapshot-mode "snapshot" recording session
362 with an initial remote output.
364 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
365 lttng_session_descriptor_snapshot_create(const char *session_name
);
369 Creates a recording session descriptor to create a
370 \ref api-session-snapshot-mode "snapshot" recording session
371 named \lt_p{session_name} and having an initial local output.
373 Using the returned descriptor when you call lttng_create_session_ext()
374 to create a snapshot recording session is similar to using a descriptor
375 which lttng_session_descriptor_snapshot_create() returns and calling
376 lttng_snapshot_add_output() after creating the recording session.
378 The name of this initial snapshot output is <code>snapshot-0</code>.
380 @param[in] session_name
382 Recording session name.
384 If \c NULL, LTTng automatically generates a recording session name
385 when you call lttng_create_session_ext().
387 Call lttng_session_descriptor_get_session_name() with the returned
388 recording session descriptor after successfully calling
389 lttng_create_session_ext() to get the generated name.
393 Absolute path of an initial snapshot output.
395 If \c NULL, the snapshot output directory is, after calling
396 lttng_create_session_ext(),
397 <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>,
401 <dt><code><em>$LTTNG_HOME</em></code>
403 The value of the \c LTTNG_HOME environment variable, or
404 of the \c HOME environment variable if \c LTTNG_HOME isn't
407 <dt><code><em>NAME</em></code>
409 Recording session name (\lt_p{session_name} if not \c NULL, or
410 an automatically generated name otherwise).
412 <dt><code><em>TS</em></code>
414 \link lttng_session_get_creation_time() Timestamp of the
415 creation\endlink of the recording session using the
416 <code>YYYYmmdd-HHMMSS</code> form.
422 Recording session descriptor on success, or \c NULL on error.
424 Destroy the returned descriptor with
425 lttng_session_descriptor_destroy().
428 @lt_pre_sess_name_not_auto{session_name}
430 <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path.
432 @sa lttng_session_descriptor_snapshot_create() --
433 Creates a recording session descriptor to create a
434 \ref api-session-snapshot-mode "snapshot" recording session
435 without an initial output.
436 @sa lttng_session_descriptor_snapshot_network_create() --
437 Creates a recording session descriptor to create a
438 \ref api-session-snapshot-mode "snapshot" recording session
439 with an initial remote output.
441 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
442 lttng_session_descriptor_snapshot_local_create(const char *session_name
, const char *trace_dir
);
446 Creates a recording session descriptor to create a
447 \ref api-session-snapshot-mode "snapshot" recording session
448 named \lt_p{session_name} and having an initial remote output.
450 Using the returned descriptor when you call lttng_create_session_ext()
451 to create a snapshot recording session is similar to using a descriptor
452 which lttng_session_descriptor_snapshot_create() returns and calling
453 lttng_snapshot_add_output() after creating the recording session.
455 The name of this initial snapshot output is <code>snapshot-0</code>.
457 The valid combinations of \lt_p{control_url} and \lt_p{data_url} are:
461 <th>\lt_p{control_url}
468 Use \lt_def_net_ctrl_url as \lt_p{control_url}.
470 Use \lt_def_net_data_url as \lt_p{data_url}.
472 <td>\ref api-session-one-port-url "Single-port output URL"
475 Use the protocol, host, and trace directory (if any) of
476 \lt_p{control_url} and the port \lt_def_net_data_port
479 <td>Single-port output URL
481 Single-port output URL with the exact same protocol, host,
482 and trace directory (if any) as \lt_p{control_url}.
484 Use the specified output URLs.
486 <td>\ref api-session-two-port-url "Two-port output URL"
489 Use the protocol, host, data port, and trace directory (if any)
490 of \lt_p{control_url} as \lt_p{data_url}.
493 @param[in] session_name
495 Recording session name.
497 If \c NULL, LTTng automatically generates a recording session name
498 when you call lttng_create_session_ext().
500 Call lttng_session_descriptor_get_session_name() with the returned
501 recording session descriptor after successfully calling
502 lttng_create_session_ext() to get the generated name.
504 @param[in] control_url
506 Control data URL of an initial snapshot output.
511 <dt>\ref api-session-one-port-url "Single-port output URL"
513 Indicates where (to which relay daemon; see
514 \lt_man{lttng-relayd,8}) to send the control data.
516 <dt>\ref api-session-two-port-url "Two-port output URL"
518 Indicates where to send the control \em and trace data.
521 If \c NULL, this function uses \lt_def_net_url.
525 Trace data URL of an initial snapshot output.
527 \ref api-session-one-port-url "Single-port output URL" which
528 indicates where to send the trace data.
530 May be <code>NULL</code>: see the table above for the default value
531 depending on \lt_p{control_url}.
536 Recording session descriptor on success, or \c NULL on error.
538 Destroy the returned descriptor with
539 lttng_session_descriptor_destroy().
542 @lt_pre_sess_name_not_auto{session_name}
544 \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid
545 combinations shown in the table above.
547 @sa lttng_session_descriptor_snapshot_create() --
548 Creates a recording session descriptor to create a
549 \ref api-session-snapshot-mode "snapshot" recording session
550 without an initial output.
551 @sa lttng_session_descriptor_snapshot_local_create() --
552 Creates a recording session descriptor to create a
553 \ref api-session-snapshot-mode "snapshot" recording session
554 with an initial local output.
556 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
557 lttng_session_descriptor_snapshot_network_create(const char *session_name
,
558 const char *control_url
,
559 const char *data_url
);
562 * NOTE: Not documented with Doxygen as what lttng_create_session_ext()
563 * creates from such a descriptor is useless (a live recording session
564 * without any output). Original documentation follows.
566 * Create a live session descriptor without an output.
568 * The 'name' parameter can be left NULL to auto-generate a session name.
570 * The 'live_timer_interval_us' parameter is the live timer's period, specified
573 * This parameter can't be 0. There is no default value defined for a live
576 * Returns an lttng_session_descriptor instance on success, NULL on error.
578 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
579 lttng_session_descriptor_live_create(const char *name
, unsigned long long live_timer_interval_us
);
583 Creates a recording session descriptor to create a
584 \ref api-session-live-mode "live" recording session
585 named \lt_p{session_name}.
587 The valid combinations of \lt_p{control_url} and \lt_p{data_url} are:
591 <th>\lt_p{control_url}
598 Use \lt_def_net_ctrl_url as \lt_p{control_url}.
600 Use \lt_def_net_data_url as \lt_p{data_url}.
602 <td>\ref api-session-one-port-url "Single-port output URL"
605 Use the protocol, host, and trace directory (if any) of
606 \lt_p{control_url} and the port \lt_def_net_data_port
609 <td>Single-port output URL
611 Single-port output URL with the exact same protocol, host,
612 and trace directory (if any) as \lt_p{control_url}.
614 Use the specified output URLs.
616 <td>\ref api-session-two-port-url "Two-port output URL"
619 Use the protocol, host, data port, and trace directory (if any)
620 of \lt_p{control_url} as \lt_p{data_url}.
623 @param[in] session_name
625 Recording session name.
627 If \c NULL, LTTng automatically generates a recording session name
628 when you call lttng_create_session_ext().
630 Call lttng_session_descriptor_get_session_name() with the returned
631 recording session descriptor after successfully calling
632 lttng_create_session_ext() to get the generated name.
634 @param[in] control_url
639 <dt>\ref api-session-one-port-url "Single-port output URL"
641 Indicates where (to which relay daemon; see
642 \lt_man{lttng-relayd,8}) to send the control data.
644 <dt>\ref api-session-two-port-url "Two-port output URL"
646 Indicates where to send the control \em and trace data.
649 If \c NULL, this function uses \lt_def_net_url.
653 \ref api-session-one-port-url "Single-port output URL" which
654 indicates where to send the trace data.
656 May be <code>NULL</code>: see the table above for the default value
657 depending on \lt_p{control_url}.
659 @param[in] live_timer_period
660 Period (µs) of the \ref api-channel-live-timer "live timers" of all
661 the channels of a recording session which lttng_create_session_ext()
662 creates from the returned descriptor.
666 Recording session descriptor on success, or \c NULL on error.
668 Destroy the returned descriptor with
669 lttng_session_descriptor_destroy().
672 @lt_pre_sess_name_not_auto{session_name}
674 \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid
675 combinations shown in the table above.
677 \lt_p{live_timer_period} ≥ 1
679 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
680 lttng_session_descriptor_live_network_create(const char *session_name
,
681 const char *control_url
,
682 const char *data_url
,
683 unsigned long long live_timer_period
);
686 * Get a session descriptor's session name.
688 * The 'name' parameter is used as an output parameter and will point to
689 * the session descriptor's session name on success
690 * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
691 * for other return codes. The pointer returned through 'name' is only
692 * guaranteed to remain valid until the next method call on the session
695 * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
696 * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are
697 * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
698 * name parameter is unset.
703 Sets \lt_p{*session_name} to the name of the recording session
704 which lttng_create_session_ext() created from the recording
705 session descriptor \lt_p{session_descriptor}.
707 Call this function after successfully calling lttng_create_session_ext()
708 when \lt_p{session_descriptor} wasn't created with a specific recording
709 session name to get the automatically generated name of the created
712 @param[in] session_descriptor
713 Recording session descriptor from which lttng_create_session_ext()
714 previously created the recording session of which to get the name.
715 @param[out] session_name
717 <strong>On success</strong>, this function sets \lt_p{*session_name}
718 to the name of the recording session which
719 lttng_create_session_ext() previously created from
720 \lt_p{session_descriptor}.
722 \lt_p{session_descriptor} owns \lt_p{*session_name}.
724 \lt_p{*session_name} remains valid until the next recording
725 session descriptor function call with \lt_p{session_descriptor}.
728 @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_OK
730 @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID
731 Unsatisfied precondition.
732 @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET
733 The name property of \lt_p{session_descriptor} is not set.
735 @lt_pre_not_null{session_descriptor}
737 You successfully called lttng_create_session_ext() with
738 \lt_p{session_descriptor}.
739 @lt_pre_not_null{session_name}
741 LTTNG_EXPORT
extern enum lttng_session_descriptor_status
742 lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor
*session_descriptor
,
743 const char **session_name
);
747 Destroys the recording session descriptor \lt_p{session_descriptor}.
751 This function doesn't destroy the recording session which
752 lttng_create_session_ext() created from \lt_p{session_descriptor},
753 but only the descriptor itself.
755 Use lttng_destroy_session_ext() to destroy a recording session.
758 @param[in] session_descriptor
760 Recording session descriptor to destroy.
765 LTTNG_EXPORT
extern void
766 lttng_session_descriptor_destroy(struct lttng_session_descriptor
*session_descriptor
);
774 #endif /* LTTNG_SESSION_DESCRIPTOR_H */