Commit | Line | Data |
---|---|---|
1239a312 DG |
1 | /* |
2 | * Copyright (C) 2014 - David Goulet <dgoulet@efficios.com> | |
3 | * | |
4 | * This library is free software; you can redistribute it and/or modify it | |
5 | * under the terms of the GNU Lesser General Public License, version 2.1 only, | |
6 | * as published by the Free Software Foundation. | |
7 | * | |
8 | * This library is distributed in the hope that it will be useful, but WITHOUT | |
9 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
10 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License | |
11 | * for more details. | |
12 | * | |
13 | * You should have received a copy of the GNU Lesser General Public License | |
14 | * along with this library; if not, write to the Free Software Foundation, | |
15 | * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
16 | */ | |
17 | ||
18 | #ifndef LTTNG_SESSION_H | |
19 | #define LTTNG_SESSION_H | |
20 | ||
21 | #ifdef __cplusplus | |
22 | extern "C" { | |
23 | #endif | |
24 | ||
ee9c58e0 MD |
25 | #include <lttng/constant.h> |
26 | ||
27 | enum lttng_tracker_type { | |
28 | LTTNG_TRACKER_PID = 0, | |
29 | LTTNG_TRACKER_VPID, | |
30 | LTTNG_TRACKER_UID, | |
31 | LTTNG_TRACKER_GID, | |
32 | LTTNG_TRACKER_VUID, | |
33 | LTTNG_TRACKER_VGID, | |
34 | }; | |
35 | ||
36 | enum lttng_tracker_id_type { | |
37 | LTTNG_ID_UNKNOWN = -1, | |
38 | ||
39 | LTTNG_ID_ALL, | |
40 | LTTNG_ID_VALUE, | |
41 | LTTNG_ID_STRING, | |
42 | }; | |
43 | ||
44 | struct lttng_tracker_id { | |
45 | enum lttng_tracker_id_type type; | |
46 | int value; | |
47 | char *string; | |
48 | }; | |
49 | ||
50 | struct lttng_handle; | |
51 | ||
1239a312 DG |
52 | /* |
53 | * Basic session information. | |
54 | * | |
55 | * The "enabled" field is only used when listing the sessions which indicate if | |
56 | * it's started or not. | |
57 | * | |
58 | * The structures should be initialized to zero before use. | |
59 | */ | |
60 | #define LTTNG_SESSION_PADDING1 12 | |
61 | struct lttng_session { | |
36d2e35d | 62 | char name[LTTNG_NAME_MAX]; |
1239a312 DG |
63 | /* The path where traces are written */ |
64 | char path[PATH_MAX]; | |
65 | uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */ | |
66 | uint32_t snapshot_mode; | |
67 | unsigned int live_timer_interval; /* usec */ | |
68 | ||
69 | char padding[LTTNG_SESSION_PADDING1]; | |
70 | }; | |
71 | ||
72 | /* | |
73 | * Create a tracing session using a name and an optional URL. | |
74 | * | |
75 | * If _url_ is NULL, no consumer is created for the session. The name can't be | |
76 | * NULL here. | |
77 | * | |
78 | * Return 0 on success else a negative LTTng error code. | |
79 | */ | |
80 | extern int lttng_create_session(const char *name, const char *url); | |
81 | ||
82 | /* | |
83 | * Create a tracing session that will exclusively be used for snapshot meaning | |
84 | * the session will be in no output mode and every channel enabled for that | |
85 | * session will be set in overwrite mode and in mmap output since splice is not | |
86 | * supported. | |
87 | * | |
88 | * Name can't be NULL. If an url is given, it will be used to create a default | |
89 | * snapshot output using it as a destination. If NULL, no output will be | |
90 | * defined and an add-output call will be needed. | |
91 | * | |
92 | * Return 0 on success else a negative LTTng error code. | |
93 | */ | |
94 | extern int lttng_create_session_snapshot(const char *name, | |
95 | const char *snapshot_url); | |
96 | ||
97 | /* | |
98 | * Create a session exclusively used for live reading. | |
99 | * | |
100 | * In this mode, the switch-timer parameter is forced for each UST channel, a | |
101 | * live-switch-timer is enabled for kernel channels, manually setting | |
102 | * switch-timer is forbidden. Synchronization beacons are sent to the relayd, | |
103 | * indexes are sent and metadata is checked for each packet. | |
104 | * | |
105 | * Name can't be NULL. If no URL is given, the default is to send the data to | |
106 | * net://127.0.0.1. The timer_interval is in usec and by default set to 1000000 | |
107 | * (1 second). | |
108 | * | |
109 | * Return 0 on success else a negative LTTng error code. | |
110 | */ | |
111 | extern int lttng_create_session_live(const char *name, const char *url, | |
112 | unsigned int timer_interval); | |
113 | ||
114 | /* | |
115 | * Destroy a tracing session. | |
116 | * | |
117 | * The session will not be usable, tracing will be stopped thus buffers will be | |
118 | * flushed. | |
119 | * | |
e20ee7c2 JD |
120 | * This call will wait for data availability for each domain of the session, |
121 | * which can take an arbitrary amount of time. However, when returning the | |
122 | * tracing data is guaranteed to be ready to be read and analyzed. | |
123 | * | |
124 | * lttng_destroy_session_no_wait() may be used if such a guarantee is not | |
125 | * needed. | |
126 | * | |
1239a312 DG |
127 | * The name can't be NULL here. |
128 | * | |
129 | * Return 0 on success else a negative LTTng error code. | |
130 | */ | |
131 | extern int lttng_destroy_session(const char *name); | |
132 | ||
e20ee7c2 JD |
133 | /* |
134 | * Behaves exactly like lttng_destroy_session but does not wait for data | |
135 | * availability. | |
136 | */ | |
137 | extern int lttng_destroy_session_no_wait(const char *name); | |
138 | ||
1239a312 DG |
139 | /* |
140 | * List all the tracing sessions. | |
141 | * | |
142 | * Return the size (number of entries) of the "lttng_session" array. Caller | |
143 | * must free sessions. On error, a negative LTTng error code is returned. | |
144 | */ | |
145 | extern int lttng_list_sessions(struct lttng_session **sessions); | |
146 | ||
d7ba1388 MD |
147 | /* |
148 | * Set the shared memory path for a session. | |
149 | * | |
150 | * Sets the (optional) file system path where shared memory buffers will | |
151 | * be created for the session. This is useful for buffer extraction on | |
152 | * crash, when used with filesystems like pramfs. | |
153 | * | |
154 | * Return 0 on success else a negative LTTng error code. | |
155 | */ | |
156 | extern int lttng_set_session_shm_path(const char *session_name, | |
157 | const char *shm_path); | |
158 | ||
ee9c58e0 MD |
159 | /* |
160 | * Add ID to session tracker. | |
161 | * | |
162 | * tracker_type is the type of tracker. | |
163 | * An id argument >= 0 adds the ID to the session tracker. | |
164 | * An id argument of -1 means "track all IDs". | |
165 | * | |
166 | * Return 0 on success else a negative LTTng error code. | |
167 | */ | |
168 | extern int lttng_track_id(struct lttng_handle *handle, | |
169 | enum lttng_tracker_type tracker_type, | |
170 | struct lttng_tracker_id *id); | |
171 | ||
172 | /* | |
173 | * Remove ID from session tracker. | |
174 | * | |
175 | * tracker_type is the type of tracker. | |
176 | * An id argument >= 0 removes the ID from the session tracker. | |
177 | * An id argument of -1 means "untrack all IDs". | |
178 | * | |
179 | * Return 0 on success else a negative LTTng error code. | |
180 | */ | |
181 | extern int lttng_untrack_id(struct lttng_handle *handle, | |
182 | enum lttng_tracker_type tracker_type, | |
183 | struct lttng_tracker_id *id); | |
184 | ||
185 | /* | |
186 | * List IDs in the tracker. | |
187 | * | |
188 | * tracker_type is the type of tracker. | |
189 | * ids is set to an allocated array of IDs currently tracked. On | |
190 | * success, ids and the strings it contains must be freed by the | |
191 | * caller. | |
192 | * nr_ids is set to the number of entries contained by the ids array. | |
193 | * | |
194 | * Returns 0 on success, else a negative LTTng error code. | |
195 | */ | |
196 | extern int lttng_list_tracker_ids(struct lttng_handle *handle, | |
197 | enum lttng_tracker_type tracker_type, | |
198 | struct lttng_tracker_id **ids, | |
199 | size_t *nr_ids); | |
200 | ||
ccf10263 MD |
201 | /* |
202 | * Add PID to session tracker. | |
203 | * | |
204 | * A pid argument >= 0 adds the PID to the session tracker. | |
205 | * A pid argument of -1 means "track all PIDs". | |
206 | * | |
207 | * Return 0 on success else a negative LTTng error code. | |
208 | */ | |
209 | extern int lttng_track_pid(struct lttng_handle *handle, int pid); | |
210 | ||
211 | /* | |
212 | * Remove PID from session tracker. | |
213 | * | |
214 | * A pid argument >= 0 removes the PID from the session tracker. | |
215 | * A pid argument of -1 means "untrack all PIDs". | |
216 | * | |
217 | * Return 0 on success else a negative LTTng error code. | |
218 | */ | |
219 | extern int lttng_untrack_pid(struct lttng_handle *handle, int pid); | |
220 | ||
a5dfbb9d MD |
221 | /* |
222 | * List PIDs in the tracker. | |
223 | * | |
36dc4128 JG |
224 | * enabled is set to whether the PID tracker is enabled. |
225 | * pids is set to an allocated array of PIDs currently tracked. On | |
226 | * success, pids must be freed by the caller. | |
227 | * nr_pids is set to the number of entries contained by the pids array. | |
a5dfbb9d MD |
228 | * |
229 | * Returns 0 on success, else a negative LTTng error code. | |
230 | */ | |
231 | extern int lttng_list_tracker_pids(struct lttng_handle *handle, | |
232 | int *enabled, int32_t **pids, size_t *nr_pids); | |
233 | ||
1239a312 DG |
234 | #ifdef __cplusplus |
235 | } | |
236 | #endif | |
237 | ||
238 | #endif /* LTTNG_SESSION_H */ |