2 * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
3 * Copyright (C) 2016 Jérémie Galarneau <jeremie.galarneau@efficios.com>
5 * SPDX-License-Identifier: LGPL-2.1-only
16 #include <lttng/handle.h>
17 #include <lttng/lttng-export.h>
18 #include <lttng/userspace-probe.h>
22 \ref api-rer-conds-inst-pt-type "Instrumentation type condition"
27 enum lttng_event_type
{
28 /// Match LTTng kernel tracepoint and Linux system call events.
31 /// Match LTTng tracepoint or Java/Python logging events.
32 LTTNG_EVENT_TRACEPOINT
= 0,
36 <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>
39 LTTNG_EVENT_PROBE
= 1,
43 <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>
46 LTTNG_EVENT_FUNCTION
= 2,
49 LTTNG_EVENT_FUNCTION_ENTRY
= 3,
53 /// Match Linux system call events.
54 LTTNG_EVENT_SYSCALL
= 5,
58 <a href="https://lwn.net/Articles/499190/">uprobe</a>
61 LTTNG_EVENT_USERSPACE_PROBE
= 6,
67 \ref api-rer-conds-ll "instrumentation point log level condition"
68 of a recording event rule.
72 In the enumerator descriptions below, consider that \lt_var{LL} is the
73 log level value of the condition, that is, the value of the
74 lttng_event::loglevel member when the lttng_event::loglevel_type member
75 is the described enumerator.
77 Depending on the \lt_obj_domain of the recording event rule, \lt_var{LL}
78 is one of the enumerators of #lttng_loglevel, #lttng_loglevel_jul,
79 #lttng_loglevel_log4j, or #lttng_loglevel_python.
81 enum lttng_loglevel_type
{
82 /// Match events regardless of their log level.
83 LTTNG_EVENT_LOGLEVEL_ALL
= 0,
86 Match events with a log level that's at least as severe as
89 LTTNG_EVENT_LOGLEVEL_RANGE
= 1,
91 /// Match events with a log level that's exacty \lt_var{LL}.
92 LTTNG_EVENT_LOGLEVEL_SINGLE
= 2,
98 \ref api-rer-conds-ll "instrumentation point log level condition"=
100 \link #LTTNG_DOMAIN_UST user space\endlink tracepoint
101 recording event rule.
105 @sa #lttng_loglevel_type --
106 Operand of the log level condition of a recording event rule.
108 enum lttng_loglevel
{
109 /// System is unusable.
110 LTTNG_LOGLEVEL_EMERG
= 0,
112 /// Action must be taken immediately.
113 LTTNG_LOGLEVEL_ALERT
= 1,
115 /// Critical conditions.
116 LTTNG_LOGLEVEL_CRIT
= 2,
118 /// Error conditions.
119 LTTNG_LOGLEVEL_ERR
= 3,
121 /// Warning conditions.
122 LTTNG_LOGLEVEL_WARNING
= 4,
124 /// Normal, but significant, condition.
125 LTTNG_LOGLEVEL_NOTICE
= 5,
127 /// Informational message.
128 LTTNG_LOGLEVEL_INFO
= 6,
130 /// Debug information with system-level scope (set of programs).
131 LTTNG_LOGLEVEL_DEBUG_SYSTEM
= 7,
133 /// Debug information with program-level scope (set of processes).
134 LTTNG_LOGLEVEL_DEBUG_PROGRAM
= 8,
136 /// Debug information with process-level scope (set of modules).
137 LTTNG_LOGLEVEL_DEBUG_PROCESS
= 9,
140 Debug information with module (executable/library) scope
143 LTTNG_LOGLEVEL_DEBUG_MODULE
= 10,
145 /// Debug information with compilation unit scope (set of functions).
146 LTTNG_LOGLEVEL_DEBUG_UNIT
= 11,
148 /// Debug information with function-level scope.
149 LTTNG_LOGLEVEL_DEBUG_FUNCTION
= 12,
151 /// Debug information with line-level scope.
152 LTTNG_LOGLEVEL_DEBUG_LINE
= 13,
154 /// Debug-level message.
155 LTTNG_LOGLEVEL_DEBUG
= 14,
161 \ref api-rer-conds-ll "instrumentation point log level condition"
163 \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink
164 recording event rule.
168 @sa #lttng_loglevel_type --
169 Operand of the log level condition of a recording event rule.
171 enum lttng_loglevel_jul
{
172 /// Logging turned off.
173 LTTNG_LOGLEVEL_JUL_OFF
= INT32_MAX
,
176 LTTNG_LOGLEVEL_JUL_SEVERE
= 1000,
178 /// Potential problem.
179 LTTNG_LOGLEVEL_JUL_WARNING
= 900,
181 /// Informational messages.
182 LTTNG_LOGLEVEL_JUL_INFO
= 800,
184 /// Static configuration messages.
185 LTTNG_LOGLEVEL_JUL_CONFIG
= 700,
187 /// Tracing information.
188 LTTNG_LOGLEVEL_JUL_FINE
= 500,
190 /// Fairly detailed tracing message.
191 LTTNG_LOGLEVEL_JUL_FINER
= 400,
193 /// Highly detailed tracing message.
194 LTTNG_LOGLEVEL_JUL_FINEST
= 300,
197 LTTNG_LOGLEVEL_JUL_ALL
= INT32_MIN
,
203 \ref api-rer-conds-ll "instrumentation point log level condition"
205 \link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink
206 recording event rule.
210 @sa #lttng_loglevel_type --
211 Operand of the log level condition of a recording event rule.
213 enum lttng_loglevel_log4j
{
214 /// Logging turned off.
215 LTTNG_LOGLEVEL_LOG4J_OFF
= INT32_MAX
,
218 Very severe error events that will presumably lead the
219 application to abort.
221 LTTNG_LOGLEVEL_LOG4J_FATAL
= 50000,
224 Error events that might still allow the application to continue
227 LTTNG_LOGLEVEL_LOG4J_ERROR
= 40000,
229 /// Potentially harmful situations.
230 LTTNG_LOGLEVEL_LOG4J_WARN
= 30000,
233 Informational messages that highlight the progress of the
234 application at coarse-grained level.
236 LTTNG_LOGLEVEL_LOG4J_INFO
= 20000,
239 Fine-grained informational events that are most useful to debug
242 LTTNG_LOGLEVEL_LOG4J_DEBUG
= 10000,
245 Finer-grained informational events than the
246 #LTTNG_LOGLEVEL_LOG4J_DEBUG level.
248 LTTNG_LOGLEVEL_LOG4J_TRACE
= 5000,
250 /// All levels, including custom levels.
251 LTTNG_LOGLEVEL_LOG4J_ALL
= INT32_MIN
,
257 \ref api-rer-conds-ll "instrumentation point log level condition"
259 \link #LTTNG_DOMAIN_PYTHON Python\endlink
260 recording event rule.
264 @sa #lttng_loglevel_type --
265 Operand of the log level condition of a recording event rule.
267 enum lttng_loglevel_python
{
269 LTTNG_LOGLEVEL_PYTHON_CRITICAL
= 50,
272 LTTNG_LOGLEVEL_PYTHON_ERROR
= 40,
275 LTTNG_LOGLEVEL_PYTHON_WARNING
= 30,
278 LTTNG_LOGLEVEL_PYTHON_INFO
= 20,
281 LTTNG_LOGLEVEL_PYTHON_DEBUG
= 10,
283 /// Logging turned off.
284 LTTNG_LOGLEVEL_PYTHON_NOTSET
= 0,
293 enum lttng_event_output
{
294 /// Use the \lt_man_gen{splice,2} system call.
295 LTTNG_EVENT_SPLICE
= 0,
297 /// Use the \lt_man_gen{mmap,2} system call.
298 LTTNG_EVENT_MMAP
= 1,
307 The following table indicates, for each enumerator, its description, for
308 which \lt_obj_domain it's available, and the
309 data type and the name of the resulting context field in traces.
319 <td>#LTTNG_EVENT_CONTEXT_PID
321 <td>#LTTNG_DOMAIN_KERNEL
325 <td>#LTTNG_EVENT_CONTEXT_PROCNAME
327 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
329 <td><code>procname</code>
331 <td>#LTTNG_EVENT_CONTEXT_PRIO
333 <td>#LTTNG_DOMAIN_KERNEL
335 <td><code>prio</code>
337 <td>#LTTNG_EVENT_CONTEXT_NICE
338 <td>Nice value of the process
339 <td>#LTTNG_DOMAIN_KERNEL
341 <td><code>nice</code>
343 <td>#LTTNG_EVENT_CONTEXT_VPID
344 <td>Virtual process ID
345 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
347 <td><code>vpid</code>
349 <td>#LTTNG_EVENT_CONTEXT_TID
351 <td>#LTTNG_DOMAIN_KERNEL
355 <td>#LTTNG_EVENT_CONTEXT_VTID
356 <td>Virtual thread ID
357 <td>#LTTNG_DOMAIN_KERNEL
359 <td><code>vtid</code>
361 <td>#LTTNG_EVENT_CONTEXT_PPID
362 <td>ID of the parent process
363 <td>#LTTNG_DOMAIN_KERNEL
365 <td><code>ppid</code>
367 <td>#LTTNG_EVENT_CONTEXT_VPPID
368 <td>Virtual ID of the parent process
369 <td>#LTTNG_DOMAIN_KERNEL
371 <td><code>vppid</code>
373 <td>#LTTNG_EVENT_CONTEXT_PTHREAD_ID
375 <td>#LTTNG_DOMAIN_KERNEL
377 <td><code>pthread_id</code>
379 <td>#LTTNG_EVENT_CONTEXT_HOSTNAME
381 <td>#LTTNG_DOMAIN_KERNEL
383 <td><code>hostname</code>
385 <td>#LTTNG_EVENT_CONTEXT_IP
386 <td>Instruction pointer
387 <td>#LTTNG_DOMAIN_UST
391 <td>#LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER
393 Per-CPU perf counter.
395 If the lttng_event_context::ctx member of an #lttng_event_context
396 structure is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER, then the
397 lttng_event_context::lttng_event_context_u::perf_counter member
398 of lttng_event_context::u selects a specific per-CPU perf counter.
399 <td>#LTTNG_DOMAIN_KERNEL
401 <td>Depends on the selected perf counter
403 <td>#LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER
405 Per-thread perf counter.
407 If the lttng_event_context::ctx member of an #lttng_event_context
408 structure is #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the
409 lttng_event_context::lttng_event_context_u::perf_counter member
410 of lttng_event_context::u selects a specific per-thread
412 <td>#LTTNG_DOMAIN_UST
414 <td>Depends on the selected perf counter
416 <td>#LTTNG_EVENT_CONTEXT_APP_CONTEXT
418 Application-specific context.
420 If the lttng_event_context::ctx member of an #lttng_event_context
421 structure is #LTTNG_EVENT_CONTEXT_APP_CONTEXT, then the
422 lttng_event_context::lttng_event_context_u::app_ctx member of
423 of lttng_event_context::u selects
424 a specific application-specific context.
425 <td>#LTTNG_DOMAIN_JUL or #LTTNG_DOMAIN_LOG4J
426 <td>Integer or string
427 <td>Depends on the selected application-specific context
429 <td>#LTTNG_EVENT_CONTEXT_INTERRUPTIBLE
430 <td>Whether or not the process is interruptible
431 <td>#LTTNG_DOMAIN_KERNEL
433 <td><code>interruptible</code>
435 <td>#LTTNG_EVENT_CONTEXT_PREEMPTIBLE
436 <td>Whether or not the process is preemptible
437 <td>#LTTNG_DOMAIN_KERNEL
439 <td><code>preemptible</code>
441 <td>#LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE
442 <td>Whether or not the process needs a reschedule
443 <td>#LTTNG_DOMAIN_KERNEL
445 <td><code>need_reschedule</code>
447 <td>#LTTNG_EVENT_CONTEXT_MIGRATABLE
448 <td>Whether or not the process is migratable
449 <td>#LTTNG_DOMAIN_KERNEL
451 <td><code>migratable</code>
453 <td>#LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL
454 <td>Linux kernel call stack
455 <td>#LTTNG_DOMAIN_KERNEL
456 <td>Dynamic-length array of integers (instruction pointers)
457 <td><code>callstack_kernel</code>
459 <td>#LTTNG_EVENT_CONTEXT_CALLSTACK_USER
461 User space call stack.
463 Only supported on IA-32 and x86-64 architectures.
464 <td>#LTTNG_DOMAIN_KERNEL
465 <td>Dynamic-length array of integers (instruction pointers)
466 <td><code>callstack_user</code>
468 <td>#LTTNG_EVENT_CONTEXT_CGROUP_NS
470 Control group root directory namespace ID.
472 @sa \lt_man_gen{cgroup_namespaces,7}
473 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
475 <td><code>cgroup_ns</code>
477 <td>#LTTNG_EVENT_CONTEXT_IPC_NS
479 System V IPC and POSIX message queue namespace ID.
481 @sa \lt_man_gen{ipc_namespaces,7}
482 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
484 <td><code>ipc_ns</code>
486 <td>#LTTNG_EVENT_CONTEXT_MNT_NS
488 Mount point namespace ID.
490 @sa \lt_man_gen{mount_namespaces,7}
491 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
493 <td><code>mnt_ns</code>
495 <td>#LTTNG_EVENT_CONTEXT_NET_NS
497 Networking namespace ID.
499 @sa \lt_man_gen{network_namespaces,7}
500 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
502 <td><code>net_ns</code>
504 <td>#LTTNG_EVENT_CONTEXT_PID_NS
506 Process ID namespace ID.
508 @sa \lt_man_gen{pid_namespaces,7}
509 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
511 <td><code>pid_ns</code>
513 <td>#LTTNG_EVENT_CONTEXT_USER_NS
515 User and group ID namespace ID.
517 @sa \lt_man_gen{user_namespaces,7}
518 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
520 <td><code>user_ns</code>
522 <td>#LTTNG_EVENT_CONTEXT_UTS_NS
524 Hostname and NIS domain name namespace ID.
526 @sa \lt_man_gen{uts_namespaces,7}
527 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
529 <td><code>uts_ns</code>
531 <td>#LTTNG_EVENT_CONTEXT_TIME_NS
533 Boot and monotonic clock namespace ID.
535 @sa \lt_man_gen{time_namespaces,7}
536 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
538 <td><code>time_ns</code>
540 <td>#LTTNG_EVENT_CONTEXT_UID
542 <td>#LTTNG_DOMAIN_KERNEL
546 <td>#LTTNG_EVENT_CONTEXT_EUID
547 <td>Effective user ID
548 <td>#LTTNG_DOMAIN_KERNEL
550 <td><code>euid</code>
552 <td>#LTTNG_EVENT_CONTEXT_SUID
553 <td>Set owner user ID
554 <td>#LTTNG_DOMAIN_KERNEL
556 <td><code>suid</code>
558 <td>#LTTNG_EVENT_CONTEXT_GID
560 <td>#LTTNG_DOMAIN_KERNEL
564 <td>#LTTNG_EVENT_CONTEXT_EGID
565 <td>Effective group ID
566 <td>#LTTNG_DOMAIN_KERNEL
568 <td><code>egid</code>
570 <td>#LTTNG_EVENT_CONTEXT_SGID
571 <td>Set owner group ID
572 <td>#LTTNG_DOMAIN_KERNEL
574 <td><code>sgid</code>
576 <td>#LTTNG_EVENT_CONTEXT_VUID
578 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
580 <td><code>vuid</code>
582 <td>#LTTNG_EVENT_CONTEXT_VEUID
583 <td>Virtual effective user ID
584 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
586 <td><code>veuid</code>
588 <td>#LTTNG_EVENT_CONTEXT_VSUID
589 <td>Virtual set owner user ID
590 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
592 <td><code>vsuid</code>
594 <td>#LTTNG_EVENT_CONTEXT_VGID
596 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
598 <td><code>vgid</code>
600 <td>#LTTNG_EVENT_CONTEXT_VEGID
601 <td>Virtual effective group ID
602 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
604 <td><code>vegid</code>
606 <td>#LTTNG_EVENT_CONTEXT_VSGID
607 <td>Virtual set owner group ID
608 <td>#LTTNG_DOMAIN_KERNEL and #LTTNG_DOMAIN_UST
610 <td><code>vsgid</code>
615 enum lttng_event_context_type
{
617 LTTNG_EVENT_CONTEXT_PID
= 0,
619 /// @cond BACKWARD_COMPAT_EVENT_CTX_TYPES
620 LTTNG_EVENT_CONTEXT_PERF_COUNTER
= 1, /* Backward compat. */
624 LTTNG_EVENT_CONTEXT_PROCNAME
= 2,
626 /// Process priority.
627 LTTNG_EVENT_CONTEXT_PRIO
= 3,
629 /// Nice value of the process.
630 LTTNG_EVENT_CONTEXT_NICE
= 4,
632 /// Virtual process ID.
633 LTTNG_EVENT_CONTEXT_VPID
= 5,
636 LTTNG_EVENT_CONTEXT_TID
= 6,
638 /// Virtual thread ID.
639 LTTNG_EVENT_CONTEXT_VTID
= 7,
641 /// ID of the parent process.
642 LTTNG_EVENT_CONTEXT_PPID
= 8,
644 /// Virtual ID of the parent process.
645 LTTNG_EVENT_CONTEXT_VPPID
= 9,
648 LTTNG_EVENT_CONTEXT_PTHREAD_ID
= 10,
651 LTTNG_EVENT_CONTEXT_HOSTNAME
= 11,
653 /// Instruction pointer.
654 LTTNG_EVENT_CONTEXT_IP
= 12,
656 /// Per-CPU perf counter.
657 LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER
= 13,
659 /// Per-thread perf counter.
660 LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER
= 14,
662 /// Application-specific context.
663 LTTNG_EVENT_CONTEXT_APP_CONTEXT
= 15,
665 /// Whether or not the process is interruptible.
666 LTTNG_EVENT_CONTEXT_INTERRUPTIBLE
= 16,
668 /// Whether or not the process is preemptible.
669 LTTNG_EVENT_CONTEXT_PREEMPTIBLE
= 17,
671 /// Whether or not the process needs a reschedule.
672 LTTNG_EVENT_CONTEXT_NEED_RESCHEDULE
= 18,
674 /// Whether or not the process is migratable.
675 LTTNG_EVENT_CONTEXT_MIGRATABLE
= 19,
677 /// Linux kernel call stack.
678 LTTNG_EVENT_CONTEXT_CALLSTACK_KERNEL
= 20,
680 /// User space call stack.
681 LTTNG_EVENT_CONTEXT_CALLSTACK_USER
= 21,
683 /// Control group root directory namespace ID.
684 LTTNG_EVENT_CONTEXT_CGROUP_NS
= 22,
686 /// System V IPC and POSIX message queue namespace ID.
687 LTTNG_EVENT_CONTEXT_IPC_NS
= 23,
689 /// Mount point namespace ID.
690 LTTNG_EVENT_CONTEXT_MNT_NS
= 24,
692 /// Networking namespace ID.
693 LTTNG_EVENT_CONTEXT_NET_NS
= 25,
695 /// Process ID namespace ID.
696 LTTNG_EVENT_CONTEXT_PID_NS
= 26,
698 /// User and group ID namespace ID.
699 LTTNG_EVENT_CONTEXT_USER_NS
= 27,
701 /// Hostname and NIS domain name namespace ID.
702 LTTNG_EVENT_CONTEXT_UTS_NS
= 28,
704 /// User ID namespace ID.
705 LTTNG_EVENT_CONTEXT_UID
= 29,
707 /// Effective user ID namespace ID.
708 LTTNG_EVENT_CONTEXT_EUID
= 30,
710 /// Set owner user ID namespace ID.
711 LTTNG_EVENT_CONTEXT_SUID
= 31,
713 /// Group ID namespace ID.
714 LTTNG_EVENT_CONTEXT_GID
= 32,
716 /// Effective group ID namespace ID.
717 LTTNG_EVENT_CONTEXT_EGID
= 33,
719 /// Set owner group ID namespace ID.
720 LTTNG_EVENT_CONTEXT_SGID
= 34,
722 /// Virtual user ID namespace ID.
723 LTTNG_EVENT_CONTEXT_VUID
= 35,
725 /// Virtual effective user ID namespace ID.
726 LTTNG_EVENT_CONTEXT_VEUID
= 36,
728 /// Virtual set owner user ID namespace ID.
729 LTTNG_EVENT_CONTEXT_VSUID
= 37,
731 /// Virtual group ID namespace ID.
732 LTTNG_EVENT_CONTEXT_VGID
= 38,
734 /// Virtual effective group ID namespace ID.
735 LTTNG_EVENT_CONTEXT_VEGID
= 39,
737 /// Virtual set owner group ID namespace ID.
738 LTTNG_EVENT_CONTEXT_VSGID
= 40,
740 /// Boot and monotonic clock namespace ID.
741 LTTNG_EVENT_CONTEXT_TIME_NS
= 41,
746 LTTng tracepoint field data type
747 (type of the lttng_event_field::type member).
751 enum lttng_event_field_type
{
753 LTTNG_EVENT_FIELD_OTHER
= 0,
756 LTTNG_EVENT_FIELD_INTEGER
= 1,
759 LTTNG_EVENT_FIELD_ENUM
= 2,
761 /// Floating point number.
762 LTTNG_EVENT_FIELD_FLOAT
= 3,
765 LTTNG_EVENT_FIELD_STRING
= 4,
770 \ref api-rer-inst-pt-descr "Instrumentation point descriptor"
771 flag (type of the lttng_event::flags member).
775 enum lttng_event_flag
{
778 32-bit Linux system call.
780 Only valid when the lttng_event::type member is
781 #LTTNG_EVENT_SYSCALL.
783 LTTNG_EVENT_FLAG_SYSCALL_32
= (1U << 0),
787 64-bit Linux system call.
789 Only valid when the lttng_event::type member is
790 #LTTNG_EVENT_SYSCALL.
792 LTTNG_EVENT_FLAG_SYSCALL_64
= (1U << 1),
795 #define LTTNG_PERF_EVENT_PADDING1 16
799 perf counter context field descriptor.
803 If the lttng_event_context::ctx member of an #lttng_event_context
804 structure is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or
805 #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then the
806 lttng_event_context::lttng_event_context_u::perf_counter member
807 of lttng_event_context::u selects a specific perf counter.
809 You must initialize such a structure to zeros before setting its members
810 and using it, for example:
813 struct lttng_event_perf_counter_ctx perf_counter_ctx;
815 memset(&perf_counter_ctx, 0, sizeof(perf_counter_ctx));
818 struct lttng_event_perf_counter_ctx
{
821 perf counter type ID.
836 <td>Hardware cache counter
839 <td>Performance Monitoring Unit (PMU) counter
847 perf counter configuration.
849 Depending on the lttng_event_perf_counter_ctx::type member:
852 <dt>0 (hardware counter)
873 <td>Branch instructions
882 <td>Stalled cycles (front end)
885 <td>Stalled cycles (back end)
889 <dt>1 (software counter)
913 <td>Minor page faults
916 <td>Major page faults
926 <dt>3 (hardware cache counter)
928 The result of a bitwise OR operation between a cache ID,
929 an operation ID, and a result ID, as follows:
947 href="https://en.wikipedia.org/wiki/Translation_lookaside_buffer">TLB</a> <tr> <td>4
951 <td>Branch prediction unit (BPU)
985 @sa \lt_man_gen{perf-record,1}
990 /// Context field name.
991 char name
[LTTNG_SYMBOL_NAME_LEN
];
993 char padding
[LTTNG_PERF_EVENT_PADDING1
];
996 #define LTTNG_EVENT_CONTEXT_PADDING1 16
997 #define LTTNG_EVENT_CONTEXT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
1001 Context field descriptor.
1003 @ingroup api_channel
1005 Such a structure describes a context field to be recorded within all the
1006 \ref api_rer "event records" of a given \lt_obj_channel (see
1007 lttng_add_context()).
1009 You must initialize such a structure to zeros before setting its members
1010 and using it, for example:
1013 struct lttng_event_context ctx;
1015 memset(&ctx, 0, sizeof(ctx));
1018 struct lttng_event_context
{
1023 Some types have a \lt_obj_domain
1026 If this member has the value
1027 #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or
1028 #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER, then you must also set
1029 the lttng_event_context::lttng_event_context_u::perf_counter
1030 member of lttng_event_context::u.
1032 If this member has the value #LTTNG_EVENT_CONTEXT_APP_CONTEXT,
1033 then you must also set the
1034 lttng_event_context::lttng_event_context_u::app_ctx member
1035 of lttng_event_context::u.
1037 enum lttng_event_context_type ctx
;
1039 char padding
[LTTNG_EVENT_CONTEXT_PADDING1
];
1043 perf counter or application-specific context field
1046 @ingroup api_channel
1048 union lttng_event_context_u
{
1051 perf counter context field descriptor.
1053 Only used when the lttng_event_context::ctx member
1054 is #LTTNG_EVENT_CONTEXT_PERF_CPU_COUNTER or
1055 #LTTNG_EVENT_CONTEXT_PERF_THREAD_COUNTER.
1057 struct lttng_event_perf_counter_ctx perf_counter
;
1061 char *provider_name
;
1069 Application-specific context field descriptor.
1071 Only used when the lttng_event_context::ctx member
1072 is #LTTNG_EVENT_CONTEXT_APP_CONTEXT.
1076 char padding
[LTTNG_EVENT_CONTEXT_PADDING2
];
1079 /// perf counter or application-specific context field descriptor.
1083 #define LTTNG_EVENT_PROBE_PADDING1 16
1087 Legacy Linux kprobe/kretprobe location.
1091 Such a structure indicates the location of a Linux kprobe/kretprobe for
1092 a \lt_obj_rer having such an instrumentation point type.
1094 You must initialize such a structure to zeros before setting its members
1095 and using it, for example:
1098 struct lttng_event_probe_attr loc;
1100 memset(&loc, 0, sizeof(loc));
1103 Set either lttng_event_probe_attr::addr or
1104 lttng_event_probe_attr::symbol_name and lttng_event_probe_attr::offset.
1106 @sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
1108 struct lttng_event_probe_attr
{
1111 kprobe/kretprobe address.
1113 If this member is not 0, then
1114 lttng_event_probe_attr::symbol_name must be an empty string.
1120 kprobe/kretprobe address offset from the symbol named
1121 lttng_event_probe_attr::symbol_name.
1127 kprobe/kretprobe symbol name.
1129 The actual kprobe/kretprobe address is the address of the named
1130 symbol plus the value of lttng_event_probe_attr::offset.
1132 If this member is not an empty string, then
1133 lttng_event_probe_attr::addr must be 0.
1135 char symbol_name
[LTTNG_SYMBOL_NAME_LEN
];
1137 char padding
[LTTNG_EVENT_PROBE_PADDING1
];
1143 * The structures should be initialized to zero before use.
1145 #define LTTNG_EVENT_FUNCTION_PADDING1 16
1146 struct lttng_event_function_attr
{
1147 char symbol_name
[LTTNG_SYMBOL_NAME_LEN
];
1149 char padding
[LTTNG_EVENT_FUNCTION_PADDING1
];
1153 * Generic lttng event
1155 * The structures should be initialized to zero before use.
1157 #define LTTNG_EVENT_PADDING1 12
1158 #define LTTNG_EVENT_PADDING2 LTTNG_SYMBOL_NAME_LEN + 32
1162 \lt_obj_c_rer descriptor.
1166 Such a structure describes a recording event rule. More specifically,
1167 it describes the \ref api-rer-conds "conditions" of a recording
1170 lttng_list_events() sets a pointer to an array of all the recording
1171 event rule descriptors of a given \lt_obj_channel.
1174 \anchor api-rer-inst-pt-descr lttng_list_tracepoints()
1175 and lttng_list_syscalls() also set
1176 a pointer to an array of instances of this structure. In this
1177 context, the #lttng_event structure is named
1178 \"<em>instrumentation point descriptor</em>\".
1180 lttng_enable_event(), lttng_enable_event_with_filter(), and
1181 lttng_enable_event_with_exclusions() expect such a structure to create
1182 or enable a recording event rule.
1184 Most properties are members of the structure itself, but the
1185 following ones have their own dedicated accessors:
1189 Linux uprobe location (when the lttng_event::type member is
1190 #LTTNG_EVENT_USERSPACE_PROBE)
1192 - lttng_event_get_userspace_probe_location()
1193 - lttng_event_set_userspace_probe_location()
1195 <dt>\ref api-rer-conds-event-name "Event name" exclusion patterns
1197 lttng_event_get_exclusion_name()
1199 <dt>\ref api-rer-conds-filter "Event payload and context filter" expression
1201 lttng_event_get_filter_expression()
1204 Create an empty recording event rule descriptor with
1205 lttng_event_create().
1207 \anchor api-rer-valid-event-struct A \em valid #lttng_event structure
1208 satisfies the following constraints:
1210 - If the lttng_event::type member is #LTTNG_EVENT_PROBE or
1211 #LTTNG_EVENT_FUNCTION, then the lttng_event::lttng_event_attr_u::probe
1212 member of lttng_event::attr is valid according to the
1213 documentation of #lttng_event_probe_attr.
1215 - If the lttng_event::type member is #LTTNG_EVENT_USERSPACE_PROBE, then
1216 the recording event rule descriptor has a Linux uprobe location
1217 (you called lttng_event_set_userspace_probe_location() on it to
1220 Destroy a recording event rule descriptor with lttng_event_destroy().
1222 struct lttng_event
{
1224 /// \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
1225 enum lttng_event_type type
;
1229 @brief \ref api-rer-conds-event-name "Event name" pattern
1232 If empty, lttng_enable_event(),
1233 lttng_enable_event_with_filter(), and
1234 lttng_enable_event_with_exclusions() use <code>*</code> (match
1235 events with any name).
1237 If the lttng_event::type member is #LTTNG_EVENT_PROBE,
1238 #LTTNG_EVENT_FUNCTION, or #LTTNG_EVENT_USERSPACE_PROBE, then
1239 this member is actually the name of the created Linux
1240 kprobe/kretprobe/uprobe instrumentation point (future event
1243 If this structure is an
1244 \ref api-rer-inst-pt-descr "instrumentation point descriptor",
1245 then this member is the name of the LTTng tracepoint, Linux
1246 system call, or Java/Python logger.
1248 char name
[LTTNG_SYMBOL_NAME_LEN
];
1254 \ref api-rer-conds-ll "instrumentation point log level condition".
1256 enum lttng_loglevel_type loglevel_type
;
1261 \ref api-rer-conds-ll "instrumentation point log level condition".
1263 This member must be one of the enumerators of
1264 #lttng_loglevel, #lttng_loglevel_jul, #lttng_loglevel_log4j, or
1265 #lttng_loglevel_python, depending on the
1266 \lt_obj_domain when you call lttng_enable_event(),
1267 lttng_enable_event_with_filter(), or
1268 lttng_enable_event_with_exclusions().
1270 If this structure is an
1271 \ref api-rer-inst-pt-descr "instrumentation point descriptor",
1272 then this member is the log level of the LTTng tracepoint or
1280 1 if this recording event rule is enabled, or 0 otherwise.
1282 This is a read-only member.
1284 @sa lttng_enable_event() --
1285 Creates or enables a recording event rule.
1286 @sa lttng_disable_event_ext() --
1287 Disables a recording event rule.
1289 int32_t enabled
; /* Does not apply: -1 */
1294 ID of the process which offers the instrumentation point
1295 described by this structure.
1297 This is a read-only member.
1299 This member is \em not part of a recording event rule.
1306 1 if the recording event rule described by this has an
1307 \ref api-rer-conds-filter "event payload and context filter"
1308 expression, or 0 otherwise.
1310 This is a read-only member: use the \lt_p{filter_expr} parameter
1311 of lttng_enable_event_with_filter() or
1312 lttng_enable_event_with_exclusions() when you create a
1313 recording event rule to set an event payload and context
1316 If this member is 1, then get the actual filter expression
1317 string with lttng_event_get_filter_expression().
1319 unsigned char filter
;
1324 1 if the recording event rule described by this has
1325 \ref api-rer-conds-event-name "event name" exclusion
1326 patterns (part of the event name condition), or 0 otherwise.
1328 This is a read-only member: use the
1329 \lt_p{event_name_exclusion_count} and
1330 \lt_p{event_name_exclusions} parameters of
1331 lttng_enable_event_with_exclusions() when you create a recording
1332 event rule to set event name exclusion patterns.
1334 If this member is 1, then get the actual event name exclusion
1335 patterns with lttng_event_get_exclusion_name_count() and
1336 lttng_event_get_exclusion_name().
1338 unsigned char exclusion
;
1346 \ref api-rer-inst-pt-descr "Instrumentation point descriptor"
1349 This is a read-only member.
1351 This member is \em not part of a recording event rule.
1353 enum lttng_event_flag flags
;
1367 Linux kprobe/kretprobe recording event rule configuration.
1371 union lttng_event_attr_u
{
1374 Linux kprobe/kretprobe location.
1376 Only valid when the lttng_event::type member is
1377 #LTTNG_EVENT_PROBE or #LTTNG_EVENT_FUNCTION.
1379 struct lttng_event_probe_attr probe
;
1381 struct lttng_event_function_attr ftrace
;
1383 char padding
[LTTNG_EVENT_PADDING2
];
1388 Linux kprobe/kretprobe recording event rule configuration.
1390 Only valid when the lttng_event::type member is
1391 #LTTNG_EVENT_PROBE or #LTTNG_EVENT_FUNCTION.
1396 #define LTTNG_EVENT_FIELD_PADDING LTTNG_SYMBOL_NAME_LEN + 32
1400 LTTng tracepoint field description.
1402 @ingroup api_inst_pt
1404 lttng_list_tracepoint_fields() sets a pointer to an array of all the
1405 tracepoint field descriptions of a given \lt_obj_domain.
1407 struct lttng_event_field
{
1409 char field_name
[LTTNG_SYMBOL_NAME_LEN
];
1411 /// Field data type.
1412 enum lttng_event_field_type type
;
1414 char padding
[LTTNG_EVENT_FIELD_PADDING
];
1418 \ref api-rer-inst-pt-descr "Descriptor" of the tracepoint
1419 which contains this field.
1421 struct lttng_event event
;
1425 0 if LTTng writes this field to an event record, or 1
1433 Sets \lt_p{*event_rules} to the descriptors of the
1434 \lt_obj_rers of the \lt_obj_channel named \lt_p{channel_name}
1435 within the recording session handle \lt_p{handle}.
1437 @ingroup api_channel
1440 Recording session handle which contains the name of the
1441 recording session and the summary
1442 of the \lt_obj_domain which own the channel (named
1443 \lt_p{channel_name}) of which to get the recording event rule
1445 @param[in] channel_name
1446 Name of the channel, within \lt_p{handle}, of which to get all the
1447 recording event rule descriptors.
1448 @param[out] event_rules
1450 <strong>On success</strong>, this function sets \lt_p{*event_rules}
1451 to the recording event rule descriptors.
1453 Free \lt_p{*event_rules} with <code>free()</code>.
1457 The number of items in \lt_p{*event_rules} on success, or a
1458 \em negative #lttng_error_code enumerator otherwise.
1461 @lt_pre_not_null{handle}
1462 @lt_pre_valid_c_str{handle->session_name}
1463 @lt_pre_sess_exists{handle->session_name}
1465 \lt_p{handle->domain} is valid as per the documentation of
1467 @lt_pre_not_null{channel_name}
1469 \lt_p{channel_name} names an existing channel within the recording
1470 session and tracing domain of \lt_p{handle}.
1471 @lt_pre_not_null{event_rules}
1473 LTTNG_EXPORT
extern int lttng_list_events(struct lttng_handle
*handle
,
1474 const char *channel_name
,
1475 struct lttng_event
**event_rules
);
1479 Creates and returns an empty recording event rule descriptor.
1483 After you create a recording event rule descriptor with this function,
1484 you can modify its properties and call
1485 lttng_enable_event_with_exclusions() to create and enable a recording
1490 New recording event rule descriptor.
1492 Destroy the returned recording event rule descriptor with
1493 lttng_event_destroy().
1496 @sa lttng_event_destroy() --
1497 Destroys a recording event rule descriptor.
1499 LTTNG_EXPORT
extern struct lttng_event
*lttng_event_create(void);
1503 Destroys the recording event rule descriptor \lt_p{event_rule}.
1508 This function doesn't destroy the recording event rule
1509 which \lt_p{event_rule} describes: you can't destroy a
1510 recording event rule.
1512 @param[in] event_rule
1514 Recording event rule descriptor to destroy.
1520 <strong>If not \c NULL</strong>, \lt_p{event_rule} was created with
1521 lttng_event_create().
1523 @sa lttng_event_create() --
1524 Creates an empty recording event rule descriptor.
1526 LTTNG_EXPORT
extern void lttng_event_destroy(struct lttng_event
*event_rule
);
1530 Sets \lt_p{*filter_expr} to the
1531 \ref api-rer-conds-filter "event payload and context filter"
1532 expression of the recording event rule described by
1537 @param[in] event_rule
1538 Descriptor of the recording event rule of which to get the event
1539 payload and context filter expression.
1540 @param[out] filter_expr
1542 <strong>On success</strong>, this function sets \lt_p{*filter_expr}
1547 If \lt_p{event_rule} has an event payload and context filter
1550 The event payload and context filter
1551 expression of \lt_p{event_rule}.
1553 \lt_p{*filter_expr} remains valid as long as \lt_p{event_rule}
1554 exists and you don't modify it.
1562 0 on success, or a \em negative #lttng_error_code enumerator
1565 @lt_pre_not_null{event_rule}
1566 @lt_pre_not_null{filter_expr}
1568 @sa lttng_event::filter --
1569 Indicates whether or not a recording event rule has an event payload
1572 LTTNG_EXPORT
extern int lttng_event_get_filter_expression(struct lttng_event
*event_rule
,
1573 const char **filter_expr
);
1577 Returns the number of \ref api-rer-conds-event-name "event name"
1578 exclusion patterns of the recording
1579 event rule described by \lt_p{event_rule}.
1583 @param[in] event_rule
1584 Descriptor of the recording event rule of which to get the number
1585 of event name exclusion patterns.
1588 Number of event name exclusion patterns of \lt_p{event_rule}, or a
1589 \em negative #lttng_error_code enumerator otherwise.
1591 @lt_pre_not_null{event_rule}
1593 @sa lttng_event_get_exclusion_name() --
1594 Returns an event name exclusion pattern by index of a recording
1596 @sa lttng_event::exclusion --
1597 Indicates whether or not a recording event rule has event name
1600 LTTNG_EXPORT
extern int lttng_event_get_exclusion_name_count(struct lttng_event
*event_rule
);
1604 Sets \lt_p{*event_name_exclusion} to the
1605 \ref api-rer-conds-event-name "event name" exclusion
1606 pattern at index \lt_p{index} of the recording event rule described
1607 by \lt_p{event_rule}.
1611 @param[in] event_rule
1612 Descriptor of the recording event rule of which to get the event
1613 name exclusion pattern at index \lt_p{index}.
1615 Index of the event name exclusion pattern to get from
1617 @param[out] event_name_exclusion
1619 <strong>On success</strong>, this function sets
1620 \lt_p{*event_name_exclusion} to the event name exclusion pattern at
1621 index \lt_p{index} of
1624 \lt_p{*event_name_exclusion} remains valis as long as
1625 \lt_p{event_rule} exists and you don't modify it.
1629 0 on success, or a \em negative #lttng_error_code enumerator
1632 @lt_pre_not_null{event_rule}
1634 \lt_p{index} is less than the number of event name exclusion
1635 patterns (as returned by lttng_event_get_exclusion_name_count())
1636 of \lt_p{event_rule}.
1637 @lt_pre_not_null{event_name_exclusion}
1639 @sa lttng_event_get_exclusion_name_count() --
1640 Returns the number of event name exclusion patterns of a recording
1643 LTTNG_EXPORT
extern int lttng_event_get_exclusion_name(struct lttng_event
*event_rule
,
1645 const char **event_name_exclusion
);
1649 Returns the Linux uprobe location of the recording event rule
1650 described by \lt_p{event_rule}.
1654 @param[in] event_rule
1655 Descriptor of the recording event rule of which to get the
1656 Linux uprobe location.
1660 Linux uprobe location of the recording event rule described by
1661 \lt_p{event_rule}, or \c NULL if none.
1663 The returned location remains valid as long as \lt_p{event_rule}
1664 exists and you don't modify it.
1667 @lt_pre_not_null{event_rule}
1669 \lt_p{event_rule->type} (see lttng_event::type) is
1670 #LTTNG_EVENT_USERSPACE_PROBE.
1672 @sa lttng_event_set_userspace_probe_location() --
1673 Sets the Linux uprobe location of a recording event rule.
1674 @sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
1676 LTTNG_EXPORT
extern const struct lttng_userspace_probe_location
*
1677 lttng_event_get_userspace_probe_location(const struct lttng_event
*event_rule
);
1681 Sets the Linux uprobe location of the recording event rule described
1682 by \lt_p{event_rule} to \lt_p{location}.
1686 @param[in] event_rule
1687 Descriptor of the recording event rule of which to set the
1688 Linux uprobe location to \lt_p{location}.
1690 New Linux uprobe location of \lt_p{event_rule}.
1693 0 on success, or a \em negative #lttng_error_code enumerator
1696 @lt_pre_not_null{event_rule}
1698 \lt_p{event_rule} was created with lttng_event_create().
1700 \lt_p{event_rule->type} (see lttng_event::type) is
1701 #LTTNG_EVENT_USERSPACE_PROBE.
1702 @lt_pre_not_null{location}
1705 <strong>On success</strong>, \lt_p{*location} is invalid
1706 (its ownership is transfered to \lt_p{event_rule}).
1708 @sa lttng_event_get_userspace_probe_location() --
1709 Returns the Linux uprobe location of a recording event rule.
1710 @sa \ref api-rer-conds-inst-pt-type "Instrumentation point type condition".
1712 LTTNG_EXPORT
extern int
1713 lttng_event_set_userspace_probe_location(struct lttng_event
*event_rule
,
1714 struct lttng_userspace_probe_location
*location
);
1718 Sets \lt_p{*descrs} to the
1719 \ref api-rer-inst-pt-descr "descriptors" of the
1720 available LTTng tracepoints or Java/Python loggers for the
1721 \lt_obj_domain of \lt_p{handle}.
1723 @ingroup api_inst_pt
1727 Recording session handle which contains the summary of the
1728 \lt_obj_domain which offers the LTTng tracepoints or Java/Python
1729 loggers of which to get the descriptors.
1731 This function ignores \lt_p{handle->session_name}.
1735 <strong>On success</strong>, this function sets \lt_p{*descrs}
1736 to the descriptors of the available tracepoints or Java/Python
1737 loggers of \lt_p{handle}.
1739 Free \lt_p{*descrs} with <code>free()</code>.
1743 The number of items in \lt_p{*descrs} on success, or a \em
1744 negative #lttng_error_code enumerator otherwise.
1747 @lt_pre_not_null{handle}
1749 \lt_p{handle->domain} is valid as per the documentation of
1751 @lt_pre_not_null{descrs}
1753 @sa lttng_list_tracepoint_fields() --
1754 Returns all the field descriptions of all the available LTTng
1756 @sa lttng_list_syscalls() --
1757 Returns the descriptors of all the available Linux system calls.
1759 LTTNG_EXPORT
extern int lttng_list_tracepoints(struct lttng_handle
*handle
,
1760 struct lttng_event
**descrs
);
1764 Sets \lt_p{*fields} to the field descriptions of all the available
1765 LTTng tracepoints for the \lt_obj_domain of \lt_p{handle}.
1767 @ingroup api_inst_pt
1771 Recording session handle which contains the summary of the
1772 \lt_obj_domain which offers the LTTng tracepoints of which to get
1773 the field descriptions.
1775 This function ignores \lt_p{handle->session_name}.
1779 <strong>On success</strong>, this function sets \lt_p{*fields}
1780 to the descriptions of the available LTTng tracepoint fields of
1783 Each #lttng_event_field instance in \lt_p{*fields} contains a
1784 pointer to the \ref api-rer-inst-pt-descr "descriptor" of
1785 a tracepoint which contains the described field
1786 (lttng_event_field::event member).
1788 Free \lt_p{*fields} with <code>free()</code>.
1792 The number of items in \lt_p{*fields} on success, or a \em
1793 negative #lttng_error_code enumerator otherwise.
1796 @lt_pre_not_null{handle}
1798 \lt_p{handle->domain} is valid as per the documentation of
1800 @lt_pre_not_null{fields}
1802 @sa lttng_list_tracepoints() --
1803 Returns the descriptors of all the available LTTng tracepoints
1804 or Java/Python loggers.
1805 @sa lttng_list_syscalls() --
1806 Returns the descriptors of all the available Linux system calls.
1808 LTTNG_EXPORT
extern int lttng_list_tracepoint_fields(struct lttng_handle
*handle
,
1809 struct lttng_event_field
**fields
);
1813 Sets \lt_p{*descrs} to the
1814 \ref api-rer-inst-pt-descr "descriptors" of the
1815 available Linux system calls for the
1816 #LTTNG_DOMAIN_KERNEL tracing domain.
1818 @ingroup api_inst_pt
1822 <strong>On success</strong>, this function sets \lt_p{*descrs}
1823 to the available system calls.
1825 The #lttng_event instances of \lt_p{*descrs} have an
1826 lttng_event::flags member which indicates whether the described
1827 system call is 32-bit, 64-bit, or both.
1829 Free \lt_p{*descrs} with <code>free()</code>.
1833 The number of items in \lt_p{*descrs} on success, or a \em
1834 negative #lttng_error_code enumerator otherwise.
1837 @lt_pre_not_null{descrs}
1839 @sa lttng_list_tracepoint_fields() --
1840 Returns all the field descriptions of all the available LTTng
1842 @sa lttng_list_syscalls() --
1843 Returns the descriptors of all the available Linux system calls.
1845 LTTNG_EXPORT
extern int lttng_list_syscalls(struct lttng_event
**descrs
);
1849 Makes the future \ref api_rer "event records" of the
1850 \lt_obj_channel named \lt_p{channel_name} (or of a default channel
1851 or all the channels if \c NULL) within the
1852 \lt_obj_session and \lt_obj_domain of \lt_p{handle}
1853 have a context field described by \lt_p{context_field_descriptor}.
1855 @ingroup api_channel
1857 Context values (for example, the ID of the current process, the
1858 instruction pointer, or the hostname) are always available during
1859 tracing. This function makes LTTng record a specific context value as a
1860 field for each future event record of the selected channel(s).
1863 Recording session handle which contains the name of the recording
1864 session and the summary of the \lt_obj_domain which own the
1865 channel(s) to select.
1866 @param[in] context_field_descriptor
1867 Descriptor of the context field to add to each event record of
1868 the selected channel(s).
1869 @param[in] event_name
1870 Unused: must be \c NULL.
1871 @param[in] channel_name
1873 Name of the channel to select.
1879 If the recording session and tracing domain of
1880 \lt_p{handle} have no channels
1882 LTTng creates a new, default channel named \c channel0 within
1883 \lt_p{handle} which becomes the selected channel.
1887 LTTng selects all the channels of \lt_p{handle}.
1892 0 on success, or a \em negative #lttng_error_code enumerator
1896 @lt_pre_not_null{handle}
1897 @lt_pre_valid_c_str{handle->session_name}
1898 @lt_pre_sess_exists{handle->session_name}
1899 @lt_pre_sess_never_active{handle->session_name}
1901 \lt_p{handle->domain} is valid (you passed a
1902 \lt_obj_domain summary to
1903 lttng_create_handle() when you created \lt_p{handle}).
1905 \lt_p{context_field_descriptor} is valid according to the
1906 documentation of #lttng_event_context.
1908 \lt_p{event_name} is \c NULL.
1910 <strong>If not \c NULL</strong>, \lt_p{channel_name} names an
1911 existing channel within the recording session and tracing domain of
1914 LTTNG_EXPORT
extern int lttng_add_context(struct lttng_handle
*handle
,
1915 struct lttng_event_context
*context_field_descriptor
,
1916 const char *event_name
,
1917 const char *channel_name
);
1921 Alias of lttng_enable_event_with_exclusions() which passes the
1922 \ref api-rer-conds-filter "event payload and context filter"
1923 expression of \lt_p{event_rule}
1924 as the \lt_p{filter_expr} parameter and the
1925 \ref api-rer-conds-event-name "event name" exclusion patterns
1926 of \lt_p{event_rule} as the
1927 \lt_p{event_name_exclusion_count} and
1928 \lt_p{event_name_exclusions} parameters.
1932 This function is equivalent to:
1937 char **event_name_exclusions = NULL;
1938 const char *filter_expr = NULL;
1939 const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule);
1941 assert(event_name_exclusion_count >= 0);
1943 if (event_name_exclusion_count > 0) {
1944 event_name_exclusions = calloc(event_name_exclusion_count,
1945 sizeof(*event_name_exclusions));
1946 assert(event_name_exclusions);
1948 for (i = 0; i < event_name_exclusion_count; i++) {
1949 const char *event_name_exclusion;
1951 ret = lttng_event_get_exclusion_name(event_rule, (size_t) i,
1952 &event_name_exclusion);
1954 event_name_exclusions[i] = (char *) event_name_exclusion;
1958 ret = lttng_event_get_filter_expression(event_rule, &filter_expr);
1960 ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name,
1962 event_name_exclusion_count,
1963 event_name_exclusions);
1964 free(event_name_exclusions);
1968 LTTNG_EXPORT
extern int lttng_enable_event(struct lttng_handle
*handle
,
1969 struct lttng_event
*event_rule
,
1970 const char *channel_name
);
1974 Alias of lttng_enable_event_with_exclusions() which passes the
1975 the \ref api-rer-conds-event-name "event name" exclusion patterns
1976 of \lt_p{event_rule} as the
1977 \lt_p{event_name_exclusion_count} and
1978 \lt_p{event_name_exclusions} parameters.
1982 This function is equivalent to:
1987 char **event_name_exclusions = NULL;
1988 const char *filter_expr = NULL;
1989 const int event_name_exclusion_count = lttng_event_get_exclusion_name_count(event_rule);
1991 assert(event_name_exclusion_count >= 0);
1993 if (event_name_exclusion_count > 0) {
1994 event_name_exclusions = calloc(event_name_exclusion_count,
1995 sizeof(*event_name_exclusions));
1996 assert(event_name_exclusions);
1998 for (i = 0; i < event_name_exclusion_count; i++) {
1999 const char *event_name_exclusion;
2001 ret = lttng_event_get_exclusion_name(event_rule, (size_t) i,
2002 &event_name_exclusion);
2004 event_name_exclusions[i] = (char *) event_name_exclusion;
2008 ret = lttng_enable_event_with_exclusions(handle, event_rule, channel_name,
2010 event_name_exclusion_count,
2011 event_name_exclusions);
2012 free(event_name_exclusions);
2016 LTTNG_EXPORT
extern int lttng_enable_event_with_filter(struct lttng_handle
*handle
,
2017 struct lttng_event
*event_rule
,
2018 const char *channel_name
,
2019 const char *filter_expr
);
2023 Creates or enables a recording event rule
2024 described by \lt_p{event_rule}, having the
2025 \ref api-rer-conds-filter "event payload and context filter"
2026 expression \lt_p{filter_expr} and the
2027 \ref api-rer-conds-event-name "event name" exclusion patterns
2028 \lt_p{event_name_exclusions}, within
2029 the \lt_obj_channel named \lt_p{channel_name}
2030 (or within a default channel if \c NULL) within the recording
2031 session handle \lt_p{handle}.
2035 This function, depending on the
2036 \ref api-rer-conds-inst-pt-type "instrumentation point type",
2037 \ref api-rer-conds-event-name "event name",
2038 and \ref api-rer-conds-ll "log level" conditions of \lt_p{event_rule},
2039 as well as on \lt_p{filter_expr} and \lt_p{event_name_exclusions}:
2043 The conditions and parameters describe an existing recording event
2044 rule within the selected channel
2046 Enables the existing recording event rule.
2050 Creates and enables a new recording event rule within the
2054 If \lt_p{event_rule->type} is #LTTNG_EVENT_ALL and
2055 \lt_p{handle->domain.type} is #LTTNG_DOMAIN_KERNEL, then this
2056 function actually creates or enables two recording event rules: one with
2057 the #LTTNG_EVENT_TRACEPOINT type, and one with the #LTTNG_EVENT_SYSCALL
2061 Recording session handle which contains the name of the recording
2062 session and the summary of the \lt_obj_domain which own the selected
2064 @param[in] event_rule
2066 Descriptor of the recording event rule to create or enable.
2070 - Ignores any event payload and context filter
2071 expression within \lt_p{event_rule}: it always uses
2074 - Ignores any event name exclusion patterns within
2075 \lt_p{event_rule}: it always uses \lt_p{event_name_exclusions}.
2077 @param[in] channel_name
2079 Name of the channel, within \lt_p{handle}, to select (that is,
2080 containing the recording event rule to create or enable).
2082 If \c NULL, then this function uses \c channel0. If no channel named
2083 \c channel0 within \lt_p{handle} exists, then LTTng creates a new,
2084 default channel named as such and selects it before it creates the
2085 recording event rule described by \lt_p{event_rule}.
2087 @param[in] filter_expr
2089 Event payload and context filter expression of the recording
2090 event rule to create or enable.
2092 <strong>If \c NULL</strong>, the created or enabled recording event
2093 rule has no event payload and context filter expression.
2095 This parameter, even when \c NULL, overrides any existing
2096 event payload and context filter expression within
2099 @param[in] event_name_exclusion_count
2100 Number of items in \lt_p{event_name_exclusions}.
2101 @param[in] event_name_exclusions
2103 Event name exclusion patterns of the recording event rule to create
2106 This function copies the strings of this array.
2108 \lt_p{event_name_exclusion_count} indicates the size of this
2109 array, which may be \c NULL if \lt_p{event_name_exclusion_count}
2112 This parameter, even when \c NULL or empty, overrides any existing
2113 event name exclusion patterns within \lt_p{event_rule}.
2117 0 on success, or a \em negative #lttng_error_code enumerator
2121 @lt_pre_not_null{handle}
2122 @lt_pre_valid_c_str{handle->session_name}
2123 @lt_pre_sess_exists{handle->session_name}
2125 \lt_p{handle->domain} is valid as per the documentation of
2127 @lt_pre_not_null{event_rule}
2129 \lt_p{event_rule} is \ref api-rer-valid-event-struct "valid".
2131 <strong>If \lt_p{handle->domain.type} is \em not
2132 #LTTNG_DOMAIN_KERNEL</strong>, then \lt_p{event_rule->type} is
2133 #LTTNG_EVENT_TRACEPOINT.
2135 <strong>If \lt_p{handle->domain.type} is \em not
2136 #LTTNG_DOMAIN_UST</strong>, then \lt_p{event_name_exclusion_count}
2139 <strong>If this function must enable an existing recording event
2140 rule</strong>, then the recording event rule to enable is disabled.
2142 <strong>If not \c NULL</strong>, \lt_p{channel_name} names an
2143 existing channel within the recording session and tracing domain of
2146 <strong>If \lt_p{channel_name} is \c NULL</strong>, then
2147 \lt_p{handle} contains either no channels or a default channel named
2150 <strong>If not \c NULL</strong>, \lt_p{filter_expr} is a valid
2151 event payload and context filter expression.
2153 \lt_p{event_name_exclusion_count} ≥ 0.
2155 @sa lttng_enable_event() --
2156 Alias which calls this function with the event payload and context
2157 filter expression and event name exclusion patterns of the
2158 recording event rule descriptor.
2159 @sa lttng_enable_event_with_filter() --
2160 Alias which calls this function with the event name exclusion
2161 patterns of the recording event rule descriptor.
2162 @sa lttng_disable_event_ext() --
2163 Disables a recording event rule.
2165 LTTNG_EXPORT
extern int lttng_enable_event_with_exclusions(struct lttng_handle
*handle
,
2166 struct lttng_event
*event_rule
,
2167 const char *channel_name
,
2168 const char *filter_expr
,
2169 int event_name_exclusion_count
,
2170 char **event_name_exclusions
);
2174 Alias of lttng_disable_event_ext() which creates a temporary
2175 recording event rule descriptor, settings its
2176 lttng_event::name member to \lt_p{event_name} if not \c NULL and
2177 its lttng_event::type member to #LTTNG_EVENT_ALL.
2181 This function is equivalent to:
2184 struct lttng_event event_rule = { 0 };
2186 event_rule.type = LTTNG_EVENT_ALL;
2189 strcpy(event_rule.name, event_name);
2192 event_rule.loglevel = -1;
2193 return lttng_disable_event_ext(handle, &event_rule, channel_name, NULL);
2196 LTTNG_EXPORT
extern int
2197 lttng_disable_event(struct lttng_handle
*handle
, const char *event_name
, const char *channel_name
);
2201 Disables recording event rules by
2202 \ref api-rer-conds-inst-pt-type "instrumentation point type" and
2203 \ref api-rer-conds-event-name "event name" condition within the
2204 \lt_obj_channel named \lt_p{channel_name}
2205 (or within a default channel if \c NULL) within the recording
2206 session handle \lt_p{handle}.
2210 Depending on \lt_p{event_rule->name}, this function:
2215 Depending on \lt_p{event_rule->type}:
2218 <dt>#LTTNG_EVENT_ALL
2220 Disables \em all the recording event rules of which the event
2221 name pattern is exactly \lt_p{event_rule->name} within the
2226 Disables all the recording event rules of which the
2227 instrumentation point type is
2228 \lt_p{event_rule->type} and the event
2229 name pattern is exactly \lt_p{event_rule->name} within the
2232 Only supported when \lt_p{handle->domain.type} is
2233 #LTTNG_DOMAIN_KERNEL.
2238 Depending on \lt_p{event_rule->type}:
2241 <dt>#LTTNG_EVENT_ALL
2243 Disables \em all the recording event rules within the selected
2248 Disables all the recording event rules of which the
2249 instrumentation point type is
2250 \lt_p{event_rule->type} within the
2253 Only supported when \lt_p{handle->domain.type} is
2254 #LTTNG_DOMAIN_KERNEL.
2258 This function ignores all the other \ref api-rer-conds "condition"
2259 properties of \lt_p{event_rule}.
2261 To use this function, create a temporary, zeroed
2262 \link #lttng_event recording event rule descriptor\endlink,
2265 - <strong>Optional, and only if \lt_p{handle->domain.type}
2266 is #LTTNG_DOMAIN_KERNEL</strong>: its lttng_event::type member.
2268 - <strong>Optional</strong>: its lttng_event::name member
2270 - Its lttng_event::loglevel member to -1.
2275 struct lttng_event event_rule = { 0 };
2277 event_rule.type = LTTNG_EVENT_SYSCALL;
2278 strcpy(event_rule.name, "open*");
2279 event_rule.loglevel = -1;
2283 Recording session handle which contains the name of the recording
2284 session and the summary of the \lt_obj_domain which own the selected
2286 @param[in] event_rule
2288 Recording event rule descriptor which contains the
2289 instrumentation point type and event name conditions to consider
2290 to disable recording event rules within the selected channel.
2292 @param[in] channel_name
2294 Name of the channel, within \lt_p{handle}, to select (that is,
2295 containing the recording event rules to disable).
2297 If \c NULL, then this function uses \c channel0.
2299 @param[in] filter_expr
2300 Unused: must be \c NULL.
2303 0 on success, or a \em negative #lttng_error_code enumerator
2307 @lt_pre_not_null{handle}
2308 @lt_pre_valid_c_str{handle->session_name}
2309 @lt_pre_sess_exists{handle->session_name}
2311 \lt_p{handle->domain} is valid as per the documentation of
2313 @lt_pre_not_null{event_rule}
2315 <strong>If \lt_p{handle->domain.type} is \em not
2316 #LTTNG_DOMAIN_KERNEL</strong>, then \lt_p{event_rule->type}
2317 is #LTTNG_EVENT_ALL.
2319 <strong>If not #LTTNG_EVENT_ALL</strong>, then
2320 \lt_p{event_rule->type} is the instrumentation point type of at
2321 least one Linux kernel recording event rule within the selected
2324 <strong>If not empty</strong>, then \lt_p{event_rule->name} is the
2325 exact event name pattern of at least one recording event rule within
2326 the selected channel.
2328 The recording event rules to disable are enabled.
2330 <strong>If not \c NULL</strong>, then \lt_p{channel_name} names an
2331 existing channel within the recording session and tracing domain of
2334 <strong>If \lt_p{channel_name} is \c NULL</strong>, then the
2335 channel named \c channel0 exists within the recording session and
2336 tracing domain of \lt_p{handle}.
2338 @sa lttng_disable_event() --
2339 Alias which calls this function with \lt_p{event_rule->type}
2340 set to #LTTNG_EVENT_ALL.
2341 @sa lttng_enable_event_with_exclusions() --
2342 Creates or enables a recording event rule.
2344 LTTNG_EXPORT
extern int lttng_disable_event_ext(struct lttng_handle
*handle
,
2345 struct lttng_event
*event_rule
,
2346 const char *channel_name
,
2347 const char *filter_expr
);
2353 #endif /* LTTNG_EVENT_H */