Commit | Line | Data |
---|---|---|
b178f53e | 1 | /* |
ab5be9fa | 2 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
b178f53e | 3 | * |
ab5be9fa | 4 | * SPDX-License-Identifier: LGPL-2.1-only |
b178f53e | 5 | * |
b178f53e JG |
6 | */ |
7 | ||
8 | #ifndef LTTNG_SESSION_DESCRIPTOR_H | |
9 | #define LTTNG_SESSION_DESCRIPTOR_H | |
10 | ||
4bd69c5f SM |
11 | #include <lttng/lttng-export.h> |
12 | ||
b178f53e JG |
13 | #ifdef __cplusplus |
14 | extern "C" { | |
15 | #endif | |
16 | ||
17 | struct lttng_session_descriptor; | |
b52d6eac | 18 | struct lttng_trace_format_descriptor; |
b178f53e JG |
19 | |
20 | /* | |
21 | * Session descriptor API. | |
22 | * | |
23 | * A session descriptor is an object describing the immutable configuration | |
24 | * options of an LTTng tracing session. | |
25 | * | |
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, | |
28 | * snapshot, and live. | |
29 | * | |
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. | |
35 | * | |
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 | |
38 | * type. | |
39 | * | |
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() | |
44 | * | |
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() | |
49 | * | |
50 | * Live session creation functions and output modes: | |
51 | * * "no output": lttng_session_descriptor_live_create() | |
52 | * * network: lttng_session_descriptor_live_network_create() | |
53 | * | |
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 | |
58 | * | |
59 | * Where CREATION_TIME is time of the creation of the session on the session | |
60 | * daemon in the form "yyyymmdd-hhmmss". | |
61 | * | |
ca077825 | 62 | * Network output locations can also be auto-generated by leaving the |
b178f53e JG |
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. | |
66 | * | |
ca077825 | 67 | * The format of the 'control_url' and 'data_url' parameters is: |
b178f53e JG |
68 | * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH] |
69 | * | |
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. | |
76 | * | |
77 | * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed | |
78 | * in brackets; see RFC 2732). | |
79 | * | |
80 | * CTRLPORT: Control port. | |
81 | * | |
82 | * DATAPORT: Data port. | |
83 | * | |
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 | |
86 | * end. | |
87 | * | |
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. | |
92 | */ | |
93 | ||
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, | |
100 | }; | |
101 | ||
102 | /* | |
103 | * Create a session descriptor in no-output mode. | |
104 | * | |
105 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
106 | * | |
107 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
108 | */ | |
4bd69c5f | 109 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
110 | lttng_session_descriptor_create(const char *name); |
111 | ||
112 | /* | |
113 | * Create a session descriptor with a local output destination. | |
114 | * | |
115 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
116 | * | |
117 | * The 'path' must either be an absolute path or it can be left NULL to | |
ca077825 | 118 | * use the default local output destination. |
b178f53e JG |
119 | * |
120 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
121 | */ | |
4bd69c5f | 122 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
123 | lttng_session_descriptor_local_create(const char *name, const char *path); |
124 | ||
125 | /* | |
126 | * Create a session descriptor with a remote output destination. | |
127 | * | |
128 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
129 | * | |
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. | |
132 | * | |
133 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
134 | */ | |
4bd69c5f | 135 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
136 | lttng_session_descriptor_network_create(const char *name, |
137 | const char *control_url, const char *data_url); | |
138 | ||
139 | /* | |
140 | * Create a snapshot session descriptor without a default output. | |
141 | * | |
142 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
143 | * | |
144 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
145 | */ | |
4bd69c5f | 146 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
147 | lttng_session_descriptor_snapshot_create(const char *name); |
148 | ||
149 | /* | |
150 | * Create a snapshot session descriptor with a local output destination. | |
151 | * | |
152 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
153 | * | |
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. | |
156 | * | |
157 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
158 | */ | |
4bd69c5f | 159 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
160 | lttng_session_descriptor_snapshot_local_create(const char *name, |
161 | const char *path); | |
162 | ||
163 | /* | |
164 | * Create a snapshot session descriptor with a remote output destination. | |
165 | * | |
166 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
167 | * | |
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. | |
171 | * | |
172 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
173 | */ | |
4bd69c5f | 174 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
175 | lttng_session_descriptor_snapshot_network_create(const char *name, |
176 | const char *control_url, const char *data_url); | |
177 | ||
178 | /* | |
179 | * Create a live session descriptor without an output. | |
180 | * | |
181 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
182 | * | |
183 | * The 'live_timer_interval_us' parameter is the live timer's period, specified | |
184 | * in microseconds. | |
185 | * | |
186 | * This parameter can't be 0. There is no default value defined for a live | |
187 | * timer's period. | |
188 | * | |
189 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
190 | */ | |
4bd69c5f | 191 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
192 | lttng_session_descriptor_live_create( |
193 | const char *name, unsigned long long live_timer_interval_us); | |
194 | ||
195 | /* | |
196 | * Create a live session descriptor with a remote output destination. | |
197 | * | |
198 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
199 | * | |
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. | |
202 | * | |
203 | * The 'live_timer_interval_us' parameter is the live timer's period, specified | |
204 | * in microseconds. | |
205 | * | |
206 | * This parameter can't be 0. There is no default value defined for a live | |
207 | * timer's period. | |
208 | * | |
209 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
210 | */ | |
4bd69c5f | 211 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
b178f53e JG |
212 | lttng_session_descriptor_live_network_create( |
213 | const char *name, | |
214 | const char *control_url, const char *data_url, | |
215 | unsigned long long live_timer_interval_us); | |
216 | ||
217 | /* | |
218 | * Get a session descriptor's session name. | |
219 | * | |
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 | |
225 | * descriptor. | |
226 | * | |
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. | |
231 | */ | |
4bd69c5f | 232 | LTTNG_EXPORT extern enum lttng_session_descriptor_status |
b178f53e JG |
233 | lttng_session_descriptor_get_session_name( |
234 | const struct lttng_session_descriptor *descriptor, | |
235 | const char **name); | |
236 | ||
49bb5ef3 JR |
237 | /* |
238 | * Get a session descriptor's trace format descriptor. | |
239 | * | |
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 | |
245 | * descriptor. | |
246 | * | |
247 | * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success, | |
248 | * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'trace_format_descriptor' are | |
249 | * NULL. | |
250 | */ | |
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); | |
255 | ||
256 | /* | |
257 | * Set a session descriptor's trace format descriptor. | |
258 | * | |
259 | * The trace format descriptor is copied internally. | |
260 | * | |
261 | * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success, | |
262 | * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'trace_format_descriptor' are | |
263 | * NULL. | |
264 | */ | |
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); | |
269 | ||
b178f53e JG |
270 | /* |
271 | * Destroy a local lttng_session object. | |
272 | * | |
273 | * This does not destroy the session on the session daemon; it releases | |
274 | * the resources allocated by the descriptor object. | |
275 | */ | |
4bd69c5f | 276 | LTTNG_EXPORT extern void lttng_session_descriptor_destroy( |
b178f53e JG |
277 | struct lttng_session_descriptor *descriptor); |
278 | ||
279 | #ifdef __cplusplus | |
280 | } | |
281 | #endif | |
282 | ||
283 | #endif /* LTTNG_SESSION_DESCRIPTOR_H */ |