Fix: improve and update lttng.h comments
[lttng-tools.git] / include / lttng / lttng.h
1 /*
2 * lttng.h
3 *
4 * Linux Trace Toolkit Control Library Header File
5 *
6 * Copyright (C) 2011 - David Goulet <david.goulet@polymtl.ca>
7 *
8 * This library is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License, version 2.1 only,
10 * as published by the Free Software Foundation.
11 *
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.
16 *
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
20 */
21
22 #ifndef LTTNG_H
23 #define LTTNG_H
24
25 #include <limits.h>
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 */
35 #include <stdint.h>
36 #endif /* #else #ifndef __STDC_LIMIT_MACROS */
37 #include <sys/types.h>
38
39 /* Error codes that can be returned by API calls */
40 #include <lttng/lttng-error.h>
41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46 /*
47 * Event symbol length. Copied from LTTng kernel ABI.
48 */
49 #define LTTNG_SYMBOL_NAME_LEN 256
50
51 /*
52 * Every lttng_event_* structure both apply to kernel event and user-space
53 * event.
54 */
55
56 /*
57 * Domain types: the different possible tracers.
58 */
59 enum lttng_domain_type {
60 LTTNG_DOMAIN_KERNEL = 1, /* Linux Kernel tracer. */
61 LTTNG_DOMAIN_UST = 2, /* Global Userspace tracer. */
62 LTTNG_DOMAIN_JUL = 3, /* Java Util Logging. */
63 };
64
65 /*
66 * Instrumentation type of tracing event.
67 */
68 enum lttng_event_type {
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,
76 };
77
78 /*
79 * Loglevel information.
80 */
81 enum lttng_loglevel_type {
82 LTTNG_EVENT_LOGLEVEL_ALL = 0,
83 LTTNG_EVENT_LOGLEVEL_RANGE = 1,
84 LTTNG_EVENT_LOGLEVEL_SINGLE = 2,
85 };
86
87 /*
88 * Available loglevels.
89 */
90 enum lttng_loglevel {
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,
106 };
107
108 /*
109 * Available loglevels for the JUL domain. Those are an exact map from the
110 * class java.util.logging.Level.
111 */
112 enum 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
124 /*
125 * LTTng consumer mode
126 */
127 enum lttng_event_output {
128 LTTNG_EVENT_SPLICE = 0,
129 LTTNG_EVENT_MMAP = 1,
130 };
131
132 /* Event context possible type */
133 enum lttng_event_context_type {
134 LTTNG_EVENT_CONTEXT_PID = 0,
135 LTTNG_EVENT_CONTEXT_PERF_COUNTER = 1, /* Backward compat. */
136 LTTNG_EVENT_CONTEXT_PROCNAME = 2,
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,
144 LTTNG_EVENT_CONTEXT_PTHREAD_ID = 10,
145 LTTNG_EVENT_CONTEXT_HOSTNAME = 11,
146 LTTNG_EVENT_CONTEXT_IP = 12,
147 LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER = 13,
148 LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER = 14,
149 };
150
151 enum lttng_calibrate_type {
152 LTTNG_CALIBRATE_FUNCTION = 0,
153 };
154
155 /* Health component for the health check function. */
156 enum lttng_health_component {
157 LTTNG_HEALTH_CMD,
158 LTTNG_HEALTH_APP_MANAGE,
159 LTTNG_HEALTH_APP_REG,
160 LTTNG_HEALTH_KERNEL,
161 LTTNG_HEALTH_CONSUMER,
162 LTTNG_HEALTH_HT_CLEANUP,
163 LTTNG_HEALTH_APP_MANAGE_NOTIFY,
164 LTTNG_HEALTH_APP_REG_DISPATCH,
165 LTTNG_HEALTH_ALL,
166 };
167
168 /* Buffer type for a specific domain. */
169 enum 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
175 /*
176 * The structures should be initialized to zero before use.
177 */
178 #define LTTNG_DOMAIN_PADDING1 12
179 #define LTTNG_DOMAIN_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
180 struct lttng_domain {
181 enum lttng_domain_type type;
182 enum lttng_buffer_type buf_type;
183 char padding[LTTNG_DOMAIN_PADDING1];
184
185 union {
186 pid_t pid;
187 char exec_name[NAME_MAX];
188 char padding[LTTNG_DOMAIN_PADDING2];
189 } attr;
190 };
191
192 /*
193 * Perf counter attributes
194 *
195 * The structures should be initialized to zero before use.
196 */
197 #define LTTNG_PERF_EVENT_PADDING1 16
198 struct lttng_event_perf_counter_ctx {
199 uint32_t type;
200 uint64_t config;
201 char name[LTTNG_SYMBOL_NAME_LEN];
202
203 char padding[LTTNG_PERF_EVENT_PADDING1];
204 };
205
206 /*
207 * Event/channel context
208 *
209 * The structures should be initialized to zero before use.
210 */
211 #define LTTNG_EVENT_CONTEXT_PADDING1 16
212 #define LTTNG_EVENT_CONTEXT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
213 struct lttng_event_context {
214 enum lttng_event_context_type ctx;
215 char padding[LTTNG_EVENT_CONTEXT_PADDING1];
216
217 union {
218 struct lttng_event_perf_counter_ctx perf_counter;
219 char padding[LTTNG_EVENT_CONTEXT_PADDING2];
220 } u;
221 };
222
223 /*
224 * Event probe.
225 *
226 * Either addr is used or symbol_name and offset.
227 *
228 * The structures should be initialized to zero before use.
229 */
230 #define LTTNG_EVENT_PROBE_PADDING1 16
231 struct lttng_event_probe_attr {
232 uint64_t addr;
233
234 uint64_t offset;
235 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
236
237 char padding[LTTNG_EVENT_PROBE_PADDING1];
238 };
239
240 /*
241 * Function tracer
242 *
243 * The structures should be initialized to zero before use.
244 */
245 #define LTTNG_EVENT_FUNCTION_PADDING1 16
246 struct lttng_event_function_attr {
247 char symbol_name[LTTNG_SYMBOL_NAME_LEN];
248
249 char padding[LTTNG_EVENT_FUNCTION_PADDING1];
250 };
251
252 /*
253 * Generic lttng event
254 *
255 * The structures should be initialized to zero before use.
256 */
257 #define LTTNG_EVENT_PADDING1 14
258 #define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
259 struct lttng_event {
260 enum lttng_event_type type;
261 char name[LTTNG_SYMBOL_NAME_LEN];
262
263 enum lttng_loglevel_type loglevel_type;
264 int loglevel;
265
266 int32_t enabled; /* Does not apply: -1 */
267 pid_t pid;
268 unsigned char filter; /* filter enabled ? */
269 unsigned char exclusion; /* exclusions added ? */
270
271 char padding[LTTNG_EVENT_PADDING1];
272
273 /* Per event type configuration */
274 union {
275 struct lttng_event_probe_attr probe;
276 struct lttng_event_function_attr ftrace;
277
278 char padding[LTTNG_EVENT_PADDING2];
279 } attr;
280 };
281
282 enum 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
291 struct 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;
296 int nowrite;
297 };
298
299 /*
300 * Tracer channel attributes. For both kernel and user-space.
301 *
302 * The structures should be initialized to zero before use.
303 */
304 #define LTTNG_CHANNEL_ATTR_PADDING1 LTTNG_SYMBOL_NAME_LEN + 12
305 struct lttng_channel_attr {
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 */
311 enum lttng_event_output output; /* splice, mmap */
312 /* LTTng 2.1 padding limit */
313 uint64_t tracefile_size; /* bytes */
314 uint64_t tracefile_count; /* number of tracefiles */
315 /* LTTng 2.3 padding limit */
316 unsigned int live_timer_interval; /* usec */
317
318 char padding[LTTNG_CHANNEL_ATTR_PADDING1];
319 };
320
321 /*
322 * Channel information structure. For both kernel and user-space.
323 *
324 * The structures should be initialized to zero before use.
325 */
326 #define LTTNG_CHANNEL_PADDING1 16
327 struct lttng_channel {
328 char name[LTTNG_SYMBOL_NAME_LEN];
329 uint32_t enabled;
330 struct lttng_channel_attr attr;
331
332 char padding[LTTNG_CHANNEL_PADDING1];
333 };
334
335 #define LTTNG_CALIBRATE_PADDING1 16
336 struct lttng_calibrate {
337 enum lttng_calibrate_type type;
338
339 char padding[LTTNG_CALIBRATE_PADDING1];
340 };
341
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).
348 *
349 * The structures should be initialized to zero before use.
350 */
351 #define LTTNG_SESSION_PADDING1 12
352 struct lttng_session {
353 char name[NAME_MAX];
354 /* The path where traces are written */
355 char path[PATH_MAX];
356 uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */
357 uint32_t snapshot_mode;
358 unsigned int live_timer_interval; /* usec */
359
360 char padding[LTTNG_SESSION_PADDING1];
361 };
362
363 /*
364 * Handle used as a context for commands.
365 *
366 * The structures should be initialized to zero before use.
367 */
368 #define LTTNG_HANDLE_PADDING1 16
369 struct lttng_handle {
370 char session_name[NAME_MAX];
371 struct lttng_domain domain;
372
373 char padding[LTTNG_HANDLE_PADDING1];
374 };
375
376 /*
377 * Public LTTng control API
378 */
379
380 /*
381 * Create a tracing session using a name and an optional URL.
382 *
383 * If _url_ is NULL, no consumer is created for the session. The name can't be
384 * NULL here.
385 *
386 * Return 0 on success else a negative LTTng error code.
387 */
388 extern int lttng_create_session(const char *name, const char *url);
389
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 *
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.
399 *
400 * Return 0 on success else a negative LTTng error code.
401 */
402 extern int lttng_create_session_snapshot(const char *name,
403 const char *snapshot_url);
404
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 *
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.
418 */
419 extern int lttng_create_session_live(const char *name, const char *url,
420 unsigned int timer_interval);
421
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 */
431 extern 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 */
439 extern void lttng_destroy_handle(struct lttng_handle *handle);
440
441 /*
442 * Destroy a tracing session.
443 *
444 * The session will not be usable, tracing will be stopped thus buffers will be
445 * flushed.
446 *
447 * The name can't be NULL here.
448 *
449 * Return 0 on success else a negative LTTng error code.
450 */
451 extern int lttng_destroy_session(const char *name);
452
453 /*
454 * List all the tracing sessions.
455 *
456 * Return the size (number of entries) of the "lttng_session" array. Caller
457 * must free sessions. On error, a negative LTTng error code is returned.
458 */
459 extern int lttng_list_sessions(struct lttng_session **sessions);
460
461 /*
462 * List the registered domain(s) of a session.
463 *
464 * Session name CAN NOT be NULL.
465 *
466 * Return the size (number of entries) of the "lttng_domain" array. Caller
467 * must free domains. On error, a negative LTTng error code is returned.
468 */
469 extern int lttng_list_domains(const char *session_name,
470 struct lttng_domain **domains);
471
472 /*
473 * List the channel(s) of a session.
474 *
475 * The handle CAN NOT be NULL.
476 *
477 * Return the size (number of entries) of the "lttng_channel" array. Caller
478 * must free channels. On error, a negative LTTng error code is returned.
479 */
480 extern int lttng_list_channels(struct lttng_handle *handle,
481 struct lttng_channel **channels);
482
483 /*
484 * List the event(s) of a session channel.
485 *
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.
490 */
491 extern int lttng_list_events(struct lttng_handle *handle,
492 const char *channel_name, struct lttng_event **events);
493
494 /*
495 * List the available tracepoints of a specific lttng domain.
496 *
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.
501 */
502 extern int lttng_list_tracepoints(struct lttng_handle *handle,
503 struct lttng_event **events);
504
505 /*
506 * List the available tracepoints fields of a specific lttng domain.
507 *
508 * The handle CAN NOT be NULL.
509 *
510 * Return the size (number of entries) of the "lttng_event_field" array.
511 * Caller must free fields. On error a negative LTTng error code is
512 * returned.
513 */
514 extern int lttng_list_tracepoint_fields(struct lttng_handle *handle,
515 struct lttng_event_field **fields);
516
517 /*
518 * Check if a session daemon is alive.
519 *
520 * Return 1 if alive or 0 if not. On error, returns a negative negative LTTng
521 * error code.
522 */
523 extern int lttng_session_daemon_alive(void);
524
525 /*
526 * Set the tracing group for the *current* flow of execution.
527 *
528 * On success, returns 0 else a negative LTTng error code.
529 */
530 extern int lttng_set_tracing_group(const char *name);
531
532 /*
533 * Return a human-readable error message for a LTTng error code.
534 *
535 * Parameter MUST be a negative value or else you'll get a generic message.
536 */
537 extern const char *lttng_strerror(int code);
538
539 /*
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).
543 *
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.
548 */
549 extern int lttng_register_consumer(struct lttng_handle *handle,
550 const char *socket_path);
551
552 /*
553 * Start tracing for *all* domain(s) in the session.
554 *
555 * Return 0 on success else a negative LTTng error code.
556 */
557 extern int lttng_start_tracing(const char *session_name);
558
559 /*
560 * Stop tracing for *all* domain(s) in the session.
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
564 * the guarantee that the data is ready to be read and analyze. Use the
565 * _no_wait call below to avoid this behavior.
566 *
567 * The session_name can't be NULL.
568 *
569 * Return 0 on success else a negative LTTng error code.
570 */
571 extern int lttng_stop_tracing(const char *session_name);
572
573 /*
574 * Behave exactly like lttng_stop_tracing but does not wait for data
575 * availability.
576 */
577 extern int lttng_stop_tracing_no_wait(const char *session_name);
578
579 /*
580 * Add context to event(s) for a specific channel (or for all).
581 *
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.
588 *
589 * Return 0 on success else a negative LTTng error code.
590 */
591 extern int lttng_add_context(struct lttng_handle *handle,
592 struct lttng_event_context *ctx, const char *event_name,
593 const char *channel_name);
594
595 /*
596 * Create or enable an event (or events) for a channel.
597 *
598 * If the event you are trying to enable does not exist, it will be created,
599 * else it is enabled. If channel_name is NULL, the default channel is used
600 * (channel0).
601 *
602 * The handle and ev params can not be NULL.
603 *
604 * Return 0 on success else a negative LTTng error code.
605 */
606 extern int lttng_enable_event(struct lttng_handle *handle,
607 struct lttng_event *ev, const char *channel_name);
608
609 /*
610 * Create or enable an event with a specific filter.
611 *
612 * If the event you are trying to enable does not exist, it will be created,
613 * else it is enabled.
614 * If ev is NULL, all events are enabled with that filter.
615 * If channel_name is NULL, the default channel is used (channel0) and created
616 * if not found.
617 * If filter_expression is NULL, an event without associated filter is
618 * created.
619 *
620 * Return 0 on success else a negative LTTng error code.
621 */
622 extern int lttng_enable_event_with_filter(struct lttng_handle *handle,
623 struct lttng_event *event, const char *channel_name,
624 const char *filter_expression);
625
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.
637 *
638 * Return 0 on success else a negative LTTng error code.
639 */
640 extern 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
645 /*
646 * Create or enable a channel.
647 *
648 * The chan and handle params can not be NULL.
649 *
650 * Return 0 on success else a negative LTTng error code.
651 */
652 extern int lttng_enable_channel(struct lttng_handle *handle,
653 struct lttng_channel *chan);
654
655 /*
656 * Disable event(s) of a channel and domain.
657 *
658 * If name is NULL, all events are disabled.
659 * If channel_name is NULL, the default channel is used (channel0).
660 *
661 * Return 0 on success else a negative LTTng error code.
662 */
663 extern int lttng_disable_event(struct lttng_handle *handle,
664 const char *name, const char *channel_name);
665
666 /*
667 * Disable channel.
668 *
669 * Name and handle CAN NOT be NULL.
670 *
671 * Return 0 on success else a negative LTTng error code.
672 */
673 extern int lttng_disable_channel(struct lttng_handle *handle,
674 const char *name);
675
676 /*
677 * Calibrate LTTng overhead.
678 *
679 * The chan and handle params can not be NULL.
680 *
681 * Return 0 on success else a negative LTTng error code.
682 */
683 extern int lttng_calibrate(struct lttng_handle *handle,
684 struct lttng_calibrate *calibrate);
685
686 /*
687 * Set the default channel attributes for a specific domain and an allocated
688 * lttng_channel_attr pointer.
689 *
690 * If one or both arguments are NULL, nothing happens.
691 */
692 extern void lttng_channel_set_default_attr(struct lttng_domain *domain,
693 struct lttng_channel_attr *attr);
694
695 /*
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.
700 *
701 * Default port are 5342 and 5343 respectively for control and data which uses
702 * the TCP protocol.
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.
718 */
719 extern int lttng_set_consumer_url(struct lttng_handle *handle,
720 const char *control_url, const char *data_url);
721
722 /*
723 * Enable the consumer for a session and domain.
724 */
725 extern LTTNG_DEPRECATED("This call is now obsolete.")
726 int lttng_enable_consumer(struct lttng_handle *handle);
727
728 /*
729 * Disable consumer for a session and domain.
730 */
731 extern LTTNG_DEPRECATED("This call is now obsolete.")
732 int lttng_disable_consumer(struct lttng_handle *handle);
733
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().
743 *
744 * Please see lttng-health-check(3) man page for more information.
745 */
746 extern LTTNG_DEPRECATED("This call is now obsolete.")
747 int lttng_health_check(enum lttng_health_component c);
748
749 /*
750 * For a given session name, this call checks if the data is ready to be read
751 * or is still being extracted by the consumer(s) (pending) hence not ready to
752 * be used by any readers.
753 *
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().
758 */
759 extern int lttng_data_pending(const char *session_name);
760
761 #ifdef __cplusplus
762 }
763 #endif
764
765 #endif /* LTTNG_H */
This page took 0.072072 seconds and 4 git commands to generate.