session-descriptor: fix comment typos in session-descriptor.h
[lttng-tools.git] / include / lttng / session-descriptor.h
1 /*
2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 *
4 * SPDX-License-Identifier: LGPL-2.1-only
5 *
6 */
7
8 #ifndef LTTNG_SESSION_DESCRIPTOR_H
9 #define LTTNG_SESSION_DESCRIPTOR_H
10
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14
15 struct lttng_session_descriptor;
16
17 /*
18 * Session descriptor API.
19 *
20 * A session descriptor is an object describing the immutable configuration
21 * options of an LTTng tracing session.
22 *
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,
25 * snapshot, and live.
26 *
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.
32 *
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
35 * type.
36 *
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()
41 *
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()
46 *
47 * Live session creation functions and output modes:
48 * * "no output": lttng_session_descriptor_live_create()
49 * * network: lttng_session_descriptor_live_network_create()
50 *
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
55 *
56 * Where CREATION_TIME is time of the creation of the session on the session
57 * daemon in the form "yyyymmdd-hhmmss".
58 *
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.
63 *
64 * The format of the 'control_url' and 'data_url' parameters is:
65 * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH]
66 *
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.
73 *
74 * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed
75 * in brackets; see RFC 2732).
76 *
77 * CTRLPORT: Control port.
78 *
79 * DATAPORT: Data port.
80 *
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
83 * end.
84 *
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.
89 */
90
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,
97 };
98
99 /*
100 * Create a session descriptor in no-output mode.
101 *
102 * The 'name' parameter can be left NULL to auto-generate a session name.
103 *
104 * Returns an lttng_session_descriptor instance on success, NULL on error.
105 */
106 extern struct lttng_session_descriptor *
107 lttng_session_descriptor_create(const char *name);
108
109 /*
110 * Create a session descriptor with a local output destination.
111 *
112 * The 'name' parameter can be left NULL to auto-generate a session name.
113 *
114 * The 'path' must either be an absolute path or it can be left NULL to
115 * use the default local output destination.
116 *
117 * Returns an lttng_session_descriptor instance on success, NULL on error.
118 */
119 extern struct lttng_session_descriptor *
120 lttng_session_descriptor_local_create(const char *name, const char *path);
121
122 /*
123 * Create a session descriptor with a remote output destination.
124 *
125 * The 'name' parameter can be left NULL to auto-generate a session name.
126 *
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.
129 *
130 * Returns an lttng_session_descriptor instance on success, NULL on error.
131 */
132 extern struct lttng_session_descriptor *
133 lttng_session_descriptor_network_create(const char *name,
134 const char *control_url, const char *data_url);
135
136 /*
137 * Create a snapshot session descriptor without a default output.
138 *
139 * The 'name' parameter can be left NULL to auto-generate a session name.
140 *
141 * Returns an lttng_session_descriptor instance on success, NULL on error.
142 */
143 extern struct lttng_session_descriptor *
144 lttng_session_descriptor_snapshot_create(const char *name);
145
146 /*
147 * Create a snapshot session descriptor with a local output destination.
148 *
149 * The 'name' parameter can be left NULL to auto-generate a session name.
150 *
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.
153 *
154 * Returns an lttng_session_descriptor instance on success, NULL on error.
155 */
156 extern struct lttng_session_descriptor *
157 lttng_session_descriptor_snapshot_local_create(const char *name,
158 const char *path);
159
160 /*
161 * Create a snapshot session descriptor with a remote output destination.
162 *
163 * The 'name' parameter can be left NULL to auto-generate a session name.
164 *
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.
168 *
169 * Returns an lttng_session_descriptor instance on success, NULL on error.
170 */
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);
174
175 /*
176 * Create a live session descriptor without an output.
177 *
178 * The 'name' parameter can be left NULL to auto-generate a session name.
179 *
180 * The 'live_timer_interval_us' parameter is the live timer's period, specified
181 * in microseconds.
182 *
183 * This parameter can't be 0. There is no default value defined for a live
184 * timer's period.
185 *
186 * Returns an lttng_session_descriptor instance on success, NULL on error.
187 */
188 extern struct lttng_session_descriptor *
189 lttng_session_descriptor_live_create(
190 const char *name, unsigned long long live_timer_interval_us);
191
192 /*
193 * Create a live session descriptor with a remote output destination.
194 *
195 * The 'name' parameter can be left NULL to auto-generate a session name.
196 *
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.
199 *
200 * The 'live_timer_interval_us' parameter is the live timer's period, specified
201 * in microseconds.
202 *
203 * This parameter can't be 0. There is no default value defined for a live
204 * timer's period.
205 *
206 * Returns an lttng_session_descriptor instance on success, NULL on error.
207 */
208 extern struct lttng_session_descriptor *
209 lttng_session_descriptor_live_network_create(
210 const char *name,
211 const char *control_url, const char *data_url,
212 unsigned long long live_timer_interval_us);
213
214 /*
215 * Get a session descriptor's session name.
216 *
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
222 * descriptor.
223 *
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.
228 */
229 extern enum lttng_session_descriptor_status
230 lttng_session_descriptor_get_session_name(
231 const struct lttng_session_descriptor *descriptor,
232 const char **name);
233
234 /*
235 * Destroy a local lttng_session object.
236 *
237 * This does not destroy the session on the session daemon; it releases
238 * the resources allocated by the descriptor object.
239 */
240 extern void lttng_session_descriptor_destroy(
241 struct lttng_session_descriptor *descriptor);
242
243 #ifdef __cplusplus
244 }
245 #endif
246
247 #endif /* LTTNG_SESSION_DESCRIPTOR_H */
This page took 0.04789 seconds and 4 git commands to generate.