lttng-concepts(7)
=================
-:revdate: 3 May 2021
+:revdate: 14 June 2021
:sect-event-rule: INSTRUMENTATION POINT, EVENT RULE, AND EVENT
-:sect-session: TRACING SESSION
+:sect-session: RECORDING SESSION
:sect-domain: TRACING DOMAIN
:sect-channel: CHANNEL AND RING BUFFER
:sect-recording-event-rule: RECORDING EVENT RULE AND EVENT RECORD
* Instrumentation point, event rule, and event
* Trigger
-* Tracing session
+* Recording session
* Tracing domain
* Channel and ring buffer
* Recording event rule and event record
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 activity of the tracing session (started or stopped; see
- the <<session,{sect-session}>> section below).
+** The status of the channel (see the ``<<channel,{sect-channel}>>''
+ section below).
+** The activity of the recording session (started or stopped; see
+ 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
man:lttng-enable-event(1) command.
+
-List the recording event rules of a specific tracing session
+List the recording event rules of a specific recording session
and/or channel with the man:lttng-list(1) and man:lttng-status(1)
commands.
``Event rule matches'' <<trigger,trigger>> condition (since LTTng{nbsp}2.13)::
When the event rule of the trigger condition matches an event, LTTng
can execute user-defined actions such as sending an LTTng
- notification, starting a tracing session, and more.
+ notification, starting a recording session, and more.
+
See man:lttng-add-trigger(1) and man:lttng-event-rule(7).
* 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)
+* The consumed buffer size of a given recording
+ 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).
+* There's an ongoing recording session rotation (see the
+ ``<<rotation,Recording session rotation>>'' section below).
-* A tracing session rotation becomes completed.
+* A recording session rotation becomes completed.
* An event rule matches an event.
+
Actions::
+
* Send a notification to a user application.
-* Start a given tracing session, like man:lttng-start(1) would do.
-* Stop a given tracing session, like man:lttng-stop(1) would do.
-* Archive the current trace chunk of a given tracing session (rotate),
+* Start a given recording session, like man:lttng-start(1) would do.
+* Stop a given recording session, like man:lttng-stop(1) would do.
+* Archive the current trace chunk of a given recording session (rotate),
like man:lttng-rotate(1) would do.
-* Take a snapshot of a given tracing session, like man:lttng-snapshot(1)
- would do.
+* Take a snapshot of a given recording session, like
+ man:lttng-snapshot(1) would do.
A trigger belongs to a session daemon (see man:lttng-sessiond(8)), not
-to a specific tracing session. For a given session daemon, each Unix
+to a specific recording session. For a given session daemon, each Unix
user has its own, private triggers. Note, however, that the `root` Unix
user may, for the root session daemon:
[[session]]
{sect-session}
--------------
-A _tracing session_ is a stateful dialogue between you and a session
-daemon (see man:lttng-sessiond(8)) for everything related to event
-recording.
+A _recording session_ (named ``tracing session'' prior to
+LTTng{nbsp}2.13) is a stateful dialogue between you and a session daemon
+(see man:lttng-sessiond(8)) for everything related to event recording.
Everything that you do when you control LTTng tracers to record events
-happens within a tracing session. In particular, a tracing session:
+happens within a recording session. In particular, a recording session:
* Has its own name, unique for a given session daemon.
* 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).
+An active recording session is an implicit recording event rule
+condition (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,Recording 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)).
Those attributes and objects are completely isolated between different
-tracing sessions.
+recording sessions.
-A tracing session is like an ATM session: the operations you do on the
+A recording session is like an ATM session: the operations you do on the
banking system through the ATM don't alter the data of other users of
the same system. In the case of the ATM, a session lasts as long as your
-bank card is inside. In the case of LTTng, a tracing session lasts from
+bank card is inside. In the case of LTTng, a recording session lasts from
the man:lttng-create(1) command to the man:lttng-destroy(1) command.
-A tracing session belongs to a session daemon (see
+A recording session belongs to a session daemon (see
man:lttng-sessiond(8)). For a given session daemon, each Unix user has
-its own, private tracing sessions. Note, however, that the `root` Unix
-user may operate on or destroy another user's tracing session.
+its own, private recording sessions. Note, however, that the `root` Unix
+user may operate on or destroy another user's recording session.
-Create a tracing session with the man:lttng-create(1) command.
+Create a recording session with the man:lttng-create(1) command.
-List the tracing sessions of the connected session daemon with
+List the recording sessions of the connected session daemon with
the man:lttng-list(1) command.
-Start and stop a tracing session with the man:lttng-start(1) and
+Start and stop a recording session with the man:lttng-start(1) and
man:lttng-stop(1) commands.
-Save and load a tracing session with the man:lttng-save(1) and
+Save and load a recording session with the man:lttng-save(1) and
man:lttng-load(1) commands.
-Archive the current trace chunk of (rotate) a tracing session with the
+Archive the current trace chunk of (rotate) a recording session with the
man:lttng-rotate(1) command.
-Destroy a tracing session with the man:lttng-destroy(1) command.
+Destroy a recording session with the man:lttng-destroy(1) command.
-Current tracing session
+Current recording session
~~~~~~~~~~~~~~~~~~~~~~~
When you run the man:lttng-create(1) command, LTTng creates the
`$LTTNG_HOME/.lttngrc` file if it doesn't exist (`$LTTNG_HOME` defaults
to `$HOME`).
-`$LTTNG_HOME/.lttngrc` contains the name of the _current tracing
+`$LTTNG_HOME/.lttngrc` contains the name of the _current recording
session_.
-When you create a new tracing session with the `create` command, LTTng
-updates the current tracing session.
+When you create a new recording session with the `create` command, LTTng
+updates the current recording session.
-The following man:lttng(1) commands select the current tracing session
+The following man:lttng(1) commands select the current recording session
if you don't specify one:
* man:lttng-add-context(1)
* man:lttng-untrack(1)
* man:lttng-view(1)
-Set the current tracing session manually with the
+Set the current recording session manually with the
man:lttng-set-session(1) command, without having to edit the `.lttngrc`
file.
[[session-modes]]
-Tracing session modes
-~~~~~~~~~~~~~~~~~~~~~
-LTTng offers four tracing session modes:
+Recording session modes
+~~~~~~~~~~~~~~~~~~~~~~~
+LTTng offers four recording session modes:
Local mode::
Write the trace data to the local file system.
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:
+LTTng takes a snapshot of such a recording 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::
(see man:lttng-relayd(8)) for live reading.
+
An LTTng live reader (for example, man:babeltrace2(1)) can connect to
-the same relay daemon to receive trace data while the tracing session is
+the same relay daemon to receive trace data while the recording session is
active.
[[rotation]]
-Tracing session rotation
-~~~~~~~~~~~~~~~~~~~~~~~~
-A _tracing session rotation_ is the action of archiving the current
-trace chunk of the tracing session to the file system.
+Recording session rotation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+A _recording session rotation_ is the action of archiving the current
+trace chunk of the recording session to the file system.
Once LTTng archives a trace chunk, it does :not: manage it anymore: you
can read it, modify it, move it, or remove it.
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 _current trace chunk_ of a given recording session includes:
* The stream files which LTTng already wrote to the file system, and
which are not part of a previously archived trace chunk, since the
most recent event amongst:
-** The first time the tracing session was started, either with the
+** The first time the recording 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.
+ recording session.
[[trace-chunk-naming]]
Trace chunk archive naming
~~~~~~~~~~~~~~~~~~~~~~~~~~
A trace chunk archive is a subdirectory of the `archives` subdirectory
-within the output directory of a tracing session (see the
+within the output directory of a recording session (see the
nloption:--output option of the man:lttng-create(1) command and
of man:lttng-relayd(8)).
* A self-contained LTTng trace.
* A member of a set of trace chunk archives which form the complete
- trace of a tracing session.
+ trace of a recording session.
-In other words, an LTTng trace reader can read both the tracing
+In other words, an LTTng trace reader can read both the recording
session output directory (all the trace chunk archives), or a
single trace chunk archive.
-When LTTng performs a tracing session rotation, it names the resulting
+When LTTng performs a recording session rotation, it names the resulting
trace chunk archive as such, relative to the output directory of the
-tracing session:
+recording session:
[verse]
archives/__BEGIN__-__END__-__ID__
Example: `20180118T152407+0930`
__ID__::
- Unique numeric identifier of the trace chunk within its tracing
+ Unique numeric identifier of the trace chunk within its recording
session.
Trace chunk archive name example:
|Tracing domain |``Event rule matches'' trigger condition option |Option for other CLI commands
|Linux kernel
-|nloption:--domain=++kernel++
+|nloption:--type option starts with `kernel:`
|nloption:--kernel
|User space
-|nloption:--domain=++user++
+|nloption:--type option starts with `user:`
|nloption:--userspace
|`java.util.logging` (JUL)
-|nloption:--domain=++jul++
+|nloption:--type option starts with `jul:`
|nloption:--jul
|Apache log4j
-|nloption:--domain=++log4j++
+|nloption:--type option starts with `log4j:`
|nloption:--log4j
|Python
-|nloption:--domain=++python++
+|nloption:--type option starts with `python:`
|nloption:--python
|===
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.
-List the channels of a given tracing session with the
+List the channels of a given recording session with the
man:lttng-list(1) and man:lttng-status(1) commands.
Disable an enabled channel with the man:lttng-disable-channel(1)
+
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
-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.
+streaming, or live recording session (see the
+``<<session-modes,Recording 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.
+
With this mode, LTTng doesn't write to the trace the exact number of
lost event records in the lost sub-buffers.
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
[IMPORTANT]
====
Even if you don't limit the trace file count, always assume that LTTng
-manages all the trace files of the tracing session.
+manages all the trace files of the recording session.
In other words, there's no safe way to know if LTTng still holds a given
trace file open with the trace file rotation feature.
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.
+you destroy the recording session is with the recording session rotation
+feature (see the ``<<rotation,Recording 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
Monitor timer::
When this timer expires, the consumer daemon samples some channel
- (see the <<channel,{sect-channel}>> section above)
statistics to evaluate the following trigger conditions:
+
--
-. The consumed buffer size of a given tracing session becomes greater
+. The consumed buffer size of a given recording session becomes greater
than some value.
. The buffer usage of a given channel becomes greater than some value.
. The buffer usage of a given channel becomes less than some value.
If you disable the monitor timer of a channel{nbsp}__C__:
+
--
-* The consumed buffer size value of the tracing session of{nbsp}__C__
+* The consumed buffer size value of the recording session of{nbsp}__C__
could be wrong for trigger condition type{nbsp}1: the consumed buffer
size of{nbsp}__C__ won't be part of the grand total.
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).
+* The recording session of the recording event rule is active (started).
+
-A tracing session is inactive (stopped) on creation.
+A recording 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.
+
-All processes are allowed to record events on tracing session
+All processes are allowed to record events on recording session
creation.
+
Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
attributes.
You always attach a recording event rule to a channel, which belongs to
-a tracing session, when you create it.
+a recording session, when you create it.
When a recording event rule{nbsp}__ER__ matches an event{nbsp}__E__,
LTTng attempts to serialize and record{nbsp}__E__ to one of the
$ lttng enable-event --userspace hello:world --loglevel=INFO
----
-List the recording event rules of a specific tracing session
+List the recording event rules of a specific recording session
and/or channel with the man:lttng-list(1) and man:lttng-status(1)
commands.
command.
As of LTTng{nbsp}{lttng_version}, you cannot remove a recording event
-rule: it exists as long as its tracing session exists.
+rule: it exists as long as its recording session exists.
include::common-footer.txt[]
projects / lttng-tools.git / blobdiff