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
11 #include <lttng/lttng-export.h>
17 struct lttng_session_descriptor
;
18 struct lttng_trace_format_descriptor
;
21 * Session descriptor API.
23 * A session descriptor is an object describing the immutable configuration
24 * options of an LTTng tracing session.
26 * When used with the lttng_create_session_ext() function, a session descriptor
27 * allows the creation of a tracing session of the following types: regular,
30 * Certain parameters can be omitted at the time of creation of a session
31 * descriptor to use default or auto-generated values selected by the
32 * session daemon. For instance, a session's name can be left unspecified,
33 * in which case one that is guaranteed not to clash with pre-existing
34 * sessions will be automatically be generated by the session daemon.
36 * Most session descriptors can be created in either "no output", local, or
37 * network output modes. The various output modes supported vary by session
40 * Regular session creation functions and output modes:
41 * * "no output": lttng_session_descriptor_create()
42 * * local: lttng_session_descriptor_local_create()
43 * * network: lttng_session_descriptor_network_create()
45 * Snapshot session creation functions and output modes:
46 * * "no output": lttng_session_descriptor_snapshot_create()
47 * * local: lttng_session_descriptor_snapshot_local_create()
48 * * network: lttng_session_descriptor_snapshot_network_create()
50 * Live session creation functions and output modes:
51 * * "no output": lttng_session_descriptor_live_create()
52 * * network: lttng_session_descriptor_live_network_create()
54 * Local output functions accept a 'path' parameter that must be an absolute
55 * path to which the user has write access. When a local output is automatically
56 * generated, it adopts the form:
57 * $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME
59 * Where CREATION_TIME is time of the creation of the session on the session
60 * daemon in the form "yyyymmdd-hhmmss".
62 * Network output locations can also be auto-generated by leaving the
63 * 'control_url' and 'data_url' output parameters unspecified. In such cases,
64 * the session daemon will create a default output targeting a relay daemon
65 * at net://127.0.0.1, using the default 'control' and 'data' ports.
67 * The format of the 'control_url' and 'data_url' parameters is:
68 * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
70 * NETPROTO: Network protocol, amongst:
71 * * net: TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
72 * are defined at build time of the lttng toolchain.
73 * * net6: TCP over IPv6: same default ports as the 'net' protocol.
74 * * tcp: Same as the 'net' protocol.
75 * * tcp6: Same as the 'net6' protocol.
77 * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed
78 * in brackets; see RFC 2732).
80 * CTRLPORT: Control port.
82 * DATAPORT: Data port.
84 * TRACEPATH: Path of trace files on the remote file system. This path is
85 * relative to the base output directory set on the relay daemon
88 * The 'data_url' parameter is optional:
89 * * This parameter is meaningless for local tracing.
90 * * If 'control_url' is specified and a network protocol is used, the
91 * default data port, and the 'control_url' host will be used.
94 enum lttng_session_descriptor_status
{
95 /* Invalid session descriptor parameter. */
96 LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID
= -1,
97 LTTNG_SESSION_DESCRIPTOR_STATUS_OK
= 0,
98 /* Session descriptor parameter is unset. */
99 LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET
= 1,
103 * Create a session descriptor in no-output mode.
105 * The 'name' parameter can be left NULL to auto-generate a session name.
107 * Returns an lttng_session_descriptor instance on success, NULL on error.
109 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
110 lttng_session_descriptor_create(const char *name
);
113 * Create a session descriptor with a local output destination.
115 * The 'name' parameter can be left NULL to auto-generate a session name.
117 * The 'path' must either be an absolute path or it can be left NULL to
118 * use the default local output destination.
120 * Returns an lttng_session_descriptor instance on success, NULL on error.
122 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
123 lttng_session_descriptor_local_create(const char *name
, const char *path
);
126 * Create a session descriptor with a remote output destination.
128 * The 'name' parameter can be left NULL to auto-generate a session name.
130 * The 'control_url' and 'data_url' must conform to the URL format
131 * described above or can be left NULL to use the default network output.
133 * Returns an lttng_session_descriptor instance on success, NULL on error.
135 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
136 lttng_session_descriptor_network_create(const char *name
,
137 const char *control_url
, const char *data_url
);
140 * Create a snapshot session descriptor without a default output.
142 * The 'name' parameter can be left NULL to auto-generate a session name.
144 * Returns an lttng_session_descriptor instance on success, NULL on error.
146 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
147 lttng_session_descriptor_snapshot_create(const char *name
);
150 * Create a snapshot session descriptor with a local output destination.
152 * The 'name' parameter can be left NULL to auto-generate a session name.
154 * The 'path' must either be an absolute path or it can be left NULL to
155 * use the default local output destination as the default snapshot output.
157 * Returns an lttng_session_descriptor instance on success, NULL on error.
159 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
160 lttng_session_descriptor_snapshot_local_create(const char *name
,
164 * Create a snapshot session descriptor with a remote output destination.
166 * The 'name' parameter can be left NULL to auto-generate a session name.
168 * The 'control_url' and 'data_url' must conform to the URL format
169 * described above or can be left NULL to use the default network output as
170 * the default snapshot output.
172 * Returns an lttng_session_descriptor instance on success, NULL on error.
174 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
175 lttng_session_descriptor_snapshot_network_create(const char *name
,
176 const char *control_url
, const char *data_url
);
179 * Create a live session descriptor without an output.
181 * The 'name' parameter can be left NULL to auto-generate a session name.
183 * The 'live_timer_interval_us' parameter is the live timer's period, specified
186 * This parameter can't be 0. There is no default value defined for a live
189 * Returns an lttng_session_descriptor instance on success, NULL on error.
191 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
192 lttng_session_descriptor_live_create(
193 const char *name
, unsigned long long live_timer_interval_us
);
196 * Create a live session descriptor with a remote output destination.
198 * The 'name' parameter can be left NULL to auto-generate a session name.
200 * The 'control_url' and 'data_url' must conform to the URL format
201 * described above or can be left NULL to use the default network output.
203 * The 'live_timer_interval_us' parameter is the live timer's period, specified
206 * This parameter can't be 0. There is no default value defined for a live
209 * Returns an lttng_session_descriptor instance on success, NULL on error.
211 LTTNG_EXPORT
extern struct lttng_session_descriptor
*
212 lttng_session_descriptor_live_network_create(
214 const char *control_url
, const char *data_url
,
215 unsigned long long live_timer_interval_us
);
218 * Get a session descriptor's session name.
220 * The 'name' parameter is used as an output parameter and will point to
221 * the session descriptor's session name on success
222 * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
223 * for other return codes. The pointer returned through 'name' is only
224 * guaranteed to remain valid until the next method call on the session
227 * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
228 * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are
229 * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
230 * name parameter is unset.
232 LTTNG_EXPORT
extern enum lttng_session_descriptor_status
233 lttng_session_descriptor_get_session_name(
234 const struct lttng_session_descriptor
*descriptor
,
238 * Get a session descriptor's trace format descriptor.
240 * The 'trace_format_descriptor' parameter is used as an output parameter and will point to
241 * the session descriptor's trace format descriptor on success
242 * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
243 * for other return codes. The pointer returned through 'trace_format_descriptor' is only
244 * guaranteed to remain valid until the next method call on the session
247 * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
248 * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'trace_format_descriptor' are
251 LTTNG_EXPORT
extern enum lttng_session_descriptor_status
252 lttng_session_descriptor_get_trace_format_descriptor(
253 const struct lttng_session_descriptor
*session_descriptor
,
254 const struct lttng_trace_format_descriptor
**trace_format_descriptor
);
257 * Set a session descriptor's trace format descriptor.
259 * The trace format descriptor is copied internally.
261 * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
262 * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'trace_format_descriptor' are
265 LTTNG_EXPORT
extern enum lttng_session_descriptor_status
266 lttng_session_descriptor_set_trace_format_descriptor(
267 struct lttng_session_descriptor
*session_descriptor
,
268 const struct lttng_trace_format_descriptor
*trace_format_descriptor
);
271 * Destroy a local lttng_session object.
273 * This does not destroy the session on the session daemon; it releases
274 * the resources allocated by the descriptor object.
276 LTTNG_EXPORT
extern void lttng_session_descriptor_destroy(
277 struct lttng_session_descriptor
*descriptor
);
283 #endif /* LTTNG_SESSION_DESCRIPTOR_H */