Commit | Line | Data |
---|---|---|
1239a312 DG |
1 | /* |
2 | * Copyright (C) 2014 - David Goulet <dgoulet@efficios.com> | |
3e3665b8 | 3 | * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com> |
1239a312 DG |
4 | * |
5 | * This library is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU Lesser General Public License, version 2.1 only, | |
7 | * as published by the Free Software Foundation. | |
8 | * | |
9 | * This library is distributed in the hope that it will be useful, but WITHOUT | |
10 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
11 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License | |
12 | * for more details. | |
13 | * | |
14 | * You should have received a copy of the GNU Lesser General Public License | |
15 | * along with this library; if not, write to the Free Software Foundation, | |
16 | * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
17 | */ | |
18 | ||
19 | #ifndef LTTNG_SESSION_H | |
20 | #define LTTNG_SESSION_H | |
21 | ||
22 | #ifdef __cplusplus | |
23 | extern "C" { | |
24 | #endif | |
25 | ||
55c9e7ca JR |
26 | #include <lttng/constant.h> |
27 | ||
41ef8f63 JR |
28 | enum lttng_tracker_type { |
29 | LTTNG_TRACKER_PID = 0, | |
30 | LTTNG_TRACKER_VPID = 1, | |
31 | LTTNG_TRACKER_UID = 2, | |
32 | LTTNG_TRACKER_GID = 3, | |
33 | LTTNG_TRACKER_VUID = 4, | |
34 | LTTNG_TRACKER_VGID = 5, | |
35 | }; | |
36 | ||
37 | enum lttng_tracker_id_type { | |
38 | LTTNG_ID_UNKNOWN = -1, | |
39 | LTTNG_ID_ALL = 0, | |
40 | LTTNG_ID_VALUE = 1, | |
41 | LTTNG_ID_STRING = 2, | |
42 | }; | |
43 | ||
44 | struct lttng_tracker_id { | |
45 | enum lttng_tracker_id_type type; | |
46 | int value; | |
47 | char *string; | |
48 | }; | |
49 | ||
55c9e7ca | 50 | struct lttng_handle; |
b178f53e | 51 | struct lttng_session_descriptor; |
3e3665b8 | 52 | struct lttng_destruction_handle; |
b178f53e | 53 | |
1239a312 DG |
54 | /* |
55 | * Basic session information. | |
56 | * | |
57 | * The "enabled" field is only used when listing the sessions which indicate if | |
58 | * it's started or not. | |
59 | * | |
60 | * The structures should be initialized to zero before use. | |
61 | */ | |
e9af56b3 | 62 | #define LTTNG_SESSION_PADDING1 8 |
1239a312 | 63 | struct lttng_session { |
36d2e35d | 64 | char name[LTTNG_NAME_MAX]; |
beede00c JG |
65 | /* |
66 | * Human-readable representation of the trace's destination. | |
67 | * In the case of a local tracing session, a path is provided: | |
68 | * /path/to/the/output | |
69 | * | |
70 | * In the case of a remote (network) tracing session, the string has | |
71 | * the following format: | |
72 | * net://hostname/path:ctrl_port [data: data_port] | |
73 | */ | |
1239a312 DG |
74 | char path[PATH_MAX]; |
75 | uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */ | |
76 | uint32_t snapshot_mode; | |
77 | unsigned int live_timer_interval; /* usec */ | |
78 | ||
e9af56b3 JG |
79 | /* |
80 | * End of public attributes. | |
81 | * The remaining fields are used to deal with ABI management concerns. | |
82 | */ | |
83 | ||
84 | /* | |
85 | * 32-bit architectures are already naturally aligned on 4 bytes after | |
86 | * 'live_timer_interval'. However, the offset does not result in a | |
87 | * natural alignment on 64-bit architectures. Adding 4 bytes of | |
88 | * padding here results in an aligned offset after 'alignement_padding' | |
89 | * for both bitnesses. | |
90 | * | |
91 | * This was added since not all compilers appear to align unions in the | |
92 | * same way. Some (e.g. MSVC) do not seem to impose an alignement | |
93 | * constraint while others (e.g. gcc, clang, icc) seem to align it to | |
94 | * ensure 'ptr' is naturally aligned. | |
95 | */ | |
96 | char alignment_padding[4]; | |
b178f53e | 97 | union { |
e9af56b3 JG |
98 | /* |
99 | * Ensure the 'extended' union has the same size for both | |
100 | * 32-bit and 64-bit builds. | |
101 | */ | |
b178f53e JG |
102 | char padding[LTTNG_SESSION_PADDING1]; |
103 | void *ptr; | |
104 | } extended; | |
1239a312 DG |
105 | }; |
106 | ||
b178f53e JG |
107 | /* |
108 | * Create a session on the session daemon from a session descriptor. | |
109 | * | |
110 | * See the session descriptor API description in session-descriptor.h | |
111 | * | |
112 | * Note that unspecified session descriptor parameters, such as a session's | |
113 | * name, are updated in the session descriptor if the creation of the session | |
114 | * succeeds. This allows users to query the session's auto-generated name | |
115 | * after its creation. Note that other attributes can be queried using the | |
116 | * session listing API. | |
117 | * | |
118 | * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other | |
119 | * return codes. | |
120 | */ | |
121 | extern enum lttng_error_code lttng_create_session_ext( | |
122 | struct lttng_session_descriptor *session_descriptor); | |
123 | ||
1239a312 DG |
124 | /* |
125 | * Create a tracing session using a name and an optional URL. | |
126 | * | |
127 | * If _url_ is NULL, no consumer is created for the session. The name can't be | |
128 | * NULL here. | |
129 | * | |
130 | * Return 0 on success else a negative LTTng error code. | |
131 | */ | |
132 | extern int lttng_create_session(const char *name, const char *url); | |
133 | ||
134 | /* | |
135 | * Create a tracing session that will exclusively be used for snapshot meaning | |
136 | * the session will be in no output mode and every channel enabled for that | |
137 | * session will be set in overwrite mode and in mmap output since splice is not | |
138 | * supported. | |
139 | * | |
140 | * Name can't be NULL. If an url is given, it will be used to create a default | |
141 | * snapshot output using it as a destination. If NULL, no output will be | |
142 | * defined and an add-output call will be needed. | |
143 | * | |
144 | * Return 0 on success else a negative LTTng error code. | |
145 | */ | |
146 | extern int lttng_create_session_snapshot(const char *name, | |
147 | const char *snapshot_url); | |
148 | ||
149 | /* | |
150 | * Create a session exclusively used for live reading. | |
151 | * | |
152 | * In this mode, the switch-timer parameter is forced for each UST channel, a | |
153 | * live-switch-timer is enabled for kernel channels, manually setting | |
154 | * switch-timer is forbidden. Synchronization beacons are sent to the relayd, | |
155 | * indexes are sent and metadata is checked for each packet. | |
156 | * | |
157 | * Name can't be NULL. If no URL is given, the default is to send the data to | |
1aacaae2 | 158 | * net://127.0.0.1. The timer_interval is in usec. |
1239a312 DG |
159 | * |
160 | * Return 0 on success else a negative LTTng error code. | |
161 | */ | |
162 | extern int lttng_create_session_live(const char *name, const char *url, | |
163 | unsigned int timer_interval); | |
164 | ||
165 | /* | |
166 | * Destroy a tracing session. | |
167 | * | |
168 | * The session will not be usable, tracing will be stopped thus buffers will be | |
169 | * flushed. | |
170 | * | |
e20ee7c2 JD |
171 | * This call will wait for data availability for each domain of the session, |
172 | * which can take an arbitrary amount of time. However, when returning the | |
173 | * tracing data is guaranteed to be ready to be read and analyzed. | |
174 | * | |
175 | * lttng_destroy_session_no_wait() may be used if such a guarantee is not | |
176 | * needed. | |
177 | * | |
1239a312 DG |
178 | * The name can't be NULL here. |
179 | * | |
780d4bb8 | 180 | * Return 0 on success else a negative LTTng error code. |
1239a312 DG |
181 | */ |
182 | extern int lttng_destroy_session(const char *name); | |
183 | ||
3e3665b8 JG |
184 | /* |
185 | * Destroy a tracing session. | |
186 | * | |
187 | * Performs the same function as lttng_destroy_session(), but provides | |
188 | * an lttng_destruction_handle which can be used to wait for the completion | |
189 | * of the session's destruction. The lttng_destroy_handle can also be used | |
190 | * obtain the status and archive location of any implicit session | |
83ed9e90 | 191 | * rotation that may have occurred during the session's destruction. |
3e3665b8 JG |
192 | * |
193 | * Returns LTTNG_OK on success. The returned handle is owned by the caller | |
194 | * and must be free'd using lttng_destruction_handle_destroy(). | |
195 | */ | |
196 | extern enum lttng_error_code lttng_destroy_session_ext(const char *session_name, | |
197 | struct lttng_destruction_handle **handle); | |
198 | ||
e20ee7c2 JD |
199 | /* |
200 | * Behaves exactly like lttng_destroy_session but does not wait for data | |
201 | * availability. | |
202 | */ | |
203 | extern int lttng_destroy_session_no_wait(const char *name); | |
204 | ||
1239a312 DG |
205 | /* |
206 | * List all the tracing sessions. | |
207 | * | |
b178f53e JG |
208 | * Return the number of entries of the "lttng_session" array. The caller |
209 | * must free the returned sessions array directly using free(). | |
210 | * | |
211 | * On error, a negative LTTng error code is returned. | |
1239a312 DG |
212 | */ |
213 | extern int lttng_list_sessions(struct lttng_session **sessions); | |
214 | ||
b178f53e JG |
215 | /* |
216 | * Get the creation time of an lttng_session object on the session daemon. | |
217 | * | |
218 | * This function must only be used with lttng_session objects returned | |
219 | * by lttng_list_sessions() or lttng_session_create(). | |
220 | * | |
221 | * The creation time returned is a UNIX timestamp; the number of seconds since | |
222 | * Epoch (1970-01-01 00:00:00 +0000 (UTC)). | |
223 | * | |
224 | * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other | |
225 | * return codes. | |
226 | */ | |
227 | extern enum lttng_error_code lttng_session_get_creation_time( | |
228 | const struct lttng_session *session, uint64_t *creation_time); | |
229 | ||
d7ba1388 MD |
230 | /* |
231 | * Set the shared memory path for a session. | |
232 | * | |
233 | * Sets the (optional) file system path where shared memory buffers will | |
234 | * be created for the session. This is useful for buffer extraction on | |
235 | * crash, when used with filesystems like pramfs. | |
236 | * | |
237 | * Return 0 on success else a negative LTTng error code. | |
238 | */ | |
239 | extern int lttng_set_session_shm_path(const char *session_name, | |
240 | const char *shm_path); | |
241 | ||
55c9e7ca JR |
242 | /* |
243 | * Add ID to session tracker. | |
244 | * | |
245 | * tracker_type is the type of tracker. | |
246 | * id the id to track. | |
247 | * | |
248 | * Return 0 on success else a negative LTTng error code. | |
249 | */ | |
250 | extern int lttng_track_id(struct lttng_handle *handle, | |
251 | enum lttng_tracker_type tracker_type, | |
252 | const struct lttng_tracker_id *id); | |
253 | ||
254 | /* | |
255 | * Remove ID from session tracker. | |
256 | * | |
257 | * tracker_type is the type of tracker. | |
258 | * id the id to untrack. | |
259 | * | |
260 | * Return 0 on success else a negative LTTng error code. | |
261 | */ | |
262 | extern int lttng_untrack_id(struct lttng_handle *handle, | |
263 | enum lttng_tracker_type tracker_type, | |
264 | const struct lttng_tracker_id *id); | |
265 | ||
266 | /* | |
267 | * List IDs in the tracker. | |
268 | * | |
269 | * tracker_type is the type of tracker. | |
270 | * ids is set to an allocated array of IDs currently tracked. On | |
271 | * success, ids and the strings it contains must be freed by the | |
272 | * caller. | |
273 | * nr_ids is set to the number of entries contained by the ids array. | |
274 | * | |
275 | * Returns 0 on success, else a negative LTTng error code. | |
276 | */ | |
277 | extern int lttng_list_tracker_ids(struct lttng_handle *handle, | |
278 | enum lttng_tracker_type tracker_type, | |
279 | struct lttng_tracker_id **ids, | |
280 | size_t *nr_ids); | |
281 | ||
ccf10263 MD |
282 | /* |
283 | * Add PID to session tracker. | |
284 | * | |
285 | * A pid argument >= 0 adds the PID to the session tracker. | |
286 | * A pid argument of -1 means "track all PIDs". | |
287 | * | |
288 | * Return 0 on success else a negative LTTng error code. | |
289 | */ | |
290 | extern int lttng_track_pid(struct lttng_handle *handle, int pid); | |
291 | ||
292 | /* | |
293 | * Remove PID from session tracker. | |
294 | * | |
295 | * A pid argument >= 0 removes the PID from the session tracker. | |
296 | * A pid argument of -1 means "untrack all PIDs". | |
297 | * | |
298 | * Return 0 on success else a negative LTTng error code. | |
299 | */ | |
300 | extern int lttng_untrack_pid(struct lttng_handle *handle, int pid); | |
301 | ||
a5dfbb9d MD |
302 | /* |
303 | * List PIDs in the tracker. | |
304 | * | |
36dc4128 JG |
305 | * enabled is set to whether the PID tracker is enabled. |
306 | * pids is set to an allocated array of PIDs currently tracked. On | |
307 | * success, pids must be freed by the caller. | |
308 | * nr_pids is set to the number of entries contained by the pids array. | |
a5dfbb9d MD |
309 | * |
310 | * Returns 0 on success, else a negative LTTng error code. | |
311 | */ | |
312 | extern int lttng_list_tracker_pids(struct lttng_handle *handle, | |
313 | int *enabled, int32_t **pids, size_t *nr_pids); | |
314 | ||
1239a312 DG |
315 | #ifdef __cplusplus |
316 | } | |
317 | #endif | |
318 | ||
319 | #endif /* LTTNG_SESSION_H */ |