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 struct lttng_session_descriptor
;
18 * Session descriptor API.
20 * A session descriptor is an object describing the immutable configuration
21 * options of an LTTng tracing session.
23 * When used with the lttng_create_session_ext() function, a session descriptor
24 * allows the creation of a tracing session of the following types: regular,
27 * Certain parameters can be omitted at the time of creation of a session
28 * descriptor to use default or auto-generated values selected by the
29 * session daemon. For instance, a session's name can be left unspecified,
30 * in which case one that is guaranteed not to clash with pre-existing
31 * sessions will be automatically be generated by the session daemon.
33 * Most session descriptors can be created in either "no output", local, or
34 * network output modes. The various output modes supported vary by session
37 * Regular session creation functions and output modes:
38 * * "no output": lttng_session_descriptor_create()
39 * * local: lttng_session_descriptor_local_create()
40 * * network: lttng_session_descriptor_network_create()
42 * Snapshot session creation functions and output modes:
43 * * "no output": lttng_session_descriptor_snapshot_create()
44 * * local: lttng_session_descriptor_snapshot_local_create()
45 * * network: lttng_session_descriptor_snapshot_network_create()
47 * Live session creation functions and output modes:
48 * * "no output": lttng_session_descriptor_live_create()
49 * * network: lttng_session_descriptor_live_network_create()
51 * Local output functions accept a 'path' parameter that must be an absolute
52 * path to which the user has write access. When a local output is automatically
53 * generated, it adopts the form:
54 * $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME
56 * Where CREATION_TIME is time of the creation of the session on the session
57 * daemon in the form "yyyymmdd-hhmmss".
59 * Network output locations can also be auto-generated by leaving the
60 * 'control_url' and 'data_url' output parameters unspecified. In such cases,
61 * the session daemon will create a default output targeting a relay daemon
62 * at net://127.0.0.1, using the default 'control' and 'data' ports.
64 * The format of the 'control_url' and 'data_url' parameters is:
65 * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
67 * NETPROTO: Network protocol, amongst:
68 * * net: TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
69 * are defined at build time of the lttng toolchain.
70 * * net6: TCP over IPv6: same default ports as the 'net' protocol.
71 * * tcp: Same as the 'net' protocol.
72 * * tcp6: Same as the 'net6' protocol.
74 * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed
75 * in brackets; see RFC 2732).
77 * CTRLPORT: Control port.
79 * DATAPORT: Data port.
81 * TRACEPATH: Path of trace files on the remote file system. This path is
82 * relative to the base output directory set on the relay daemon
85 * The 'data_url' parameter is optional:
86 * * This parameter is meaningless for local tracing.
87 * * If 'control_url' is specified and a network protocol is used, the
88 * default data port, and the 'control_url' host will be used.
91 enum lttng_session_descriptor_status
{
92 /* Invalid session descriptor parameter. */
93 LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID
= -1,
94 LTTNG_SESSION_DESCRIPTOR_STATUS_OK
= 0,
95 /* Session descriptor parameter is unset. */
96 LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET
= 1,
100 * Create a session descriptor in no-output mode.
102 * The 'name' parameter can be left NULL to auto-generate a session name.
104 * Returns an lttng_session_descriptor instance on success, NULL on error.
106 extern struct lttng_session_descriptor
*
107 lttng_session_descriptor_create(const char *name
);
110 * Create a session descriptor with a local output destination.
112 * The 'name' parameter can be left NULL to auto-generate a session name.
114 * The 'path' must either be an absolute path or it can be left NULL to
115 * use the default local output destination.
117 * Returns an lttng_session_descriptor instance on success, NULL on error.
119 extern struct lttng_session_descriptor
*
120 lttng_session_descriptor_local_create(const char *name
, const char *path
);
123 * Create a session descriptor with a remote output destination.
125 * The 'name' parameter can be left NULL to auto-generate a session name.
127 * The 'control_url' and 'data_url' must conform to the URL format
128 * described above or can be left NULL to use the default network output.
130 * Returns an lttng_session_descriptor instance on success, NULL on error.
132 extern struct lttng_session_descriptor
*
133 lttng_session_descriptor_network_create(const char *name
,
134 const char *control_url
, const char *data_url
);
137 * Create a snapshot session descriptor without a default output.
139 * The 'name' parameter can be left NULL to auto-generate a session name.
141 * Returns an lttng_session_descriptor instance on success, NULL on error.
143 extern struct lttng_session_descriptor
*
144 lttng_session_descriptor_snapshot_create(const char *name
);
147 * Create a snapshot session descriptor with a local output destination.
149 * The 'name' parameter can be left NULL to auto-generate a session name.
151 * The 'path' must either be an absolute path or it can be left NULL to
152 * use the default local output destination as the default snapshot output.
154 * Returns an lttng_session_descriptor instance on success, NULL on error.
156 extern struct lttng_session_descriptor
*
157 lttng_session_descriptor_snapshot_local_create(const char *name
,
161 * Create a snapshot session descriptor with a remote output destination.
163 * The 'name' parameter can be left NULL to auto-generate a session name.
165 * The 'control_url' and 'data_url' must conform to the URL format
166 * described above or can be left NULL to use the default network output as
167 * the default snapshot output.
169 * Returns an lttng_session_descriptor instance on success, NULL on error.
171 extern struct lttng_session_descriptor
*
172 lttng_session_descriptor_snapshot_network_create(const char *name
,
173 const char *control_url
, const char *data_url
);
176 * Create a live session descriptor without an output.
178 * The 'name' parameter can be left NULL to auto-generate a session name.
180 * The 'live_timer_interval_us' parameter is the live timer's period, specified
183 * This parameter can't be 0. There is no default value defined for a live
186 * Returns an lttng_session_descriptor instance on success, NULL on error.
188 extern struct lttng_session_descriptor
*
189 lttng_session_descriptor_live_create(
190 const char *name
, unsigned long long live_timer_interval_us
);
193 * Create a live session descriptor with a remote output destination.
195 * The 'name' parameter can be left NULL to auto-generate a session name.
197 * The 'control_url' and 'data_url' must conform to the URL format
198 * described above or can be left NULL to use the default network output.
200 * The 'live_timer_interval_us' parameter is the live timer's period, specified
203 * This parameter can't be 0. There is no default value defined for a live
206 * Returns an lttng_session_descriptor instance on success, NULL on error.
208 extern struct lttng_session_descriptor
*
209 lttng_session_descriptor_live_network_create(
211 const char *control_url
, const char *data_url
,
212 unsigned long long live_timer_interval_us
);
215 * Get a session descriptor's session name.
217 * The 'name' parameter is used as an output parameter and will point to
218 * the session descriptor's session name on success
219 * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified
220 * for other return codes. The pointer returned through 'name' is only
221 * guaranteed to remain valid until the next method call on the session
224 * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success,
225 * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are
226 * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's
227 * name parameter is unset.
229 extern enum lttng_session_descriptor_status
230 lttng_session_descriptor_get_session_name(
231 const struct lttng_session_descriptor
*descriptor
,
235 * Destroy a local lttng_session object.
237 * This does not destroy the session on the session daemon; it releases
238 * the resources allocated by the descriptor object.
240 extern void lttng_session_descriptor_destroy(
241 struct lttng_session_descriptor
*descriptor
);
247 #endif /* LTTNG_SESSION_DESCRIPTOR_H */