Fix: improve and update lttng.h comments
[lttng-tools.git] / include / lttng / lttng.h
CommitLineData
826d496d 1/*
b7384347
DG
2 * lttng.h
3 *
4 * Linux Trace Toolkit Control Library Header File
5 *
826d496d 6 * Copyright (C) 2011 - David Goulet <david.goulet@polymtl.ca>
fac6795d 7 *
1e46a50f 8 * This library is free software; you can redistribute it and/or modify it
d14d33bf
AM
9 * under the terms of the GNU Lesser General Public License, version 2.1 only,
10 * as published by the Free Software Foundation.
82a3637f 11 *
1e46a50f
TD
12 * This library is distributed in the hope that it will be useful, but WITHOUT
13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
15 * for more details.
82a3637f 16 *
1e46a50f
TD
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with this library; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
fac6795d
DG
20 */
21
73db5be4
DG
22#ifndef LTTNG_H
23#define LTTNG_H
fac6795d 24
57167058 25#include <limits.h>
73e0d944
JG
26/*
27 * Necessary to include the fixed width type limits on glibc versions older
28 * than 2.18 when building with a C++ compiler.
29 */
30#ifndef __STDC_LIMIT_MACROS
31#define __STDC_LIMIT_MACROS
32#include <stdint.h>
33#undef __STDC_LIMIT_MACROS
34#else /* #ifndef __STDC_LIMIT_MACROS */
1e307fab 35#include <stdint.h>
73e0d944 36#endif /* #else #ifndef __STDC_LIMIT_MACROS */
1e307fab 37#include <sys/types.h>
57167058 38
03b1319d
DG
39/* Error codes that can be returned by API calls */
40#include <lttng/lttng-error.h>
41
5168918c
DG
42#ifdef __cplusplus
43extern "C" {
44#endif
45
b7384347 46/*
e6ddca71 47 * Event symbol length. Copied from LTTng kernel ABI.
1657e9bb 48 */
8d326ab9 49#define LTTNG_SYMBOL_NAME_LEN 256
f3ed775e 50
e6ddca71
DG
51/*
52 * Every lttng_event_* structure both apply to kernel event and user-space
53 * event.
e6ddca71
DG
54 */
55
7d29a247 56/*
1e46a50f 57 * Domain types: the different possible tracers.
7d29a247
DG
58 */
59enum lttng_domain_type {
b9dfb167
DG
60 LTTNG_DOMAIN_KERNEL = 1, /* Linux Kernel tracer. */
61 LTTNG_DOMAIN_UST = 2, /* Global Userspace tracer. */
62 LTTNG_DOMAIN_JUL = 3, /* Java Util Logging. */
7d29a247
DG
63};
64
7d29a247
DG
65/*
66 * Instrumentation type of tracing event.
67 */
f3ed775e 68enum lttng_event_type {
7a3d1328
MD
69 LTTNG_EVENT_ALL = -1,
70 LTTNG_EVENT_TRACEPOINT = 0,
71 LTTNG_EVENT_PROBE = 1,
72 LTTNG_EVENT_FUNCTION = 2,
73 LTTNG_EVENT_FUNCTION_ENTRY = 3,
74 LTTNG_EVENT_NOOP = 4,
75 LTTNG_EVENT_SYSCALL = 5,
0cda4f28
MD
76};
77
78/*
79 * Loglevel information.
80 */
81enum lttng_loglevel_type {
8005f29a
MD
82 LTTNG_EVENT_LOGLEVEL_ALL = 0,
83 LTTNG_EVENT_LOGLEVEL_RANGE = 1,
84 LTTNG_EVENT_LOGLEVEL_SINGLE = 2,
1657e9bb
DG
85};
86
46839cc2
MD
87/*
88 * Available loglevels.
89 */
90enum lttng_loglevel {
00e2e675
DG
91 LTTNG_LOGLEVEL_EMERG = 0,
92 LTTNG_LOGLEVEL_ALERT = 1,
93 LTTNG_LOGLEVEL_CRIT = 2,
94 LTTNG_LOGLEVEL_ERR = 3,
95 LTTNG_LOGLEVEL_WARNING = 4,
96 LTTNG_LOGLEVEL_NOTICE = 5,
97 LTTNG_LOGLEVEL_INFO = 6,
98 LTTNG_LOGLEVEL_DEBUG_SYSTEM = 7,
99 LTTNG_LOGLEVEL_DEBUG_PROGRAM = 8,
100 LTTNG_LOGLEVEL_DEBUG_PROCESS = 9,
101 LTTNG_LOGLEVEL_DEBUG_MODULE = 10,
102 LTTNG_LOGLEVEL_DEBUG_UNIT = 11,
103 LTTNG_LOGLEVEL_DEBUG_FUNCTION = 12,
104 LTTNG_LOGLEVEL_DEBUG_LINE = 13,
105 LTTNG_LOGLEVEL_DEBUG = 14,
46839cc2
MD
106};
107
b2064f54
DG
108/*
109 * Available loglevels for the JUL domain. Those are an exact map from the
110 * class java.util.logging.Level.
111 */
112enum lttng_loglevel_jul {
113 LTTNG_LOGLEVEL_JUL_OFF = INT32_MAX,
114 LTTNG_LOGLEVEL_JUL_SEVERE = 1000,
115 LTTNG_LOGLEVEL_JUL_WARNING = 900,
116 LTTNG_LOGLEVEL_JUL_INFO = 800,
117 LTTNG_LOGLEVEL_JUL_CONFIG = 700,
118 LTTNG_LOGLEVEL_JUL_FINE = 500,
119 LTTNG_LOGLEVEL_JUL_FINER = 400,
120 LTTNG_LOGLEVEL_JUL_FINEST = 300,
121 LTTNG_LOGLEVEL_JUL_ALL = INT32_MIN,
122};
123
e6ddca71
DG
124/*
125 * LTTng consumer mode
126 */
127enum lttng_event_output {
d78d6610
DG
128 LTTNG_EVENT_SPLICE = 0,
129 LTTNG_EVENT_MMAP = 1,
e6ddca71
DG
130};
131
7d29a247
DG
132/* Event context possible type */
133enum lttng_event_context_type {
d78d6610 134 LTTNG_EVENT_CONTEXT_PID = 0,
aa3514e9 135 LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, /* Backward compat. */
9197c5c4 136 LTTNG_EVENT_CONTEXT_PROCNAME = 2,
d78d6610
DG
137 LTTNG_EVENT_CONTEXT_PRIO = 3,
138 LTTNG_EVENT_CONTEXT_NICE = 4,
139 LTTNG_EVENT_CONTEXT_VPID = 5,
140 LTTNG_EVENT_CONTEXT_TID = 6,
141 LTTNG_EVENT_CONTEXT_VTID = 7,
142 LTTNG_EVENT_CONTEXT_PPID = 8,
143 LTTNG_EVENT_CONTEXT_VPPID = 9,
9197c5c4 144 LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10,
54773d68 145 LTTNG_EVENT_CONTEXT_HOSTNAME = 11,
7c612c2e 146 LTTNG_EVENT_CONTEXT_IP = 12,
aa3514e9
MD
147 LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER = 13,
148 LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER = 14,
d65106b1
DG
149};
150
d0254c7c 151enum lttng_calibrate_type {
d78d6610 152 LTTNG_CALIBRATE_FUNCTION = 0,
d0254c7c
MD
153};
154
44a5e5eb
DG
155/* Health component for the health check function. */
156enum lttng_health_component {
157 LTTNG_HEALTH_CMD,
139ac872 158 LTTNG_HEALTH_APP_MANAGE,
44a5e5eb
DG
159 LTTNG_HEALTH_APP_REG,
160 LTTNG_HEALTH_KERNEL,
161 LTTNG_HEALTH_CONSUMER,
0b2dc8df 162 LTTNG_HEALTH_HT_CLEANUP,
380e8d6f 163 LTTNG_HEALTH_APP_MANAGE_NOTIFY,
12e2b881 164 LTTNG_HEALTH_APP_REG_DISPATCH,
44a5e5eb
DG
165 LTTNG_HEALTH_ALL,
166};
167
7972aab2
DG
168/* Buffer type for a specific domain. */
169enum lttng_buffer_type {
170 LTTNG_BUFFER_PER_PID, /* Only supported by UST being the default. */
171 LTTNG_BUFFER_PER_UID, /* Only supported by UST. */
172 LTTNG_BUFFER_GLOBAL, /* Only supported by the Kernel. */
173};
174
ece640c8
RB
175/*
176 * The structures should be initialized to zero before use.
177 */
7972aab2 178#define LTTNG_DOMAIN_PADDING1 12
8d326ab9 179#define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
9f19cc17
DG
180struct lttng_domain {
181 enum lttng_domain_type type;
7972aab2 182 enum lttng_buffer_type buf_type;
8d326ab9
DG
183 char padding[LTTNG_DOMAIN_PADDING1];
184
9f19cc17
DG
185 union {
186 pid_t pid;
187 char exec_name[NAME_MAX];
8d326ab9 188 char padding[LTTNG_DOMAIN_PADDING2];
9f19cc17 189 } attr;
54c90d10 190};
9f19cc17 191
ece640c8
RB
192/*
193 * Perf counter attributes
194 *
195 * The structures should be initialized to zero before use.
196 */
8d326ab9 197#define LTTNG_PERF_EVENT_PADDING1 16
7d29a247 198struct lttng_event_perf_counter_ctx {
d65106b1
DG
199 uint32_t type;
200 uint64_t config;
201 char name[LTTNG_SYMBOL_NAME_LEN];
8d326ab9
DG
202
203 char padding[LTTNG_PERF_EVENT_PADDING1];
54c90d10 204};
d65106b1 205
ece640c8
RB
206/*
207 * Event/channel context
208 *
209 * The structures should be initialized to zero before use.
210 */
8d326ab9
DG
211#define LTTNG_EVENT_CONTEXT_PADDING1 16
212#define LTTNG_EVENT_CONTEXT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
7d29a247
DG
213struct lttng_event_context {
214 enum lttng_event_context_type ctx;
8d326ab9
DG
215 char padding[LTTNG_EVENT_CONTEXT_PADDING1];
216
d65106b1 217 union {
7d29a247 218 struct lttng_event_perf_counter_ctx perf_counter;
8d326ab9 219 char padding[LTTNG_EVENT_CONTEXT_PADDING2];
d65106b1 220 } u;
54c90d10 221};
d65106b1 222
b7384347 223/*
7d29a247
DG
224 * Event probe.
225 *
226 * Either addr is used or symbol_name and offset.
ece640c8
RB
227 *
228 * The structures should be initialized to zero before use.
57167058 229 */
8d326ab9 230#define LTTNG_EVENT_PROBE_PADDING1 16
7d29a247 231struct lttng_event_probe_attr {
f3ed775e
DG
232 uint64_t addr;
233
234 uint64_t offset;
235 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
8d326ab9
DG
236
237 char padding[LTTNG_EVENT_PROBE_PADDING1];
54c90d10 238};
57167058 239
b7384347 240/*
f3ed775e 241 * Function tracer
ece640c8
RB
242 *
243 * The structures should be initialized to zero before use.
f3ed775e 244 */
8d326ab9 245#define LTTNG_EVENT_FUNCTION_PADDING1 16
f3ed775e
DG
246struct lttng_event_function_attr {
247 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
8d326ab9
DG
248
249 char padding[LTTNG_EVENT_FUNCTION_PADDING1];
54c90d10 250};
f3ed775e
DG
251
252/*
253 * Generic lttng event
ece640c8
RB
254 *
255 * The structures should be initialized to zero before use.
f3ed775e 256 */
4634f12e 257#define LTTNG_EVENT_PADDING1 14
8d326ab9 258#define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
f3ed775e 259struct lttng_event {
0cda4f28 260 enum lttng_event_type type;
f3ed775e 261 char name[LTTNG_SYMBOL_NAME_LEN];
0cda4f28
MD
262
263 enum lttng_loglevel_type loglevel_type;
8005f29a 264 int loglevel;
0cda4f28 265
35dc4d62 266 int32_t enabled; /* Does not apply: -1 */
b551a063 267 pid_t pid;
fceb65df 268 unsigned char filter; /* filter enabled ? */
4634f12e 269 unsigned char exclusion; /* exclusions added ? */
8d326ab9
DG
270
271 char padding[LTTNG_EVENT_PADDING1];
272
f3ed775e
DG
273 /* Per event type configuration */
274 union {
7d29a247 275 struct lttng_event_probe_attr probe;
f3ed775e 276 struct lttng_event_function_attr ftrace;
8d326ab9
DG
277
278 char padding[LTTNG_EVENT_PADDING2];
f3ed775e 279 } attr;
54c90d10 280};
f3ed775e 281
f37d259d
MD
282enum lttng_event_field_type {
283 LTTNG_EVENT_FIELD_OTHER = 0,
284 LTTNG_EVENT_FIELD_INTEGER = 1,
285 LTTNG_EVENT_FIELD_ENUM = 2,
286 LTTNG_EVENT_FIELD_FLOAT = 3,
287 LTTNG_EVENT_FIELD_STRING = 4,
288};
289
290#define LTTNG_EVENT_FIELD_PADDING LTTNG_SYMBOL_NAME_LEN + 32
291struct lttng_event_field {
292 char field_name[LTTNG_SYMBOL_NAME_LEN];
293 enum lttng_event_field_type type;
294 char padding[LTTNG_EVENT_FIELD_PADDING];
295 struct lttng_event event;
590b9e3c 296 int nowrite;
54c90d10 297};
f37d259d 298
e6ddca71
DG
299/*
300 * Tracer channel attributes. For both kernel and user-space.
ece640c8
RB
301 *
302 * The structures should be initialized to zero before use.
e6ddca71 303 */
ecc48a90 304#define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12
f3ed775e 305struct lttng_channel_attr {
8ce37aa5
DG
306 int overwrite; /* 1: overwrite, 0: discard */
307 uint64_t subbuf_size; /* bytes */
308 uint64_t num_subbuf; /* power of 2 */
309 unsigned int switch_timer_interval; /* usec */
310 unsigned int read_timer_interval; /* usec */
f05b5f07 311 enum lttng_event_output output; /* splice, mmap */
1624d5b7
JD
312 /* LTTng 2.1 padding limit */
313 uint64_t tracefile_size; /* bytes */
314 uint64_t tracefile_count; /* number of tracefiles */
ecc48a90
JD
315 /* LTTng 2.3 padding limit */
316 unsigned int live_timer_interval; /* usec */
8d326ab9
DG
317
318 char padding[LTTNG_CHANNEL_ATTR_PADDING1];
54c90d10 319};
f3ed775e
DG
320
321/*
e6ddca71 322 * Channel information structure. For both kernel and user-space.
ece640c8
RB
323 *
324 * The structures should be initialized to zero before use.
1657e9bb 325 */
8d326ab9 326#define LTTNG_CHANNEL_PADDING1 16
e6ddca71 327struct lttng_channel {
045e5491 328 char name[LTTNG_SYMBOL_NAME_LEN];
9f19cc17 329 uint32_t enabled;
e6ddca71 330 struct lttng_channel_attr attr;
8d326ab9
DG
331
332 char padding[LTTNG_CHANNEL_PADDING1];
54c90d10 333};
f3ed775e 334
8d326ab9 335#define LTTNG_CALIBRATE_PADDING1 16
d0254c7c
MD
336struct lttng_calibrate {
337 enum lttng_calibrate_type type;
8d326ab9
DG
338
339 char padding[LTTNG_CALIBRATE_PADDING1];
54c90d10 340};
d0254c7c 341
e6ddca71
DG
342/*
343 * Basic session information.
344 *
345 * This is an 'output data' meaning that it only comes *from* the session
346 * daemon *to* the lttng client. It's basically a 'human' representation of
347 * tracing entities (here a session).
ece640c8
RB
348 *
349 * The structures should be initialized to zero before use.
e6ddca71 350 */
2cbf8fed 351#define LTTNG_SESSION_PADDING1 12
e6ddca71 352struct lttng_session {
f3ed775e 353 char name[NAME_MAX];
e6ddca71
DG
354 /* The path where traces are written */
355 char path[PATH_MAX];
464dd62d 356 uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */
2cbf8fed 357 uint32_t snapshot_mode;
ecc48a90 358 unsigned int live_timer_interval; /* usec */
8d326ab9
DG
359
360 char padding[LTTNG_SESSION_PADDING1];
54c90d10 361};
1657e9bb 362
cd80958d
DG
363/*
364 * Handle used as a context for commands.
ece640c8
RB
365 *
366 * The structures should be initialized to zero before use.
cd80958d 367 */
8d326ab9 368#define LTTNG_HANDLE_PADDING1 16
cd80958d
DG
369struct lttng_handle {
370 char session_name[NAME_MAX];
371 struct lttng_domain domain;
8d326ab9
DG
372
373 char padding[LTTNG_HANDLE_PADDING1];
54c90d10 374};
cd80958d 375
7d29a247
DG
376/*
377 * Public LTTng control API
cd80958d 378 */
7d29a247
DG
379
380/*
a4b92340
DG
381 * Create a tracing session using a name and an optional URL.
382 *
41039c06
DG
383 * If _url_ is NULL, no consumer is created for the session. The name can't be
384 * NULL here.
06662f07
DG
385 *
386 * Return 0 on success else a negative LTTng error code.
00e2e675 387 */
a4b92340 388extern int lttng_create_session(const char *name, const char *url);
00e2e675 389
27babd3a
DG
390/*
391 * Create a tracing session that will exclusively be used for snapshot meaning
392 * the session will be in no output mode and every channel enabled for that
393 * session will be set in overwrite mode and in mmap output since splice is not
394 * supported.
395 *
06662f07
DG
396 * Name can't be NULL. If an url is given, it will be used to create a default
397 * snapshot output using it as a destination. If NULL, no output will be
398 * defined and an add-output call will be needed.
27babd3a 399 *
06662f07 400 * Return 0 on success else a negative LTTng error code.
27babd3a
DG
401 */
402extern int lttng_create_session_snapshot(const char *name,
403 const char *snapshot_url);
404
ecc48a90
JD
405/*
406 * Create a session exclusively used for live reading.
407 *
408 * In this mode, the switch-timer parameter is forced for each UST channel, a
409 * live-switch-timer is enabled for kernel channels, manually setting
410 * switch-timer is forbidden. Synchronization beacons are sent to the relayd,
411 * indexes are sent and metadata is checked for each packet.
412 *
06662f07
DG
413 * Name can't be NULL. If no URL is given, the default is to send the data to
414 * net://127.0.0.1. The timer_interval is in usec and by default set to 1000000
415 * (1 second).
416 *
417 * Return 0 on success else a negative LTTng error code.
ecc48a90
JD
418 */
419extern int lttng_create_session_live(const char *name, const char *url,
420 unsigned int timer_interval);
421
06662f07
DG
422/*
423 * Create an handle used as a context for every request made to the library.
424 *
425 * This handle contains the session name and domain on which the command will
426 * be executed. A domain is basically a tracer like the kernel or user space.
427 *
428 * Return an newly allocated handle that should be freed using
429 * lttng_destroy_handle. On error, NULL is returned.
430 */
431extern struct lttng_handle *lttng_create_handle(const char *session_name,
432 struct lttng_domain *domain);
433
434/*
435 * Destroy an handle that has been previously created with lttng_create_handle.
436 *
437 * It free the given pointer making it unusable.
438 */
439extern void lttng_destroy_handle(struct lttng_handle *handle);
440
7d29a247 441/*
1e46a50f 442 * Destroy a tracing session.
7d29a247 443 *
06662f07
DG
444 * The session will not be usable, tracing will be stopped thus buffers will be
445 * flushed.
41039c06
DG
446 *
447 * The name can't be NULL here.
06662f07
DG
448 *
449 * Return 0 on success else a negative LTTng error code.
7d29a247 450 */
843f5df9 451extern int lttng_destroy_session(const char *name);
f3ed775e 452
e6ddca71 453/*
1e46a50f 454 * List all the tracing sessions.
7d29a247 455 *
1e46a50f 456 * Return the size (number of entries) of the "lttng_session" array. Caller
06662f07 457 * must free sessions. On error, a negative LTTng error code is returned.
e6ddca71 458 */
ca95a216 459extern int lttng_list_sessions(struct lttng_session **sessions);
f3ed775e 460
9f19cc17 461/*
1e46a50f 462 * List the registered domain(s) of a session.
9f19cc17 463 *
06662f07
DG
464 * Session name CAN NOT be NULL.
465 *
1e46a50f 466 * Return the size (number of entries) of the "lttng_domain" array. Caller
06662f07 467 * must free domains. On error, a negative LTTng error code is returned.
9f19cc17 468 */
330be774 469extern int lttng_list_domains(const char *session_name,
9f19cc17
DG
470 struct lttng_domain **domains);
471
472/*
1e46a50f 473 * List the channel(s) of a session.
9f19cc17 474 *
06662f07
DG
475 * The handle CAN NOT be NULL.
476 *
1e46a50f 477 * Return the size (number of entries) of the "lttng_channel" array. Caller
06662f07 478 * must free channels. On error, a negative LTTng error code is returned.
9f19cc17 479 */
cd80958d
DG
480extern int lttng_list_channels(struct lttng_handle *handle,
481 struct lttng_channel **channels);
9f19cc17
DG
482
483/*
1e46a50f 484 * List the event(s) of a session channel.
9f19cc17 485 *
06662f07
DG
486 * Both handle and channel_name CAN NOT be NULL.
487 *
488 * Return the size (number of entries) of the "lttng_event" array. Caller must
489 * free events. On error a negative LTTng error code is returned.
9f19cc17 490 */
cd80958d
DG
491extern int lttng_list_events(struct lttng_handle *handle,
492 const char *channel_name, struct lttng_event **events);
9f19cc17
DG
493
494/*
1e46a50f 495 * List the available tracepoints of a specific lttng domain.
9f19cc17 496 *
06662f07
DG
497 * The handle CAN NOT be NULL.
498 *
499 * Return the size (number of entries) of the "lttng_event" array. Caller must
500 * free events. On error a negative LTTng error code is returned.
9f19cc17 501 */
cd80958d 502extern int lttng_list_tracepoints(struct lttng_handle *handle,
2a71efd5 503 struct lttng_event **events);
9f19cc17 504
f37d259d
MD
505/*
506 * List the available tracepoints fields of a specific lttng domain.
507 *
06662f07
DG
508 * The handle CAN NOT be NULL.
509 *
f37d259d 510 * Return the size (number of entries) of the "lttng_event_field" array.
06662f07
DG
511 * Caller must free fields. On error a negative LTTng error code is
512 * returned.
f37d259d
MD
513 */
514extern int lttng_list_tracepoint_fields(struct lttng_handle *handle,
515 struct lttng_event_field **fields);
516
7d29a247
DG
517/*
518 * Check if a session daemon is alive.
1e46a50f 519 *
06662f07
DG
520 * Return 1 if alive or 0 if not. On error, returns a negative negative LTTng
521 * error code.
7d29a247 522 */
947308c4 523extern int lttng_session_daemon_alive(void);
f3ed775e 524
7d29a247 525/*
1e46a50f
TD
526 * Set the tracing group for the *current* flow of execution.
527 *
06662f07 528 * On success, returns 0 else a negative LTTng error code.
7d29a247 529 */
b7384347 530extern int lttng_set_tracing_group(const char *name);
f3ed775e 531
7d29a247 532/*
06662f07 533 * Return a human-readable error message for a LTTng error code.
7d29a247
DG
534 *
535 * Parameter MUST be a negative value or else you'll get a generic message.
536 */
9a745bc7 537extern const char *lttng_strerror(int code);
b7384347 538
d9800920 539/*
1e46a50f
TD
540 * This call registers an "outside consumer" for a session and an lttng domain.
541 * No consumer will be spawned and all fds/commands will go through the socket
542 * path given (socket_path).
d9800920 543 *
06662f07
DG
544 * NOTE that this is not recommended unless you absolutely know what you are
545 * doing.
546 *
547 * Return 0 on success else a negative LTTng error code.
d9800920
DG
548 */
549extern int lttng_register_consumer(struct lttng_handle *handle,
550 const char *socket_path);
551
7d29a247 552/*
06662f07
DG
553 * Start tracing for *all* domain(s) in the session.
554 *
555 * Return 0 on success else a negative LTTng error code.
7d29a247 556 */
6a4f824d 557extern int lttng_start_tracing(const char *session_name);
f3ed775e 558
7d29a247 559/*
06662f07 560 * Stop tracing for *all* domain(s) in the session.
38ee087f
DG
561 *
562 * This call will wait for data availability for each domain of the session so
563 * this can take an abritrary amount of time. However, when returning you have
06662f07 564 * the guarantee that the data is ready to be read and analyze. Use the
38ee087f 565 * _no_wait call below to avoid this behavior.
41039c06
DG
566 *
567 * The session_name can't be NULL.
06662f07
DG
568 *
569 * Return 0 on success else a negative LTTng error code.
7d29a247 570 */
6a4f824d 571extern int lttng_stop_tracing(const char *session_name);
f3ed775e 572
38ee087f
DG
573/*
574 * Behave exactly like lttng_stop_tracing but does not wait for data
575 * availability.
576 */
577extern int lttng_stop_tracing_no_wait(const char *session_name);
578
b7384347 579/*
1e46a50f 580 * Add context to event(s) for a specific channel (or for all).
7d29a247 581 *
06662f07
DG
582 * If the channel_name is NULL and they are no channel for the domain, the
583 * default channel is created (channel0). The context is then added on ALL
584 * channels since no name was specified.
585 *
586 * The event_name is ignored since adding a context to an event is not possible
587 * for now.
41039c06 588 *
06662f07 589 * Return 0 on success else a negative LTTng error code.
b7384347 590 */
cd80958d 591extern int lttng_add_context(struct lttng_handle *handle,
38057ed1
DG
592 struct lttng_event_context *ctx, const char *event_name,
593 const char *channel_name);
f3ed775e 594
7d29a247 595/*
c8f61fc6 596 * Create or enable an event (or events) for a channel.
7d29a247
DG
597 *
598 * If the event you are trying to enable does not exist, it will be created,
06662f07
DG
599 * else it is enabled. If channel_name is NULL, the default channel is used
600 * (channel0).
41039c06
DG
601 *
602 * The handle and ev params can not be NULL.
06662f07
DG
603 *
604 * Return 0 on success else a negative LTTng error code.
7d29a247 605 */
cd80958d
DG
606extern int lttng_enable_event(struct lttng_handle *handle,
607 struct lttng_event *ev, const char *channel_name);
f3ed775e 608
53a80697 609/*
025faf73 610 * Create or enable an event with a specific filter.
53a80697 611 *
025faf73
DG
612 * If the event you are trying to enable does not exist, it will be created,
613 * else it is enabled.
41039c06 614 * If ev is NULL, all events are enabled with that filter.
025faf73
DG
615 * If channel_name is NULL, the default channel is used (channel0) and created
616 * if not found.
52df2401
MD
617 * If filter_expression is NULL, an event without associated filter is
618 * created.
06662f07
DG
619 *
620 * Return 0 on success else a negative LTTng error code.
53a80697 621 */
025faf73 622extern int lttng_enable_event_with_filter(struct lttng_handle *handle,
178191b3 623 struct lttng_event *event, const char *channel_name,
53a80697 624 const char *filter_expression);
178191b3 625
93deb080
JI
626/*
627 * Create or enable an event with a filter and/or exclusions.
628 *
629 * If the event you are trying to enable does not exist, it will be created,
630 * else it is enabled.
631 * If ev is NULL, all events are enabled with the filter and exclusion options.
632 * If channel_name is NULL, the default channel is used (channel0) and created
633 * if not found.
634 * If filter_expression is NULL, an event without associated filter is
635 * created.
636 * If exclusion count is zero, the event will be created without exclusions.
06662f07
DG
637 *
638 * Return 0 on success else a negative LTTng error code.
93deb080
JI
639 */
640extern int lttng_enable_event_with_exclusions(struct lttng_handle *handle,
641 struct lttng_event *event, const char *channel_name,
642 const char *filter_expression,
643 int exclusion_count, char **exclusion_names);
644
7d29a247 645/*
c8f61fc6 646 * Create or enable a channel.
41039c06
DG
647 *
648 * The chan and handle params can not be NULL.
06662f07
DG
649 *
650 * Return 0 on success else a negative LTTng error code.
7d29a247 651 */
cd80958d 652extern int lttng_enable_channel(struct lttng_handle *handle,
38057ed1 653 struct lttng_channel *chan);
f3ed775e 654
7d29a247 655/*
c8f61fc6 656 * Disable event(s) of a channel and domain.
7d29a247 657 *
41039c06 658 * If name is NULL, all events are disabled.
7d29a247 659 * If channel_name is NULL, the default channel is used (channel0).
06662f07
DG
660 *
661 * Return 0 on success else a negative LTTng error code.
7d29a247 662 */
cd80958d
DG
663extern int lttng_disable_event(struct lttng_handle *handle,
664 const char *name, const char *channel_name);
fac6795d 665
1df4dedd 666/*
c8f61fc6 667 * Disable channel.
7d29a247 668 *
06662f07
DG
669 * Name and handle CAN NOT be NULL.
670 *
671 * Return 0 on success else a negative LTTng error code.
1df4dedd 672 */
cd80958d 673extern int lttng_disable_channel(struct lttng_handle *handle,
38057ed1 674 const char *name);
1df4dedd 675
d0254c7c
MD
676/*
677 * Calibrate LTTng overhead.
41039c06
DG
678 *
679 * The chan and handle params can not be NULL.
06662f07
DG
680 *
681 * Return 0 on success else a negative LTTng error code.
d0254c7c 682 */
cd80958d 683extern int lttng_calibrate(struct lttng_handle *handle,
d0254c7c
MD
684 struct lttng_calibrate *calibrate);
685
5edd7e09
DG
686/*
687 * Set the default channel attributes for a specific domain and an allocated
688 * lttng_channel_attr pointer.
1e46a50f 689 *
41039c06 690 * If one or both arguments are NULL, nothing happens.
5edd7e09
DG
691 */
692extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
693 struct lttng_channel_attr *attr);
694
00e2e675 695/*
a4b92340
DG
696 * Set URL for a consumer for a session and domain.
697 *
698 * Both data and control URL must be defined. If both URLs are the same, only
699 * the control URL is used even for network streaming.
00e2e675 700 *
a4b92340
DG
701 * Default port are 5342 and 5343 respectively for control and data which uses
702 * the TCP protocol.
06662f07
DG
703 *
704 * URL format: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
705 *
706 * Possible protocols are:
707 * > file://...
708 * Local filesystem full path.
709 *
710 * > net[6]://...
711 * This will use the default network transport layer which is TCP for both
712 * control (PORT1) and data port (PORT2).
713 *
714 * > tcp[6]://...
715 * TCP only streaming. For this one, both data and control URL must be given.
716 *
717 * Return 0 on success else a negative LTTng error code.
00e2e675 718 */
a4b92340
DG
719extern int lttng_set_consumer_url(struct lttng_handle *handle,
720 const char *control_url, const char *data_url);
00e2e675
DG
721
722/*
723 * Enable the consumer for a session and domain.
724 */
9c6bda17 725extern LTTNG_DEPRECATED("This call is now obsolete.")
785d2d0d 726int lttng_enable_consumer(struct lttng_handle *handle);
00e2e675
DG
727
728/*
729 * Disable consumer for a session and domain.
730 */
9c6bda17 731extern LTTNG_DEPRECATED("This call is now obsolete.")
785d2d0d 732int lttng_disable_consumer(struct lttng_handle *handle);
00e2e675 733
44a5e5eb
DG
734/*
735 * Check session daemon health for a specific component.
736 *
737 * Return 0 if health is OK or 1 if BAD. A returned value of -1 indicate that
738 * the control library was not able to connect to the session daemon health
739 * socket.
740 *
741 * Any other positive value is an lttcomm error which can be translate with
742 * lttng_strerror().
41039c06
DG
743 *
744 * Please see lttng-health-check(3) man page for more information.
44a5e5eb 745 */
d74df422
MD
746extern LTTNG_DEPRECATED("This call is now obsolete.")
747int lttng_health_check(enum lttng_health_component c);
44a5e5eb 748
806e2684
DG
749/*
750 * For a given session name, this call checks if the data is ready to be read
6d805429
DG
751 * or is still being extracted by the consumer(s) (pending) hence not ready to
752 * be used by any readers.
806e2684 753 *
6d805429
DG
754 * Return 0 if there is _no_ data pending in the buffers thus having a
755 * guarantee that the data can be read safely. Else, return 1 if there is still
756 * traced data is pending. On error, a negative value is returned and readable
757 * by lttng_strerror().
806e2684 758 */
6d805429 759extern int lttng_data_pending(const char *session_name);
806e2684 760
5168918c
DG
761#ifdef __cplusplus
762}
763#endif
764
73db5be4 765#endif /* LTTNG_H */
This page took 0.119599 seconds and 4 git commands to generate.