which, when executed, creates an LTTng _event_.
LTTng offers various types of instrumentation; see the
-<<inst-point-types,Instrumentation point types>> section below to learn
-about them.
+``<<inst-point-types,Instrumentation point types>>'' section below to
+learn about them.
An _event rule_ is a set of conditions to match a set of events.
evaluate the arguments of the instrumentation point.
In practice, LTTng implements various optimizations for the Linux kernel
-and user space tracing domains (see the <<domain,{sect-domain}>> section
-below) to avoid actually creating an event
-when the tracer knows, thanks to properties which are independent from
-the event payload and current context, that it would never emit such an
-event. Those properties are:
+and user space tracing domains (see the ``<<domain,{sect-domain}>>''
+section below) to avoid actually creating an event when the tracer
+knows, thanks to properties which are independent from the event payload
+and current context, that it would never emit such an event. Those
+properties are:
* The instrumentation point type (see the
- <<inst-point-types,Instrumentation point types>> section below).
+ ``<<inst-point-types,Instrumentation point types>>'' section below).
* The instrumentation point name.
* The instrumentation point log level.
* For a recording event rule (see the
- <<recording-event-rule,{sect-recording-event-rule}>> section
+ ``<<recording-event-rule,{sect-recording-event-rule}>>'' section
below):
** The status of the rule itself.
-** The status of the channel (see the <<channel,{sect-channel}>> section
- below).
+** The status of the channel (see the ``<<channel,{sect-channel}>>''
+ section below).
** The activity of the tracing session (started or stopped; see
- the <<session,{sect-session}>> section below).
+ the ``<<session,{sect-session}>>'' section below).
** Whether or not the process for which LTTng would create the event is
allowed to record events (see man:lttng-track(1)).
A specific type of event rule of which the action is to record the
matched event as an event record.
+
-See the <<recording-event-rule,{sect-recording-event-rule}>> section
+See the ``<<recording-event-rule,{sect-recording-event-rule}>>'' section
below.
+
Create or enable a recording event rule with the
* The instrumentation point from which LTTng creates{nbsp}__E__ has a
specific type.
+
-See the <<inst-point-types,Instrumentation point types>> section below.
+See the ``<<inst-point-types,Instrumentation point types>>'' section
+below.
* A pattern matches the name of{nbsp}__E__ while another pattern
doesn't.
satisfy a filter expression.
A recording event rule has additional, implicit conditions to satisfy.
-See the <<recording-event-rule,{sect-recording-event-rule}>> section
+See the ``<<recording-event-rule,{sect-recording-event-rule}>>'' section
below to learn more.
~~~~~~~~~~~~~~~~~~~~~~~~~~~
As of LTTng{nbsp}{lttng_version}, the available instrumentation point
types are, depending on the tracing domain (see the
-<<domain,{sect-domain}>> section below):
+``<<domain,{sect-domain}>>'' section below):
Linux kernel::
LTTng tracepoint:::
Conditions::
+
* The consumed buffer size of a given tracing
- session (see the <<session,{sect-session}>> section below)
+ session (see the ``<<session,{sect-session}>>'' section below)
becomes greater than some value.
* The buffer usage of a given channel (see the
- <<channel,{sect-channel}>> section below) becomes greater than some
- value.
+ ``<<channel,{sect-channel}>>'' section below) becomes greater than
+ some value.
* The buffer usage of a given channel becomes less than some value.
* There's an ongoing tracing session rotation (see the
- <<rotation,Tracing session rotation>> section below).
+ ``<<rotation,Tracing session rotation>>'' section below).
* A tracing session rotation becomes completed.
* Has its own state of activity (started or stopped).
+
An active tracing session is an implicit recording event rule condition
-(see the <<recording-event-rule,{sect-recording-event-rule}>> section
-below).
+(see the ``<<recording-event-rule,{sect-recording-event-rule}>>''
+section below).
* Has its own mode (local, network streaming, snapshot, or live).
+
-See the <<session-modes,Tracing session modes>> section below to learn
-more.
+See the ``<<session-modes,Tracing session modes>>'' section below to
+learn more.
-* Has its own channels (see the <<channel,{sect-channel}>> section
+* Has its own channels (see the ``<<channel,{sect-channel}>>'' section
below) to which are attached their own recording event rules.
* Has its own process attribute inclusion sets (see man:lttng-track(1)).
listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
snapshot.
+
-LTTng forces all the channels (see the <<channel,{sect-channel}>>
+LTTng forces all the channels (see the ``<<channel,{sect-channel}>>''
section below) to be created to be configured to be snapshot-ready.
+
LTTng takes a snapshot of such a tracing session when:
* You run the man:lttng-snapshot(1) command.
* LTTng executes a `snapshot-session` trigger action (see the
- <<trigger,TRIGGER>> section above).
+ ``<<trigger,TRIGGER>>'' section above).
--
Live mode::
An _archived trace chunk_ is a collection of metadata and data stream
files which form a self-contained LTTng trace. See the
-<<trace-chunk-naming,Trace chunk naming>> section below to learn how
+``<<trace-chunk-naming,Trace chunk naming>>'' section below to learn how
LTTng names a trace chunk archive directory.
The _current trace chunk_ of a given tracing session includes:
** The first time the tracing session was started, either with the
man:lttng-start(1) command or with a `start-session` trigger action
- (see the <<trigger,TRIGGER>> section above).
+ (see the ``<<trigger,TRIGGER>>'' section above).
** The last rotation, performed with:
man:lttng-enable-rotation(1).
*** An executed `rotate-session` trigger action (see the
- <<trigger,TRIGGER>> section above).
+ ``<<trigger,TRIGGER>>'' section above).
* The content of all the non-flushed sub-buffers of the channels of the
tracing session.
using some man:lttng(1) commands to avoid ambiguity. For example,
because the Linux kernel and user space tracing domains support named
tracepoints as instrumentation points (see the
-<<"event-rule","{sect-event-rule}">> section above), you need to specify
-a tracing domain when you create an event rule because both tracing
-domains could have tracepoints sharing the same name.
+``<<"event-rule","{sect-event-rule}">>'' section above), you need to
+specify a tracing domain when you create an event rule because both
+tracing domains could have tracepoints sharing the same name.
-You can create channels (see the <<channel,{sect-channel}>> section
+You can create channels (see the ``<<channel,{sect-channel}>>'' section
below) in the Linux kernel and user space tracing domains. The other
tracing domains have a single, default channel.
Each ring buffer is divided into multiple _sub-buffers_. When a
recording event rule (see the
-<<recording-event-rule,{sect-recording-event-rule} section below)
+``<<recording-event-rule,{sect-recording-event-rule}>>'' section below)
matches an event, LTTng can record it to one or more sub-buffers of one
or more channels.
* Its buffering scheme.
+
-See the <<channel-buf-scheme,Buffering scheme>> section below.
+See the ``<<channel-buf-scheme,Buffering scheme>>'' section below.
* What to do when there's no
space left for a new event record because all sub-buffers are full.
+
-See the <<channel-er-loss-mode,Event record loss mode>> section below.
+See the ``<<channel-er-loss-mode,Event record loss mode>>'' section
+below.
* The size of each ring buffer and how many sub-buffers a ring buffer
has.
+
-See the <<channel-sub-buf-size-count,Sub-buffer size and count>> section
-below.
+See the ``<<channel-sub-buf-size-count,Sub-buffer size and count>>''
+section below.
* The size of each trace file LTTng writes for this channel and the
maximum count of trace files.
+
-See the <<channel-max-trace-file-size-count,Maximum trace file size and
-count>> section below.
+See the ``<<channel-max-trace-file-size-count,Maximum trace file size
+and count>>'' section below.
* The periods of its read, switch, and monitor timers.
+
-See the <<channel-timers,Timers>> section below.
+See the ``<<channel-timers,Timers>>'' section below.
* For a Linux kernel channel: its output type (man:mmap(2) or
man:splice(2)).
provided tracing domain.
A channel is always associated to a tracing domain (see the
-<<domain,{sect-domain}>> section below). The `java.util.logging` (JUL),
-log4j, and Python tracing domains each have a default channel which you
-can't configure.
+``<<domain,{sect-domain}>>'' section below). The `java.util.logging`
+(JUL), log4j, and Python tracing domains each have a default channel
+which you can't configure.
A channel owns recording event rules.
+
Since LTTng{nbsp}2.8, with this mode, LTTng writes to a given sub-buffer
its sequence number within its data stream. With a local, network
-streaming, or live tracing session (see the <<session-modes,Tracing
-session modes>> section above), a trace reader can use such sequence
+streaming, or live tracing session (see the ``<<session-modes,Tracing
+session modes>>'' section above), a trace reader can use such sequence
numbers to report lost packets. A trace reader can use the saved
discarded sub-buffer (packet) count of the trace to decide whether or
not to perform some analysis even if trace data is known to be missing.
command.
There are a few ways to decrease your probability of losing event
-records. The <<channel-sub-buf-size-count,Sub-buffer size and count>>
-section below shows how to fine-tune the sub-buffer size and count of a
-channel to virtually stop losing event records, though at the cost of
-greater memory usage.
+records. The ``<<channel-sub-buf-size-count,Sub-buffer size and
+count>>'' section below shows how to fine-tune the sub-buffer size and
+count of a channel to virtually stop losing event records, though at the
+cost of greater memory usage.
[[channel-sub-buf-size-count]]
~~~~~~~~~~~~~~~~~~~~~~~~~
A channel has one or more ring buffer for each CPU of the target system.
-See the <<channel-buf-scheme,Buffering scheme>> section above to learn
-how many ring buffers of a given channel are dedicated to each CPU
+See the ``<<channel-buf-scheme,Buffering scheme>>'' section above to
+learn how many ring buffers of a given channel are dedicated to each CPU
depending on its buffering scheme.
Set the size of each sub-buffer the ring buffers of a channel contain
event records.
+
Having larger sub-buffers also ensures a lower sub-buffer switching
-frequency (see the <<channel-timers,Timers>> section below).
+frequency (see the ``<<channel-timers,Timers>>'' section below).
+
The sub-buffer count is only meaningful if you create the channel in
-overwrite mode (see the <<channel-er-loss-mode,Event record loss mode>>
-section above): in this case, if LTTng overwrites a sub-buffer, then the
-other sub-buffers are left unaltered.
+overwrite mode (see the ``<<channel-er-loss-mode,Event record loss
+mode>>'' section above): in this case, if LTTng overwrites a sub-buffer,
+then the other sub-buffers are left unaltered.
Low event throughput::
In general, prefer smaller sub-buffers since the risk of losing
The only way to obtain an unmanaged, self-contained LTTng trace before
you destroy the tracing session is with the tracing session rotation
-feature (see the <<rotation,Tracing session rotation>> section above),
-which is available since LTTng{nbsp}2.11.
+feature (see the ``<<rotation,Tracing session rotation>>'' section
+above), which is available since LTTng{nbsp}2.11.
====
periodically in case of a low event throughput.
+
Such a timer is also convenient when you use large sub-buffers (see the
-<<channel-sub-buf-size-count,Sub-buffer size and count>> section above)
-to cope with a sporadic high event throughput, even if the throughput is
-otherwise low.
+``<<channel-sub-buf-size-count,Sub-buffer size and count>>'' section
+above) to cope with a sporadic high event throughput, even if the
+throughput is otherwise low.
+
Set the period of the switch timer of a channel, or disable the timer
altogether, with the nloption:--switch-timer option of the
for{nbsp}__C__ will never be satisfied.
--
+
-See the <<trigger,TRIGGER>> section above to learn more about triggers.
+See the ``<<trigger,TRIGGER>>'' section above to learn more about
+triggers.
+
Set the period of the monitor timer of a channel, or disable the timer
altogether, with the nloption:--monitor-timer option of the
{sect-recording-event-rule}
---------------------------
A _recording event rule_ is a specific type of event rule (see the
-<<"event-rule","{sect-event-rule}">> section above) of which the action is
-to serialize and record the matched event as an _event record_.
+``<<"event-rule","{sect-event-rule}">>'' section above) of which the
+action is to serialize and record the matched event as an _event
+record_.
Set the explicit conditions of a recording event rule when you create it
with the man:lttng-enable-event(1) command. A recording event rule also
+
A channel is enabled on creation.
+
-See the <<channel,{sect-channel}>> section above.
+See the ``<<channel,{sect-channel}>>'' section above.
* The tracing session of the recording event rule is active (started).
+
A tracing session is inactive (stopped) on creation.
+
-See the <<session,{sect-session}>> section above.
+See the ``<<session,{sect-session}>>'' section above.
* The process for which LTTng creates an event to match is allowed to
record events.
projects / lttng-tools.git / blobdiff