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 | ||
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 | * | |
ca077825 | 59 | * Network output locations can also be auto-generated by leaving the |
b178f53e JG |
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 | * | |
ca077825 | 64 | * The format of the 'control_url' and 'data_url' parameters is: |
b178f53e JG |
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 | |
ca077825 | 115 | * use the default local output destination. |
b178f53e JG |
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 */ |