4 :sect-event-rule: INSTRUMENTATION POINT, EVENT RULE, AND EVENT
5 :sect-session: RECORDING SESSION
6 :sect-domain: TRACING DOMAIN
7 :sect-channel: CHANNEL AND RING BUFFER
8 :sect-recording-event-rule: RECORDING EVENT RULE AND EVENT RECORD
13 lttng-concepts - LTTng concepts
18 This manual page documents the concepts of LTTng.
20 Many other LTTng manual pages refer to this one so that you can
21 understand what are the various LTTng objects and how they relate to
24 The concepts of LTTng{nbsp}{lttng_version} are:
26 * Instrumentation point, event rule, and event
30 * Channel and ring buffer
31 * Recording event rule and event record
37 An _instrumentation point_ is a point, within a piece of software,
38 which, when executed, creates an LTTng _event_.
40 LTTng offers various types of instrumentation; see the
41 ``<<inst-point-types,Instrumentation point types>>'' section below to
44 An _event rule_ is a set of conditions to match a set of events.
46 When LTTng creates an event{nbsp}__E__, an event rule{nbsp}__ER__ is
47 said to __match__{nbsp}__E__ when{nbsp}__E__ satisfies *all* the
48 conditions of{nbsp}__ER__. This concept is similar to a regular
49 expression which matches a set of strings.
51 When an event rule matches an event, LTTng _emits_ the event, therefore
52 attempting to execute one or more actions.
56 The event creation and emission processes are documentation concepts to
57 help understand the journey from an instrumentation point to the
60 The actual creation of an event can be costly because LTTng needs to
61 evaluate the arguments of the instrumentation point.
63 In practice, LTTng implements various optimizations for the Linux kernel
64 and user space tracing domains (see the ``<<domain,{sect-domain}>>''
65 section below) to avoid actually creating an event when the tracer
66 knows, thanks to properties which are independent from the event payload
67 and current context, that it would never emit such an event. Those
70 * The instrumentation point type (see the
71 ``<<inst-point-types,Instrumentation point types>>'' section below).
73 * The instrumentation point name.
75 * The instrumentation point log level.
77 * For a recording event rule (see the
78 ``<<recording-event-rule,{sect-recording-event-rule}>>'' section
80 ** The status of the rule itself.
81 ** The status of the channel (see the ``<<channel,{sect-channel}>>''
83 ** The activity of the recording session (started or stopped; see
84 the ``<<session,{sect-session}>>'' section below).
85 ** Whether or not the process for which LTTng would create the event is
86 allowed to record events (see man:lttng-track(1)).
88 In other words: if, for a given instrumentation point{nbsp}__IP__, the
89 LTTng tracer knows that it would never emit an event,
90 executing{nbsp}__IP__ represents a simple boolean variable check and,
91 for a Linux kernel recording event rule, a few process attribute checks.
94 As of LTTng{nbsp}{lttng_version}, there are two places where you can
97 Recording event rule::
98 A specific type of event rule of which the action is to record the
99 matched event as an event record.
101 See the ``<<recording-event-rule,{sect-recording-event-rule}>>'' section
104 Create or enable a recording event rule with the
105 man:lttng-enable-event(1) command.
107 List the recording event rules of a specific recording session
108 and/or channel with the man:lttng-list(1) and man:lttng-status(1)
111 ``Event rule matches'' <<trigger,trigger>> condition (since LTTng{nbsp}2.13)::
112 When the event rule of the trigger condition matches an event, LTTng
113 can execute user-defined actions such as sending an LTTng
114 notification, starting a recording session, and more.
116 See man:lttng-add-trigger(1) and man:lttng-event-rule(7).
118 For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
119 basic conditions of an event rule{nbsp}__ER__, that is:
121 * The instrumentation point from which LTTng creates{nbsp}__E__ has a
124 See the ``<<inst-point-types,Instrumentation point types>>'' section
127 * A pattern matches the name of{nbsp}__E__ while another pattern
130 * The log level of the instrumentation point from which LTTng
131 creates{nbsp}__E__ is at least as severe as some value, or is exactly
134 * The fields of the payload of{nbsp}__E__ and the current context fields
135 satisfy a filter expression.
137 A recording event rule has additional, implicit conditions to satisfy.
138 See the ``<<recording-event-rule,{sect-recording-event-rule}>>'' section
143 Instrumentation point types
144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
145 As of LTTng{nbsp}{lttng_version}, the available instrumentation point
146 types are, depending on the tracing domain (see the
147 ``<<domain,{sect-domain}>>'' section below):
151 A statically defined point in the source code of the kernel
152 image or of a kernel module using the LTTng-modules macros.
154 List the available Linux kernel tracepoints with `lttng list --kernel`.
155 See man:lttng-list(1) to learn more.
157 Linux kernel system call:::
158 Entry, exit, or both of a Linux kernel system call.
160 List the available Linux kernel system call instrumentation points with
161 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
164 A single probe dynamically placed in the compiled kernel code.
166 When you create such an instrumentation point, you set its memory
167 address or symbol name.
169 Linux user space probe:::
170 A single probe dynamically placed at the entry of a compiled
171 user space application/library function through the kernel.
173 When you create such an instrumentation point, you set:
176 With the ELF method::
177 Its application/library path and its symbol name.
179 With the USDT method::
180 Its application/library path, its provider name, and its probe name.
182 ``USDT'' stands for SystemTap User-level Statically Defined Tracing,
183 a DTrace-style marker.
186 As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
187 are :not: reference-counted.
190 Entry, exit, or both of a Linux kernel function.
192 When you create such an instrumentation point, you set the memory
193 address or symbol name of its function.
197 A statically defined point in the source code of a C/$$C++$$
198 application/library using the LTTng-UST macros.
200 List the available Linux kernel tracepoints with
201 `lttng list --userspace`. See man:lttng-list(1) to learn more.
203 `java.util.logging`, Apache Log4j 1.x, Apache Log4j 2, and Python::
204 Java or Python logging statement:::
205 A method call on a Java or Python logger attached to an
208 List the available Java and Python loggers with `lttng list --jul`,
209 `lttng list --log4j`, `lttng list --log4j2`, and `lttng list --python`. See
210 man:lttng-list(1) to learn more.
216 A _trigger_ associates a condition to one or more actions.
218 When the condition of a trigger is satisfied, LTTng attempts to execute
221 As of LTTng{nbsp}{lttng_version}, the available trigger conditions and
226 * The consumed buffer size of a given recording
227 session (see the ``<<session,{sect-session}>>'' section below)
228 becomes greater than some value.
230 * The buffer usage of a given channel (see the
231 ``<<channel,{sect-channel}>>'' section below) becomes greater than
234 * The buffer usage of a given channel becomes less than some value.
236 * There's an ongoing recording session rotation (see the
237 ``<<rotation,Recording session rotation>>'' section below).
239 * A recording session rotation becomes completed.
241 * An event rule matches an event.
243 As of LTTng{nbsp}{lttng_version}, this is the only available condition
244 when you add a trigger with the man:lttng-add-trigger(1) command. The
245 other ones are available through the liblttng-ctl C{nbsp}API.
249 * Send a notification to a user application.
250 * Start a given recording session, like man:lttng-start(1) would do.
251 * Stop a given recording session, like man:lttng-stop(1) would do.
252 * Archive the current trace chunk of a given recording session (rotate),
253 like man:lttng-rotate(1) would do.
254 * Take a snapshot of a given recording session, like
255 man:lttng-snapshot(1) would do.
257 A trigger belongs to a session daemon (see man:lttng-sessiond(8)), not
258 to a specific recording session. For a given session daemon, each Unix
259 user has its own, private triggers. Note, however, that the `root` Unix
260 user may, for the root session daemon:
262 * Add a trigger as another Unix user.
264 * List all the triggers, regardless of their owner.
266 * Remove a trigger which belongs to another Unix user.
268 For a given session daemon and Unix user, a trigger has a unique name.
270 Add a trigger to a session daemon with the man:lttng-add-trigger(1)
273 List the triggers of your Unix user (or of all users if your
274 Unix user is `root`) with the man:lttng-list-triggers(1) command.
276 Remove a trigger with the man:lttng-remove-trigger(1) command.
282 A _recording session_ (named ``tracing session'' prior to
283 LTTng{nbsp}2.13) is a stateful dialogue between you and a session daemon
284 (see man:lttng-sessiond(8)) for everything related to event recording.
286 Everything that you do when you control LTTng tracers to record events
287 happens within a recording session. In particular, a recording session:
289 * Has its own name, unique for a given session daemon.
291 * Has its own set of trace files, if any.
293 * Has its own state of activity (started or stopped).
295 An active recording session is an implicit recording event rule
297 ``<<recording-event-rule,{sect-recording-event-rule}>>'' section below).
299 * Has its own mode (local, network streaming, snapshot, or live).
301 See the ``<<session-modes,Recording session modes>>'' section below to
304 * Has its own channels (see the ``<<channel,{sect-channel}>>'' section
305 below) to which are attached their own recording event rules.
307 * Has its own process attribute inclusion sets (see man:lttng-track(1)).
309 Those attributes and objects are completely isolated between different
312 A recording session is like an ATM session: the operations you do on the
313 banking system through the ATM don't alter the data of other users of
314 the same system. In the case of the ATM, a session lasts as long as your
315 bank card is inside. In the case of LTTng, a recording session lasts from
316 the man:lttng-create(1) command to the man:lttng-destroy(1) command.
318 A recording session belongs to a session daemon (see
319 man:lttng-sessiond(8)). For a given session daemon, each Unix user has
320 its own, private recording sessions. Note, however, that the `root` Unix
321 user may operate on or destroy another user's recording session.
323 Create a recording session with the man:lttng-create(1) command.
325 List the recording sessions of the connected session daemon with
326 the man:lttng-list(1) command.
328 Start and stop a recording session with the man:lttng-start(1) and
329 man:lttng-stop(1) commands.
331 Save and load a recording session with the man:lttng-save(1) and
332 man:lttng-load(1) commands.
334 Archive the current trace chunk of (rotate) a recording session with the
335 man:lttng-rotate(1) command.
337 Destroy a recording session with the man:lttng-destroy(1) command.
340 Current recording session
341 ~~~~~~~~~~~~~~~~~~~~~~~
342 When you run the man:lttng-create(1) command, LTTng creates the
343 `$LTTNG_HOME/.lttngrc` file if it doesn't exist (`$LTTNG_HOME` defaults
346 `$LTTNG_HOME/.lttngrc` contains the name of the _current recording
349 When you create a new recording session with the `create` command, LTTng
350 updates the current recording session.
352 The following man:lttng(1) commands select the current recording session
353 if you don't specify one:
355 * man:lttng-add-context(1)
357 * man:lttng-destroy(1)
358 * man:lttng-disable-channel(1)
359 * man:lttng-disable-event(1)
360 * man:lttng-disable-rotation(1)
361 * man:lttng-enable-channel(1)
362 * man:lttng-enable-event(1)
363 * man:lttng-enable-rotation(1)
364 * man:lttng-regenerate(1)
365 * man:lttng-rotate(1)
367 * man:lttng-snapshot(1)
369 * man:lttng-status(1)
372 * man:lttng-untrack(1)
375 Set the current recording session manually with the
376 man:lttng-set-session(1) command, without having to edit the `.lttngrc`
381 Recording session modes
382 ~~~~~~~~~~~~~~~~~~~~~~~
383 LTTng offers four recording session modes:
386 Write the trace data to the local file system.
388 Network streaming mode::
389 Send the trace data over the network to a listening relay daemon
390 (see man:lttng-relayd(8)).
393 Only write the trace data to the local file system or send it to a
394 listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
397 LTTng forces all the channels (see the ``<<channel,{sect-channel}>>''
398 section below) to be created to be configured to be snapshot-ready.
400 LTTng takes a snapshot of such a recording session when:
403 * You run the man:lttng-snapshot(1) command.
405 * LTTng executes a `snapshot-session` trigger action (see the
406 ``<<trigger,TRIGGER>>'' section above).
410 Send the trace data over the network to a listening relay daemon
411 (see man:lttng-relayd(8)) for live reading.
413 An LTTng live reader (for example, man:babeltrace2(1)) can connect to
414 the same relay daemon to receive trace data while the recording session is
419 Recording session rotation
420 ~~~~~~~~~~~~~~~~~~~~~~~~~~
421 A _recording session rotation_ is the action of archiving the current
422 trace chunk of the recording session to the file system.
424 Once LTTng archives a trace chunk, it does :not: manage it anymore: you
425 can read it, modify it, move it, or remove it.
427 An _archived trace chunk_ is a collection of metadata and data stream
428 files which form a self-contained LTTng trace. See the
429 ``<<trace-chunk-naming,Trace chunk naming>>'' section below to learn how
430 LTTng names a trace chunk archive directory.
432 The _current trace chunk_ of a given recording session includes:
434 * The stream files which LTTng already wrote to the file system, and
435 which are not part of a previously archived trace chunk, since the
436 most recent event amongst:
438 ** The first time the recording session was started, either with the
439 man:lttng-start(1) command or with a `start-session` trigger action
440 (see the ``<<trigger,TRIGGER>>'' section above).
442 ** The last rotation, performed with:
444 *** An man:lttng-rotate(1) command.
446 *** A rotation schedule previously set with
447 man:lttng-enable-rotation(1).
449 *** An executed `rotate-session` trigger action (see the
450 ``<<trigger,TRIGGER>>'' section above).
452 * The content of all the non-flushed sub-buffers of the channels of the
456 [[trace-chunk-naming]]
457 Trace chunk archive naming
458 ~~~~~~~~~~~~~~~~~~~~~~~~~~
459 A trace chunk archive is a subdirectory of the `archives` subdirectory
460 within the output directory of a recording session (see the
461 nloption:--output option of the man:lttng-create(1) command and
462 of man:lttng-relayd(8)).
464 A trace chunk archive contains, through tracing domain and possibly
465 UID/PID subdirectories, metadata and data stream files.
467 A trace chunk archive is, at the same time:
469 * A self-contained LTTng trace.
471 * A member of a set of trace chunk archives which form the complete
472 trace of a recording session.
474 In other words, an LTTng trace reader can read both the recording
475 session output directory (all the trace chunk archives), or a
476 single trace chunk archive.
478 When LTTng performs a recording session rotation, it names the resulting
479 trace chunk archive as such, relative to the output directory of the
483 archives/__BEGIN__-__END__-__ID__
486 Date and time of the beginning of the trace chunk archive with
487 the ISO{nbsp}8601-compatible __YYYYmmddTHHMMSS±HHMM__ form, where
488 __YYYYmmdd__ is the date and __HHMMSS±HHMM__ is the time with the
489 time zone offset from UTC.
491 Example: `20171119T152407-0500`
494 Date and time of the end of the trace chunk archive with
495 the ISO{nbsp}8601-compatible __YYYYmmddTHHMMSS±HHMM__ form, where
496 __YYYYmmdd__ is the date and __HHMMSS±HHMM__ is the time with the
497 time zone offset from UTC.
499 Example: `20180118T152407+0930`
502 Unique numeric identifier of the trace chunk within its recording
505 Trace chunk archive name example:
508 archives/20171119T152407-0500-20171119T151422-0500-3
515 A _tracing domain_ identifies a type of LTTng tracer.
517 A tracing domain has its own properties and features.
519 There are currently five available tracing domains:
523 |Tracing domain |``Event rule matches'' trigger condition option |Option for other CLI commands
526 |nloption:--type option starts with `kernel:`
530 |nloption:--type option starts with `user:`
531 |nloption:--userspace
533 |`java.util.logging` (JUL)
534 |nloption:--type option starts with `jul:`
538 |nloption:--type option starts with `log4j:`
542 |nloption:--type option starts with `log4j2:`
546 |nloption:--type option starts with `python:`
550 You must specify a tracing domain to target a type of LTTng tracer when
551 using some man:lttng(1) commands to avoid ambiguity. For example,
552 because the Linux kernel and user space tracing domains support named
553 tracepoints as instrumentation points (see the
554 ``<<"event-rule","{sect-event-rule}">>'' section above), you need to
555 specify a tracing domain when you create an event rule because both
556 tracing domains could have tracepoints sharing the same name.
558 You can create channels (see the ``<<channel,{sect-channel}>>'' section
559 below) in the Linux kernel and user space tracing domains. The other
560 tracing domains have a single, default channel.
566 A _channel_ is an object which is responsible for a set of ring buffers.
568 Each ring buffer is divided into multiple _sub-buffers_. When a
569 recording event rule (see the
570 ``<<recording-event-rule,{sect-recording-event-rule}>>'' section below)
571 matches an event, LTTng can record it to one or more sub-buffers of one
574 When you create a channel with the man:lttng-enable-channel(1) command,
575 you set its final attributes, that is:
577 * Its buffering scheme.
579 See the ``<<channel-buf-scheme,Buffering scheme>>'' section below.
581 * What to do when there's no
582 space left for a new event record because all sub-buffers are full.
584 See the ``<<channel-er-loss-mode,Event record loss mode>>'' section
587 * The size of each ring buffer and how many sub-buffers a ring buffer
590 See the ``<<channel-sub-buf-size-count,Sub-buffer size and count>>''
593 * The size of each trace file LTTng writes for this channel and the
594 maximum count of trace files.
596 See the ``<<channel-max-trace-file-size-count,Maximum trace file size
597 and count>>'' section below.
599 * The periods of its read, switch, and monitor timers.
601 See the ``<<channel-timers,Timers>>'' section below.
603 * For a Linux kernel channel: its output type (man:mmap(2) or
606 See the nloption:--output option of the man:lttng-enable-channel(1)
609 * For a user space channel: the value of its blocking timeout.
611 See the nloption:--blocking-timeout option of the
612 man:lttng-enable-channel(1) command.
614 Note that the man:lttng-enable-event(1) command can automatically create
615 a default channel with sane defaults when no channel exists for the
616 provided tracing domain.
618 A channel is always associated to a tracing domain (see the
619 ``<<domain,{sect-domain}>>'' section below). The `java.util.logging`
620 (JUL), log4j, log4j2 and Python tracing domains each have a default channel
621 which you can't configure.
623 A channel owns recording event rules.
625 List the channels of a given recording session with the
626 man:lttng-list(1) and man:lttng-status(1) commands.
628 Disable an enabled channel with the man:lttng-disable-channel(1)
632 [[channel-buf-scheme]]
635 A channel has at least one ring buffer per CPU. LTTng always records an
636 event to the ring buffer dedicated to the CPU which emits it.
638 The buffering scheme of a user space channel determines what has its own
639 set of per-CPU ring buffers:
641 Per-user buffering (nloption:--buffers-uid option of the man:lttng-enable-channel(1) command)::
642 Allocate one set of ring buffers (one per CPU) shared by all the
643 instrumented processes of:
644 If your Unix user is `root`:::
649 Per-process buffering (nloption:--buffers-pid option of the man:lttng-enable-channel(1) command)::
650 Allocate one set of ring buffers (one per CPU) for each instrumented
652 If your Unix user is `root`:::
657 The per-process buffering scheme tends to consume more memory than the
658 per-user option because systems generally have more instrumented
659 processes than Unix users running instrumented processes. However, the
660 per-process buffering scheme ensures that one process having a high
661 event throughput won't fill all the shared sub-buffers of the same Unix
664 The buffering scheme of a Linux kernel channel is always to allocate a
665 single set of ring buffers for the whole system. This scheme is similar
666 to the per-user option, but with a single, global user ``running'' the
670 [[channel-er-loss-mode]]
671 Event record loss mode
672 ~~~~~~~~~~~~~~~~~~~~~~
673 When LTTng emits an event, LTTng can record it to a specific, available
674 sub-buffer within the ring buffers of specific channels. When there's no
675 space left in a sub-buffer, the tracer marks it as consumable and
676 another, available sub-buffer starts receiving the following event
677 records. An LTTng consumer daemon eventually consumes the marked
678 sub-buffer, which returns to the available state.
680 In an ideal world, sub-buffers are consumed faster than they are filled.
681 In the real world, however, all sub-buffers can be full at some point,
682 leaving no space to record the following events.
684 By default, LTTng-modules and LTTng-UST are _non-blocking_ tracers: when
685 there's no available sub-buffer to record an event, it's acceptable to
686 lose event records when the alternative would be to cause substantial
687 delays in the execution of the instrumented application. LTTng
688 privileges performance over integrity; it aims at perturbing the
689 instrumented application as little as possible in order to make the
690 detection of subtle race conditions and rare interrupt cascades
693 Since LTTng{nbsp}2.10, the LTTng user space tracer, LTTng-UST, supports
694 a _blocking mode_. See the nloption:--blocking-timeout of the
695 man:lttng-enable-channel(1) command to learn how to use the blocking
698 When it comes to losing event records because there's no available
699 sub-buffer, or because the blocking timeout of the channel is
700 reached, the _event record loss mode_ of the channel determines what to
701 do. The available event record loss modes are:
704 Drop the newest event records until a sub-buffer becomes available.
706 This is the only available mode when you specify a blocking timeout.
708 With this mode, LTTng increments a count of lost event records when an
709 event record is lost and saves this count to the trace. A trace reader
710 can use the saved discarded event record count of the trace to decide
711 whether or not to perform some analysis even if trace data is known to
715 Clear the sub-buffer containing the oldest event records and start
716 writing the newest event records there.
718 This mode is sometimes called _flight recorder mode_ because it's
719 similar to a https://en.wikipedia.org/wiki/Flight_recorder[flight
720 recorder]: always keep a fixed amount of the latest data. It's also
721 similar to the roll mode of an oscilloscope.
723 Since LTTng{nbsp}2.8, with this mode, LTTng writes to a given sub-buffer
724 its sequence number within its data stream. With a local, network
725 streaming, or live recording session (see the
726 ``<<session-modes,Recording session modes>>'' section above), a trace
727 reader can use such sequence numbers to report lost packets. A trace
728 reader can use the saved discarded sub-buffer (packet) count of the
729 trace to decide whether or not to perform some analysis even if trace
730 data is known to be missing.
732 With this mode, LTTng doesn't write to the trace the exact number of
733 lost event records in the lost sub-buffers.
735 Which mechanism you should choose depends on your context: prioritize
736 the newest or the oldest event records in the ring buffer?
738 Beware that, in overwrite mode, the tracer abandons a _whole sub-buffer_
739 as soon as a there's no space left for a new event record, whereas in
740 discard mode, the tracer only discards the event record that doesn't
743 Set the event record loss mode of a channel with the nloption:--discard
744 and nloption:--overwrite options of the man:lttng-enable-channel(1)
747 There are a few ways to decrease your probability of losing event
748 records. The ``<<channel-sub-buf-size-count,Sub-buffer size and
749 count>>'' section below shows how to fine-tune the sub-buffer size and
750 count of a channel to virtually stop losing event records, though at the
751 cost of greater memory usage.
754 [[channel-sub-buf-size-count]]
755 Sub-buffer size and count
756 ~~~~~~~~~~~~~~~~~~~~~~~~~
757 A channel has one or more ring buffer for each CPU of the target system.
759 See the ``<<channel-buf-scheme,Buffering scheme>>'' section above to
760 learn how many ring buffers of a given channel are dedicated to each CPU
761 depending on its buffering scheme.
763 Set the size of each sub-buffer the ring buffers of a channel contain
764 with the nloption:--subbuf-size option of the
765 man:lttng-enable-channel(1) command.
767 Set the number of sub-buffers each ring buffer of a channel contains
768 with the nloption:--num-subbuf option of the man:lttng-enable-channel(1)
771 Note that LTTng switching the current sub-buffer of a ring buffer
772 (marking a full one as consumable and switching to an available one for
773 LTTng to record the next events) introduces noticeable CPU overhead.
774 Knowing this, the following list presents a few practical situations
775 along with how to configure the sub-buffer size and count for them:
777 High event throughput::
778 In general, prefer large sub-buffers to lower the risk of losing
781 Having larger sub-buffers also ensures a lower sub-buffer switching
782 frequency (see the ``<<channel-timers,Timers>>'' section below).
784 The sub-buffer count is only meaningful if you create the channel in
785 overwrite mode (see the ``<<channel-er-loss-mode,Event record loss
786 mode>>'' section above): in this case, if LTTng overwrites a sub-buffer,
787 then the other sub-buffers are left unaltered.
789 Low event throughput::
790 In general, prefer smaller sub-buffers since the risk of losing
791 event records is low.
793 Because LTTng emits events less frequently, the sub-buffer switching
794 frequency should remain low and therefore the overhead of the tracer
795 shouldn't be a problem.
798 If your target system has a low memory limit, prefer fewer first,
799 then smaller sub-buffers.
801 Even if the system is limited in memory, you want to keep the
802 sub-buffers as large as possible to avoid a high sub-buffer switching
805 Note that LTTng uses https://diamon.org/ctf/[CTF] as its trace format,
806 which means event record data is very compact. For example, the average
807 LTTng kernel event record weights about 32{nbsp}bytes. Therefore, a
808 sub-buffer size of 1{nbsp}MiB is considered large.
810 The previous scenarios highlight the major trade-off between a few large
811 sub-buffers and more, smaller sub-buffers: sub-buffer switching
812 frequency vs. how many event records are lost in overwrite mode.
813 Assuming a constant event throughput and using the overwrite mode, the
814 two following configurations have the same ring buffer total size:
816 Two sub-buffers of 4{nbsp}MiB each::
817 Expect a very low sub-buffer switching frequency, but if LTTng
818 ever needs to overwrite a sub-buffer, half of the event records so
819 far (4{nbsp}MiB) are definitely lost.
821 Eight sub-buffers of 1{nbsp}MiB each::
822 Expect four times the tracer overhead of the configuration above,
823 but if LTTng needs to overwrite a sub-buffer, only the eighth of
824 event records so far (1{nbsp}MiB) are definitely lost.
826 In discard mode, the sub-buffer count parameter is pointless: use two
827 sub-buffers and set their size according to your requirements.
830 [[channel-max-trace-file-size-count]]
831 Maximum trace file size and count
832 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
833 By default, trace files can grow as large as needed.
835 Set the maximum size of each trace file that LTTng writes of a given
836 channel with the nloption:--tracefile-size option of the man:lttng-enable-channel(1)
839 When the size of a trace file reaches the fixed maximum size of the
840 channel, LTTng creates another file to contain the next event records.
841 LTTng appends a file count to each trace file name in this case.
843 If you set the trace file size attribute when you create a channel, the
844 maximum number of trace files that LTTng creates is _unlimited_ by
845 default. To limit them, use the nloption:--tracefile-count option of
846 man:lttng-enable-channel(1). When the number of trace files reaches the
847 fixed maximum count of the channel, LTTng overwrites the oldest trace
848 file. This mechanism is called _trace file rotation_.
852 Even if you don't limit the trace file count, always assume that LTTng
853 manages all the trace files of the recording session.
855 In other words, there's no safe way to know if LTTng still holds a given
856 trace file open with the trace file rotation feature.
858 The only way to obtain an unmanaged, self-contained LTTng trace before
859 you destroy the recording session is with the recording session rotation
860 feature (see the ``<<rotation,Recording session rotation>>'' section
861 above), which is available since LTTng{nbsp}2.11.
868 Each channel can have up to three optional timers:
871 When this timer expires, a sub-buffer switch happens: for each ring
872 buffer of the channel, LTTng marks the current sub-buffer as
873 consumable and switches to an available one to record the next
876 A switch timer is useful to ensure that LTTng consumes and commits trace
877 data to trace files or to a distant relay daemon (man:lttng-relayd(8))
878 periodically in case of a low event throughput.
880 Such a timer is also convenient when you use large sub-buffers (see the
881 ``<<channel-sub-buf-size-count,Sub-buffer size and count>>'' section
882 above) to cope with a sporadic high event throughput, even if the
883 throughput is otherwise low.
885 Set the period of the switch timer of a channel, or disable the timer
886 altogether, with the nloption:--switch-timer option of the
887 man:lttng-enable-channel(1) command.
890 When this timer expires, LTTng checks for full, consumable
893 By default, the LTTng tracers use an asynchronous message mechanism to
894 signal a full sub-buffer so that a consumer daemon can consume it.
896 When such messages must be avoided, for example in real-time
897 applications, use this timer instead.
899 Set the period of the read timer of a channel, or disable the timer
900 altogether, with the nloption:--read-timer option of the
901 man:lttng-enable-channel(1) command.
904 When this timer expires, the consumer daemon samples some channel
905 statistics to evaluate the following trigger conditions:
908 . The consumed buffer size of a given recording session becomes greater
910 . The buffer usage of a given channel becomes greater than some value.
911 . The buffer usage of a given channel becomes less than some value.
914 If you disable the monitor timer of a channel{nbsp}__C__:
917 * The consumed buffer size value of the recording session of{nbsp}__C__
918 could be wrong for trigger condition type{nbsp}1: the consumed buffer
919 size of{nbsp}__C__ won't be part of the grand total.
921 * The buffer usage trigger conditions (types{nbsp}2 and{nbsp}3)
922 for{nbsp}__C__ will never be satisfied.
925 See the ``<<trigger,TRIGGER>>'' section above to learn more about
928 Set the period of the monitor timer of a channel, or disable the timer
929 altogether, with the nloption:--monitor-timer option of the
930 man:lttng-enable-channel(1) command.
933 [[recording-event-rule]]
934 {sect-recording-event-rule}
935 ---------------------------
936 A _recording event rule_ is a specific type of event rule (see the
937 ``<<"event-rule","{sect-event-rule}">>'' section above) of which the
938 action is to serialize and record the matched event as an _event
941 Set the explicit conditions of a recording event rule when you create it
942 with the man:lttng-enable-event(1) command. A recording event rule also
943 has the following implicit conditions:
945 * The recording event rule itself is enabled.
947 A recording event rule is enabled on creation.
949 * The channel to which the recording event rule is attached is enabled.
951 A channel is enabled on creation.
953 See the ``<<channel,{sect-channel}>>'' section above.
955 * The recording session of the recording event rule is active (started).
957 A recording session is inactive (stopped) on creation.
959 See the ``<<session,{sect-session}>>'' section above.
961 * The process for which LTTng creates an event to match is allowed to
964 All processes are allowed to record events on recording session
967 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
968 which processes are allowed to record events based on specific process
971 You always attach a recording event rule to a channel, which belongs to
972 a recording session, when you create it.
974 When a recording event rule{nbsp}__ER__ matches an event{nbsp}__E__,
975 LTTng attempts to serialize and record{nbsp}__E__ to one of the
976 available sub-buffers of the channel to which{nbsp}__E__ is attached.
978 When multiple matching recording event rules are attached to the same
979 channel, LTTng attempts to serialize and record the matched event
980 _once_. In the following example, the second recording event rule is
981 redundant when both are enabled:
985 $ lttng enable-event --userspace hello:world
986 $ lttng enable-event --userspace hello:world --loglevel=INFO
989 List the recording event rules of a specific recording session
990 and/or channel with the man:lttng-list(1) and man:lttng-status(1)
993 Disable a recording event rule with the man:lttng-disable-event(1)
996 As of LTTng{nbsp}{lttng_version}, you cannot remove a recording event
997 rule: it exists as long as its recording session exists.
1000 include::common-footer.txt[]
1006 man:lttng-relayd(8),
1007 man:lttng-sessiond(8)