# Command short descriptions
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to be recorded])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_TRIGGER], [Add a trigger])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CLEAR], [Clear a tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Destroy tracing sessions])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CLEAR], [Clear a recording session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a recording session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Destroy recording sessions])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_CHANNEL], [Disable channels])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_EVENT], [Disable recording event rules])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a tracing session rotation schedule])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a recording session rotation schedule])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_CHANNEL], [Create or enable a channel])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_EVENT], [Create or enable recording event rules])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a tracing session rotation schedule])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a recording session rotation schedule])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_HELP], [Show the help of a command])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing sessions and instrumentation points])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List recording sessions and instrumentation points])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST_TRIGGERS], [List triggers])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load tracing session configurations])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Regenerate specific tracing session data])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load recording session configurations])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Regenerate specific recording session data])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REMOVE_TRIGGER], [Remove a trigger])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive the current trace chunk of a tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save tracing session configurations])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set the current tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a tracing session snapshot])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start a tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Show the status of the current tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop a tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive the current trace chunk of a recording session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save recording session configurations])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set the current recording session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a recording session snapshot])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start a recording session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Show the status of the current recording session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop a recording session])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Allow specific processes to record events])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Disallow specific processes to record events])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VERSION], [Show LTTng-tools version information])
nloption:--help option) instead of `/usr/bin/man`.
`LTTNG_SESSION_CONFIG_XSD_PATH`::
- Path to the directory containing the `session.xsd` tracing session
+ Path to the directory containing the `session.xsd` recording session
configuration XML schema.
`LTTNG_SESSIOND_PATH`::
`$LTTNG_HOME/.lttngrc`::
Unix user's LTTng runtime configuration.
+
-This is where LTTng stores the name of the Unix user's current tracing
+This is where LTTng stores the name of the Unix user's current recording
session between executions of man:lttng(1). man:lttng-create(1) and
-man:lttng-set-session(1) set the current tracing session.
+man:lttng-set-session(1) set the current recording session.
`$LTTNG_HOME/lttng-traces`::
Default output directory of LTTng traces in local and snapshot
Unix user's LTTng runtime and configuration directory.
`$LTTNG_HOME/.lttng/sessions`::
- Default directory containing the Unix user's saved tracing session
+ Default directory containing the Unix user's saved recording session
configurations (see man:lttng-save(1) and man:lttng-load(1)).
+{system_sessions_dir}+::
- Directory containing the system-wide saved tracing session
+ Directory containing the system-wide saved recording session
configurations (see man:lttng-save(1) and man:lttng-load(1)).
NOTE: `$LTTNG_HOME` defaults to the value of the `HOME` environment
lttng-add-context(1)
====================
-:revdate: 6 May 2021
+:revdate: 14 June 2021
NAME
records of:
+
With the option:--session='SESSION' option:::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option:::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
With the option:--channel='CHANNEL':::
The channel named 'CHANNEL'.
Without the option:--channel option:::
- *All* the channels of the selected tracing session.
+ *All* the channels of the selected recording session.
With the option:--list option::
List the available context field types.
-See man:lttng-concepts(7) to learn more about tracing sessions and
+See man:lttng-concepts(7) to learn more about recording sessions and
channels.
Repeat the option:--type='TYPE' option to add more than one context
variable substitution in most shells.
NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
-to be recorded to the event records of a given channel once its tracing
-session has been started (see man:lttng-start(1)) at least once.
+to be recorded to the event records of a given channel once its
+recording session has been started (see man:lttng-start(1)) at least
+once.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
option:-c 'CHANNEL', option:--channel='CHANNEL'::
Add context fields to be recorded to the event records of a channel
named 'CHANNEL' instead of all the channels of the selected
- tracing session.
+ recording session.
option:-s 'SESSION', option:--session='SESSION'::
Add context fields to be recorded to the event records of one or
- more channels of the tracing session named 'SESSION' instead of the
- current tracing session.
+ more channels of the recording session named 'SESSION' instead of
+ the current recording session.
Context field type
----
====
-.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session.
+.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session.
====
[role="term"]
----
----
====
-.Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session.
+.Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session.
====
See the option:--session and option:--channel options.
----
====
-.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session.
+.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session.
====
See the option:--channel option.
----
====
-.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session.
+.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session.
====
[role="term"]
----
lttng-add-trigger(1)
====================
-:revdate: 18 May 2021
+:revdate: 14 June 2021
NAME
+
See below for the nloption:--rate-policy option.
-Start a tracing session::
+Start a recording session::
Synopsis:
+
[verse]
option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
-Starts the tracing session named 'SESSION' like man:lttng-start(1)
+Starts the recording session named 'SESSION' like man:lttng-start(1)
would.
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+If no recording session has the name 'SESSION' when LTTng is ready to
execute the action, LTTng does nothing.
+
See below for the nloption:--rate-policy option.
-Stop a tracing session::
+Stop a recording session::
Synopsis:
+
[verse]
option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
-Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
+Stops the recording session named 'SESSION' like man:lttng-stop(1)
+would.
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+If no recording session has the name 'SESSION' when LTTng is ready to
execute the action, LTTng does nothing.
+
See below for the nloption:--rate-policy option.
-Rotate a tracing session::
+Rotate a recording session::
Synopsis:
+
[verse]
option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
-Archives the current trace chunk of the tracing session named 'SESSION'
-like man:lttng-rotate(1) would.
+Archives the current trace chunk of the recording session named
+'SESSION' like man:lttng-rotate(1) would.
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+If no recording session has the name 'SESSION' when LTTng is ready to
execute the action, LTTng does nothing.
+
See below for the nloption:--rate-policy option.
-Take a tracing session snapshot::
+Take a recording session snapshot::
Synopsis:
+
[verse]
option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
-Takes a snapshot of the tracing session named 'SESSION' like
+Takes a snapshot of the recording session named 'SESSION' like
man:lttng-snapshot(1) would.
+
-When the condition of the trigger is satisfied, the tracing session
-named 'SESSION', if any, must be a snapshot-mode tracing session
+When the condition of the trigger is satisfied, the recording session
+named 'SESSION', if any, must be a snapshot-mode recording session
(see man:lttng-create(1)).
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+If no recording session has the name 'SESSION' when LTTng is ready to
execute the action, LTTng does nothing.
+
See below for the nloption:--rate-policy option.
----
====
-.Add an ``event rule matches'' trigger of which the action is to stop a tracing session and then rotate it.
+.Add an ``event rule matches'' trigger of which the action is to stop a recording session and then rotate it.
====
The `event-rule-matches` trigger condition below specifies an event rule
which matches any user space tracepoint event with a name starting with
--action=rotate-session my-session
----
-See man:lttng-concepts(7) to learn more about tracing sessions and
+See man:lttng-concepts(7) to learn more about recording sessions and
rotations.
====
----
====
-.Add an ``event rule matches'' trigger with a tracing session starting action to be executed a single time after 40{nbsp}times.
+.Add an ``event rule matches'' trigger with a recording session starting action to be executed a single time after 40{nbsp}times.
====
The `event-rule-matches` trigger condition below specifies an event rule
which matches any Linux system call event (entry and exit) of which the
lttng-clear(1)
==============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-clear - Clear an LTTng tracing session
+lttng-clear - Clear an LTTng recording session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng clear` command clears one or more tracing sessions, that is,
-it deletes the contents of their tracing buffers and of all their local
-and streamed trace data.
+The `lttng clear` command clears one or more recording sessions, that
+is, it deletes the contents of their recording buffers and of all their
+local and streamed trace data.
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
The `clear` command clears:
Without any option::
- The current tracing session.
+ The current recording session.
+
-See man:lttng-concepts(7) to learn more about the current tracing
+See man:lttng-concepts(7) to learn more about the current recording
session.
With the 'SESSION' argument::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
With the option:--all option::
- *All* the tracing sessions of the connected session daemon for your
- Unix user, or for all users if your Unix user is `root`, as listed
- in the output of `lttng list` (see man:lttng-list(1)).
+ *All* the recording sessions of the connected session daemon for
+ your Unix user, or for all users if your Unix user is `root`, as
+ listed in the output of `lttng list` (see man:lttng-list(1)).
+
See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.
-If a tracing session is configured in snapshot mode (see the
+If a recording session is configured in snapshot mode (see the
nloption:--snapshot option of the man:lttng-create(1) command), the
-`clear` command only clears the tracing buffers.
+`clear` command only clears the recording buffers.
-For a given tracing session, if at least one rotation occurred (see
-man:lttng-concepts(7)), the `clear` command only clears its tracing
+For a given recording session, if at least one rotation occurred (see
+man:lttng-concepts(7)), the `clear` command only clears its recording
buffers and its current trace chunk, :not: its archived trace chunks.
NOTE: The nloption:--disallow-clear option and the
`LTTNG_RELAYD_DISALLOW_CLEAR` environment variable of
man:lttng-relayd(8) can disable remote clearing operations. If LTTng
-sends tracing data over the network for the selected tracing session(s)
-to an LTTng relay daemon configured as such, the `clear` command fails.
+sends recording data over the network for the selected recording
+session(s) to an LTTng relay daemon configured as such, the `clear`
+command fails.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
Recording target
~~~~~~~~~~~~~~~~
option:-a, option:--all::
- Clear all the tracing sessions of your Unix user, or of all users if
+ Clear all the recording sessions of your Unix user, or of all users if
your Unix user is `root`, as listed in the output of
- man:lttng-list(1), instead of the current tracing session or the
- tracing session named 'SESSION'.
+ man:lttng-list(1), instead of the current recording session or the
+ recording session named 'SESSION'.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Clear the current tracing session.
+.Clear the current recording session.
====
[role="term"]
----
----
====
-.Clear a specific tracing session.
+.Clear a specific recording session.
====
[role="term"]
----
----
====
-.Clear all tracing sessions.
+.Clear all recording sessions.
====
See the option:--all option.
lttng-concepts(7)
=================
-:revdate: 18 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
** 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 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)).
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).
Conditions::
+
-* The consumed buffer size of a given tracing
+* 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 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
+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 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.
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.
(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.
``<<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).
``<<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:
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.
[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
+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.
====
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.
+
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.
* 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[]
lttng-crash(1)
==============
-:revdate: 3 May 2021
+:revdate: 14 June 2021
NAME
'SHMDIR' is the directory specified as the argument of the
nloption:--shm-path option of the man:lttng-create(1) command used to
-create the tracing session for which to recover the traces.
+create the recording session for which to recover the traces.
OPTIONS
lttng-create(1)
===============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-create - Create an LTTng tracing session
+lttng-create - Create an LTTng recording session
SYNOPSIS
--------
-Create a local mode tracing session:
+Create a local mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
[option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
-Create a network streaming mode tracing session:
+Create a network streaming mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
(option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
-Create a snapshot mode tracing session:
+Create a snapshot mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot [option:--shm-path='DIR']
[option:--no-output | option:--output='DIR' | option:--set-url='URL' |
option:--ctrl-url='URL' option:--data-url='URL']
-Create a live mode tracing session:
+Create a live mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
DESCRIPTION
-----------
-The `lttng create` command creates a new tracing session for your Unix
+The `lttng create` command creates a new recording session for your Unix
user within the connected session daemon (see the ``Session daemon
connection'' section of man:lttng(1) to learn how a user application
connects to a session daemon).
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
-Without the 'SESSION' argument, LTTng automatically generates a tracing
+Without the 'SESSION' argument, LTTng automatically generates a recording
session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may
:not: contain the character `/`.
Override the path of the relay daemon binary to spawn with the general
genoption:--relayd-path option.
-On success, the `create` command sets the current tracing session (see
-man:lttng-concepts(7) to learn more) to the created tracing session.
+On success, the `create` command sets the current recording session (see
+man:lttng-concepts(7) to learn more) to the created recording session.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-Show the status of the current tracing session with the
+Show the status of the current recording session with the
man:lttng-status(1) command.
-List the tracing sessions of your Unix user, or of all users if
+List the recording sessions of your Unix user, or of all users if
your Unix user is `root`, within 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.
Allow and disallow specific processes to record events with the
man:lttng-track(1) and man:lttng-untrack(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.
[[modes]]
-Tracing session modes
-~~~~~~~~~~~~~~~~~~~~~
-As documented in man:lttng-concepts(7), LTTng offers four tracing
+Recording session modes
+~~~~~~~~~~~~~~~~~~~~~~~
+As documented in man:lttng-concepts(7), LTTng offers four recording
session modes:
[[local-mode]]Local mode::
Otherwise:::
A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
defaults to `$HOME`) directory, of which the name contains the
- tracing session name and the date/time.
+ recording session name and the date/time.
[[network-streaming-mode]]Network streaming mode::
Send the trace data over the network to a listening relay daemon
With this mode, LTTng:
+
With the option:--no-output option:::
- Does :not: add any snapshot output to the created tracing
+ Does :not: add any snapshot output to the created recording
session.
With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
Adds a snapshot output named `snapshot-1` using the provided
- path or URL(s) to the created tracing session.
+ path or URL(s) to the created recording session.
Otherwise:::
Adds an automatic snapshot output named `snapshot-1` to the created
- tracing session.
+ recording session.
+
The automatic snapshot output is a subdirectory, under the
`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
-directory, of which the name contains the tracing session name and the
+directory, of which the name contains the recording session name and the
date/time.
[[live-mode]]Live mode (option:--live option)::
{nbsp}
+
The `file://` protocol targets the *local file system*: you may only use
-such an URL with the option:--set-url option when you create the tracing
-session in local or snapshot mode (see the ``<<modes,Tracing session
-modes>>'' section above).
+such an URL with the option:--set-url option when you create the
+recording session in local or snapshot mode (see the ``<<modes,Recording
+session modes>>'' section above).
+
'TRACEDIR':::
Absolute path to the directory containing the trace data on the
'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
{nbsp}
+
-This format is only available when you create the tracing session in
+This format is only available when you create the recording session in
network streaming, snapshot (option:--snapshot), or live (option:--live)
-mode (see the ``<<modes,Tracing session modes>>'' section above).
+mode (see the ``<<modes,Recording session modes>>'' section above).
+
'NETPROTO':::
Network protocol, amongst:
Mode selection
~~~~~~~~~~~~~~
-See the ``<<modes,Tracing session modes>>'' section above.
+See the ``<<modes,Recording session modes>>'' section above.
At most one of:
option:--live[='DELAYUS']::
- Create the tracing session in live mode.
+ Create the recording session in live mode.
+
The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
for the data to be flushed (sent to the connected LTTng relay daemon).
(see man:lttng-relayd(8)).
option:--snapshot::
- Create the tracing session in snapshot mode.
+ Create the recording session in snapshot mode.
+
This is equivalent to:
+
+
--
With the option:--no-output option::
- Not adding any snapshot output after LTTng creates the tracing
+ Not adding any snapshot output after LTTng creates the recording
session.
With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
Adding a snapshot output named `snapshot-1` using the provided path
- or URL(s) immediately after LTTng creates the tracing session.
+ or URL(s) immediately after LTTng creates the recording session.
Otherwise::
Adding an automatic snapshot output named `snapshot-1` immediately
- after LTTng creates the tracing session.
+ after LTTng creates the recording session.
+
The automatic snapshot output is a subdirectory, under the
`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
-directory, of which the name contains the tracing session name and the
+directory, of which the name contains the recording session name and the
date/time.
--
-* Forcing all the channels to be created for the tracing session to be
+* Forcing all the channels to be created for the recording session to be
configured with the nloption:--override and nloption:--output=++mmap++
options (see man:lttng-enable-channel(1)).
Output
~~~~~~
option:--no-output::
- Depending on the tracing session mode (see the ``<<modes,Tracing
+ Depending on the recording session mode (see the ``<<modes,Recording
session modes>>'' section above):
+
Local mode:::
Disable the file system output.
Snapshot mode (option:--snapshot option):::
- Do :not: add a snapshot output after creating the tracing session.
+ Do :not: add a snapshot output after creating the recording session.
option:-o 'DIR', option:--output='DIR'::
Equivalent to option:--set-url=++file://++__DIR__.
+
You must also use the option:--data-url option.
+
-Not available in local mode (see the ``<<modes,Tracing session modes>>''
-section above).
+Not available in local mode (see the ``<<modes,Recording session
+modes>>'' section above).
+
In snapshot mode, this is equivalent to using the nloption:--ctrl-url
option of the `add-output` action of the man:lttng-snapshot(1) command
-immediately after creating the tracing session.
+immediately after creating the recording session.
option:-D 'URL', option:--data-url='URL'::
Set the trace data path URL to 'URL'.
+
You must also use the option:--ctrl-url option.
+
-Not available in local mode (see the ``<<modes,Tracing session modes>>''
-section above).
+Not available in local mode (see the ``<<modes,Recording session
+modes>>'' section above).
+
In snapshot mode, this is equivalent to using the nloption:--data-url
option of the `add-output` action of the man:lttng-snapshot(1) command
-immediately after creating the tracing session.
+immediately after creating the recording session.
option:-U 'URL', option:--set-url='URL'::
Set the destination URL of the control path and trace data to 'URL'.
+
-This URL remains unchanged as long as the tracing session exists.
+This URL remains unchanged as long as the recording session exists.
+
-Depending on the tracing session mode (see the ``<<modes,Tracing session
-modes>>'' section above):
+Depending on the recording session mode (see the ``<<modes,Recording
+session modes>>'' section above):
+
Local mode:::
'URL' must start with `file://`, followed with the destination
Snapshot mode (option:--snapshot option):::
Equivalent to using the 'URL' non-option argument of the
`add-output` action of the man:lttng-snapshot(1) command immediately
- after creating the tracing session.
+ after creating the recording session.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Create a normal mode tracing session with a generated name.
+.Create a normal mode recording session with a generated name.
====
[role="term"]
----
----
====
-.Create a normal mode tracing session with a custom name.
+.Create a normal mode recording session with a custom name.
====
[role="term"]
----
----
====
-.Create a normal mode tracing session with a specific output directory.
+.Create a normal mode recording session with a specific output directory.
====
See the option:--output option.
----
====
-.Create a network streaming mode tracing session.
+.Create a network streaming mode recording session.
====
See the ``Output directory'' section of man:lttng-relayd(8) to
understand where the relay daemon to connect to (`10.0.0.242`) writes
----
====
-.Create a snapshot mode tracing session with a default snapshot output.
+.Create a snapshot mode recording session with a default snapshot output.
====
See the option:--snapshot option.
----
====
-.Create a snapshot mode tracing session with a custom snapshot output.
+.Create a snapshot mode recording session with a custom snapshot output.
====
See the option:--snapshot and option:--set-url options.
----
====
-.Create a snapshot mode tracing session with no snapshot output.
+.Create a snapshot mode recording session with no snapshot output.
====
See the option:--snapshot and option:--no-output options.
----
====
-.Create an LTTng live mode tracing session with a default relay daemon URL.
+.Create an LTTng live mode recording session with a default relay daemon URL.
====
See the option:--live option.
----
====
-.Create an LTTng live mode tracing session with a custom live timer period and relay daemon URL.
+.Create an LTTng live mode recording session with a custom live timer period and relay daemon URL.
====
See the option:--live and option:--set-url options.
----
====
-.Create a normal mode tracing session with a custom directory containing the ring buffer shared memory files.
+.Create a normal mode recording session with a custom directory containing the ring buffer shared memory files.
====
See the option:--shm-path option.
lttng-destroy(1)
================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-destroy - Destroy LTTng tracing sessions
+lttng-destroy - Destroy LTTng recording sessions
SYNOPSIS
The `lttng destroy` command destroys:
With the 'SESSION' argument::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
With the option:--all option::
- *All* the tracing sessions of the connected session daemon for your
- Unix user, or for all users if your Unix user is `root`, as listed
- in the output of `lttng list` (see man:lttng-list(1)).
+ *All* the recording sessions of the connected session daemon for
+ your Unix user, or for all users if your Unix user is `root`, as
+ listed in the output of `lttng list` (see man:lttng-list(1)).
+
See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.
Otherwise::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
+
-In that case, the current tracing session becomes nonexistent.
+In that case, the current recording session becomes nonexistent.
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
-``Destroying'' a tracing session means freeing the resources which the
+``Destroying'' a recording session means freeing the resources which the
LTTng daemons and tracers acquired for it, also making sure to flush all
the recorded trace data to either the local file system or the connected
-LTTng relay daemon (see man:lttng-relayd(8)), depending on the tracing
+LTTng relay daemon (see man:lttng-relayd(8)), depending on the recording
session mode.
-The `destroy` command stops any tracing activity within the selected
-tracing session(s). By default, the command runs an implicit
-man:lttng-stop(1) command to ensure that the trace data of the tracing
+The `destroy` command stops any recording activity within the selected
+recording session(s). By default, the command runs an implicit
+man:lttng-stop(1) command to ensure that the trace data of the recording
session(s) is valid before it exits. Make the command exit immediately
with the option:--no-wait option. In this case, however, the traces(s)
might not be valid when the command exits, and there's no way to know
when it/they become valid.
-If, for a tracing session{nbsp}__TS__ to destroy with the `destroy`
+If, for a recording session{nbsp}__RS__ to destroy with the `destroy`
command, the following statements are true:
* You don't specify the option:--no-wait option.
* LTTng archived the current trace chunk (see man:lttng-concepts(7))
- of{nbsp}__TS__ at least once during its lifetime.
+ of{nbsp}__RS__ at least once during its lifetime.
-Then all the subdirectories of the output directory of{nbsp}__TS__
+Then all the subdirectories of the output directory of{nbsp}__RS__
(local or remote) are considered trace chunk archives once the `destroy`
command exits. In other words, it's safe to read them, modify them, move
them, or remove then.
option:-a, option:--all::
- Destroy all the tracing sessions of your Unix user, or of all users
- if your Unix user is `root`, as listed in the output of
- man:lttng-list(1), instead of the current tracing session or the
- tracing session named 'SESSION'.
+ Destroy all the recording sessions of your Unix user, or of all
+ users if your Unix user is `root`, as listed in the output of
+ man:lttng-list(1), instead of the current recording session or the
+ recording session named 'SESSION'.
option:-n, option:--no-wait::
- Do :not: ensure that the trace data of the tracing session(s) to
+ Do :not: ensure that the trace data of the recording session(s) to
destroy is valid before exiting.
[[examples]]
EXAMPLES
--------
-.Destroy the current tracing session.
+.Destroy the current recording session.
====
[role="term"]
----
----
====
-.Destroy the current tracing session without waiting for completion.
+.Destroy the current recording session without waiting for completion.
====
See the option:--no-wait option.
----
====
-.Destroy a specific tracing session.
+.Destroy a specific recording session.
====
[role="term"]
----
----
====
-.Destroy all tracing sessions.
+.Destroy all recording sessions.
====
See the option:--all option.
lttng-disable-channel(1)
========================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
+
NAME
----
which belong to:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
See man:lttng-concepts(7) to learn more about channels.
argument.
As of LTTng{nbsp}{lttng_version}, you may :not: enable a disabled
-channel once its tracing session has been started (see
+channel once its recording session has been started (see
man:lttng-start(1)) at least once.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Disable one or more channels of the tracing session named 'SESSION'
- instead of the current tracing session.
+ Disable one or more channels of the recording session named
+ 'SESSION' instead of the current recording session.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Disable one Linux kernel channel of the current tracing session.
+.Disable one Linux kernel channel of the current recording session.
====
[role="term"]
----
----
====
-.Disable two user space channels of a specific tracing session.
+.Disable two user space channels of a specific recording session.
====
See the option:--session option.
lttng-disable-event(1)
======================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
command which belong to:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
With the option:--channel='CHANNEL' option::
The channel named 'CHANNEL'.
Without the option:--channel option::
The channel named `channel0`.
+
-If there's more than one channel for the selected tracing session and
+If there's more than one channel for the selected recording session and
domain, the `disable-event` command fails.
See man:lttng-concepts(7) to learn more about recording event rules.
kernel recording event rules regardless of their instrumentation point
type.
-List the recording event rules of a given tracing session
+List the recording event rules of a given recording session
and/or channel with the man:lttng-list(1) command.
Without the option:--all-events option, the `disable-event` command
man:lttng-list(1)).
You may disable an enabled recording event rule regardless of the
-activity (started or stopped) of its tracing session (see
+activity (started or stopped) of its recording session (see
man:lttng-start(1) and man:lttng-stop(1)).
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
'CHANNEL' instead of `channel0`.
option:-s 'SESSION', option:--session='SESSION'::
- Disable recording event rules in the tracing session named 'SESSION'
- instead of the current tracing session.
+ Disable recording event rules in the recording session named
+ 'SESSION' instead of the current recording session.
Instrumentation point type condition
[[examples]]
EXAMPLES
--------
-.Disable all Linux kernel tracepoint recording event rules in the default channel of the current tracing session.
+.Disable all Linux kernel tracepoint recording event rules in the default channel of the current recording session.
====
See the option:--all-events option.
----
====
-.Disable specific Apache log4j recording event rules in the default channel of a specific tracing session.
+.Disable specific Apache log4j recording event rules in the default channel of a specific recording session.
====
See the option:--session option.
----
====
-.Disable all user space recording event rules in a specific channel of the current tracing session.
+.Disable all user space recording event rules in a specific channel of the current recording session.
====
See the option:--channel option.
----
====
-.Disable specific Linux kernel system call recording event rules in the default channel of the current tracing session.
+.Disable specific Linux kernel system call recording event rules in the default channel of the current recording session.
====
[role="term"]
----
lttng-disable-rotation(1)
=========================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-disable-rotation - Unset an LTTng tracing session rotation schedule
+lttng-disable-rotation - Unset an LTTng recording session rotation schedule
SYNOPSIS
previously set with the man:lttng-enable-rotation(1) command, for:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-See man:lttng-concepts(7) to learn more about the tracing session
+See man:lttng-concepts(7) to learn more about the recording session
rotation and trace chunk concepts.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Unset a rotation schedule for the tracing session named 'SESSION'
- instead of the current tracing session.
+ Unset a rotation schedule for the recording session named 'SESSION'
+ instead of the current recording session.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Unset the size-based rotation schedule of the current tracing session.
+.Unset the size-based rotation schedule of the current recording session.
====
See the option:--size option.
----
====
-.Unset the periodic rotation schedule of a specific tracing session.
+.Unset the periodic rotation schedule of a specific recording session.
====
See the option:--timer and option:--session options.
lttng-enable-channel(1)
=======================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
The channel(s) to create or enable belong to:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
NOTE: The man:lttng-enable-event(1) command can automatically create a
default channel when no channel exists for the provided tracing domain.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-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)
* Change an attribute of an existing channel.
-* Enable a disabled channel once its tracing session has been active
+* Enable a disabled channel once its recording session has been active
(started; see man:lttng-start(1)) at least once.
-* Create a channel once its tracing session has been active at least
+* Create a channel once its recording session has been active at least
once.
* Create a user space channel with a given buffering scheme
(option:--buffers-uid or option:--buffers-pid options) and create a
second user space channel with a different buffering scheme in the
- same tracing session.
+ same recording session.
====
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Create or enable channels in the tracing session named 'SESSION'
- instead of the current tracing session.
+ Create or enable channels in the recording session named 'SESSION'
+ instead of the current recording session.
Buffering scheme
[[examples]]
EXAMPLES
--------
-.Create a Linux kernel channel with default attributes in the current tracing session.
+.Create a Linux kernel channel with default attributes in the current recording session.
====
The following command line only creates a new channel if `my-channel`
-doesn't name an existing Linux kernel channel in the current tracing
+doesn't name an existing Linux kernel channel in the current recording
session.
[role="term"]
----
====
-.Create a user space channel with a per-process buffering scheme in a specific tracing session.
+.Create a user space channel with a per-process buffering scheme in a specific recording session.
====
See the option:--session and option:--buffers-pid options.
----
====
-.Create a Linux kernel channel in the current tracing session with four 32-MiB sub-buffers per ring buffer.
+.Create a Linux kernel channel in the current recording session with four 32-MiB sub-buffers per ring buffer.
====
See the option:--num-subbuf and option:--subbuf-size options.
----
====
-.Create a user space channel in the current tracing session with trace file rotation.
+.Create a user space channel in the current recording session with trace file rotation.
====
See the option:--tracefile-count and option:--tracefile-size options.
----
====
-.Enable two user space channels of a specific tracing session.
+.Enable two user space channels of a specific recording session.
====
[role="term"]
----
lttng-enable-event(1)
=====================
-:revdate: 25 May 2021
+:revdate: 14 June 2021
NAME
The recording event rule(s) to create or enable belong to:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
With the option:--channel='CHANNEL' option::
The channel named 'CHANNEL'.
Without the option:--channel option::
The channel named `channel0`.
+
-If there's already a channel for the selected tracing session and domain
-which isn't named `channel0`, the `enable-event` command fails.
+If there's already a channel for the selected recording session and
+domain which isn't named `channel0`, the `enable-event` command fails.
Otherwise, it automatically creates it.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-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.
+
Enable a disabled channel with the man:lttng-enable-channel(1) command.
-* The tracing session of{nbsp}__ER__ is active (started).
+* The recording session of{nbsp}__ER__ is active (started).
+
-A tracing session is inactive (stopped) on creation.
+A recording session is inactive (stopped) on creation.
+
-Start an inactive tracing session with the man:lttng-start(1) command.
+Start an inactive recording session with the man:lttng-start(1) command.
* The process for which LTTng creates{nbsp}__E__ 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
as listed in the output of the man:lttng-list(1) command.
You may enable a disabled recording event rule regardless of the
-activity (started or stopped) of its tracing session (see
+activity (started or stopped) of its recording session (see
man:lttng-start(1) and man:lttng-stop(1)).
To enable a disabled recording event rule, run the `enable-event`
'CHANNEL' instead of `channel0`.
option:-s 'SESSION', option:--session='SESSION'::
- Create or enable recording event rules in the tracing session named
- 'SESSION' instead of the current tracing session.
+ Create or enable recording event rules in the recording session
+ named 'SESSION' instead of the current recording session.
Instrumentation point type condition
[[examples]]
EXAMPLES
--------
-.Create a recording event rule which matches all Linux system call events (current tracing session, default channel).
+.Create a recording event rule which matches all Linux system call events (current recording session, default channel).
====
See the option:--all and option:--syscall options.
----
====
-.Create a recording event rule which matches user space tracepoint events named specifically (current tracing session, default channel).
+.Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel).
====
The recording event rule below matches all user space tracepoint events
of which the name starts with `my_provider:msg`.
----
====
-.Create three recording event rules which match Python logging events named specifically (current tracing session, default channel).
+.Create three recording event rules which match Python logging events named specifically (current recording session, default channel).
====
[role="term"]
----
----
====
-.Create a recording event rule which matches Apache log4j logging events with a specific log level range (current tracing session, specific channel).
+.Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel).
====
See the option:--channel, option:--all, and option:--loglevel options.
----
====
-.Create a recording event rule which matches specific Linux kprobe events (current tracing session, default channel).
+.Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel).
====
The recording event rule below matches the entry of `usb_disconnect()`
Linux kernel function calls. The records of such events are named `usbd`
----
====
-.Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific tracing session, default channel).
+.Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel).
====
See the option:--session and option:--filter options.
----
====
-.Enable two Linux kernel tracepoint recording event rules (current tracing session, specific channel).
+.Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel).
====
See the option:--channel option.
lttng-enable-rotation(1)
========================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-enable-rotation - Set an LTTng tracing session rotation schedule
+lttng-enable-rotation - Set an LTTng recording session rotation schedule
SYNOPSIS
DESCRIPTION
-----------
-The `lttng enable-rotation` command sets a tracing session rotation
+The `lttng enable-rotation` command sets a recording session rotation
schedule for:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn more
+ about the current recording session).
-See man:lttng-concepts(7) to learn more about the tracing session
+See man:lttng-concepts(7) to learn more about the recording session
rotation and trace chunk concepts.
With the option:--timer='PERIODUS' option, the `enable-rotation` command
For both the option:--timer and option:--size options, LTTng checks the
schedule condition periodically using the monitor timers of the channels
-of the selected tracing session (see the nloption:--monitor-timer option
-of the man:lttng-enable-channel(1) command). This means that:
+of the selected recording session (see the nloption:--monitor-timer
+option of the man:lttng-enable-channel(1) command). This means that:
* With the option:--timer='PERIODUS' option, LTTng can perform an
automatic rotation when the elapsed time since the last automatic
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-Unset a tracing session rotation schedule with the
+Unset a recording session rotation schedule with the
man:lttng-disable-rotation(1) command.
[IMPORTANT]
====
You may only use the `enable-rotation` command when:
-* The selected tracing session was created in normal mode or in network
- streaming mode (see man:lttng-create(1)).
+* The selected recording session was created in normal mode or in
+ network streaming mode (see man:lttng-create(1)).
* No channel was created with a configured trace file count or size
limit (see the nloption:--tracefile-size and
nloption:--tracefile-count options of the man:lttng-enable-channel(1)
command).
-For a given tracing session, LTTng only performs an automatic rotation
+For a given recording session, LTTng only performs an automatic rotation
when it's not currently performing a rotation.
====
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Set a rotation schedule for the tracing session named 'SESSION'
- instead of the current tracing session.
+ Set a rotation schedule for the recording session named 'SESSION'
+ instead of the current recording session.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Set the size-based rotation schedule of the current tracing session.
+.Set the size-based rotation schedule of the current recording session.
====
See the option:--size option.
----
====
-.Set the periodic rotation schedule of a specific tracing session.
+.Set the periodic rotation schedule of a specific recording session.
====
See the option:--timer and option:--session options.
lttng-list(1)
=============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-list - List LTTng tracing sessions and instrumentation points
+lttng-list - List LTTng recording sessions and instrumentation points
SYNOPSIS
--------
-List the tracing sessions:
+List the recording sessions:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list*
-List the tracing domains of a tracing session with at least one channel:
+List the tracing domains of a recording session with at least one
+channel:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION'
-List the channels and recording event rules of a tracing session:
+List the channels and recording event rules of a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION'
The `lttng list` command lists:
Without arguments::
- The tracing sessions of your Unix user, or of all users
+ The recording sessions of your Unix user, or of all users
if your Unix user is `root`, within the connected session daemon.
+
See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.
+
-The command shows tracing session properties such as their output
+The command shows recording session properties such as their output
directories/URLs and whether or not they're active.
With the 'SESSION' argument::
With the option:--domain option:::
- The tracing domains (with at least one channel) of the tracing
+ The tracing domains (with at least one channel) of the recording
session named 'SESSION'.
Without the option:--domain option:::
With the option:--channel='CHANNEL' option::::
The recording event rules of the channel 'CHANNEL' of the
- tracing session named 'SESSION'.
+ recording session named 'SESSION'.
Without the option:--channel option::::
- The channels of the tracing session named 'SESSION' and
+ The channels of the recording session named 'SESSION' and
their recording event rules.
+
Use the dedicated tracing domain options (option:--kernel,
Also list the available instrumentation point fields with the
option:--fields option.
-See man:lttng-concept(7) to learn more about tracing sessions, tracing
+See man:lttng-concept(7) to learn more about recording sessions, tracing
domains, channels, recording event rules, and instrumentation points.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-List the channels and recording event rules of the current tracing
+List the channels and recording event rules of the current recording
session (see man:lttng-concept(7) to learn more) with the
man:lttng-status(1) command.
Only available with the 'SESSION' argument.
option:-d, option:--domain::
- Show the tracing domains with at least one channel of the tracing
+ Show the tracing domains with at least one channel of the recording
session named 'SESSION'.
option:-f, option:--fields::
[[examples]]
EXAMPLES
--------
-.List the tracing sessions.
+.List the recording sessions.
====
[role="term"]
----
----
====
-.Show the details of a specific tracing session.
+.Show the details of a specific recording session.
====
[role="term"]
----
----
====
-.List the tracing domains of a specific tracing session having at least one channel.
+.List the tracing domains of a specific recording session having at least one channel.
====
See the option:--domain option.
----
====
-.Show the details of a specific channel in a specific tracing session.
+.Show the details of a specific channel in a specific recording session.
====
See the option:--channel option.
lttng-load(1)
=============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-load - Load LTTng tracing session configurations
+lttng-load - Load LTTng recording session configurations
SYNOPSIS
DESCRIPTION
-----------
The `lttng load` command loads the configurations of one or more
-tracing sessions from files.
+recording sessions from files.
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
Use the `load` command in conjunction with the man:lttng-save(1) command
-to save and restore the complete configurations of tracing sessions. A
-tracing session configuration includes the enabled channels and
-recording event rules, the context fields to be recorded, the tracing
+to save and restore the complete configurations of recording sessions. A
+recording session configuration includes the enabled channels and
+recording event rules, the context fields to be recorded, the recording
activity, and more.
-Once LTTng loads one or more tracing session configurations, they appear
-exactly as they were saved from the user's point of view.
+Once LTTng loads one or more recording session configurations, they
+appear exactly as they were saved from the user's point of view.
LTTng searches the following directories, non-recursively, in this order
-for tracing session configuration files:
+for recording session configuration files:
. `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`)
. +{system_sessions_dir}+
A directory::
With the 'SESSION' argument:::
- LTTng searches for the tracing session configuration named
+ LTTng searches for the recording session configuration named
'SESSION' in all the files of the directory 'PATH' and loads it
if found.
Without the 'SESSION' argument:::
- The option:--all option is implicit: LTTng loads all the tracing
- session configurations found in all the files in the directory
- 'PATH'.
+ The option:--all option is implicit: LTTng loads all the
+ recording session configurations found in all the files in the
+ directory 'PATH'.
A file::
With the 'SESSION' argument:::
- LTTng searches for the tracing session configuration named
+ LTTng searches for the recording session configuration named
'SESSION' in the file 'PATH' and loads it if found.
Without the 'SESSION' argument:::
- The option:--all option is implicit: LTTng loads all the tracing
- session configurations found in the file 'PATH'.
+ The option:--all option is implicit: LTTng loads all the
+ recording session configurations found in the file 'PATH'.
-Override the output URL of the loaded tracing session configurations
+Override the output URL of the loaded recording session configurations
with the option:--override-url option.
-With the 'SESSION' argument, override the name of the loaded tracing
+With the 'SESSION' argument, override the name of the loaded recording
session configuration with the option:--override-name option.
-By default, the `load` command does :not: overwrite existing tracing
+By default, the `load` command does :not: overwrite existing recording
sessions: the command fails. Allow the `load` command to overwrite
-existing tracing sessions with the option:--force option.
+existing recording sessions with the option:--force option.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
option:-a, option:--all::
- Load all the tracing session configurations (default).
+ Load all the recording session configurations (default).
option:-f, option:--force::
- Overwrite existing tracing sessions when loading.
+ Overwrite existing recording sessions when loading.
option:-i 'PATH', option:--input-path='PATH'::
- Load tracing session configurations from 'PATH', either a directory
- or a file, instead of loading them from the default search
+ Load recording session configurations from 'PATH', either a
+ directory or a file, instead of loading them from the default search
directories.
option:--override-name='NAME'::
- Override the name of the loaded tracing session configuration,
+ Override the name of the loaded recording session configuration,
'SESSION', with 'NAME'.
option:--override-url='URL'::
- Override the output URL of the loaded tracing session configurations
- with 'URL'.
+ Override the output URL of the loaded recording session
+ configurations with 'URL'.
+
This is the equivalent of the nloption:--set-url option of
man:lttng-create(1). The validity of the URL override depends on the
-type of tracing session configurations to load. This option applies to
-_all_ the loaded tracing session configurations.
+type of recording session configurations to load. This option applies to
+_all_ the loaded recording session configurations.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Load all the tracing session configurations from the default search directories.
+.Load all the recording session configurations from the default search directories.
====
[role="term"]
----
----
====
-.Load all the tracing session configurations from a specific directory.
+.Load all the recording session configurations from a specific directory.
====
See the option:--input-path option.
----
====
-.Load a specific tracing session configuration from the default search directories.
+.Load a specific recording session configuration from the default search directories.
====
[role="term"]
----
----
====
-.Allow LTTng to overwrite existing tracing sessions when loading.
+.Allow LTTng to overwrite existing recording sessions when loading.
====
See the option:--force option.
----
====
-.Load a specific tracing session configuration from a specific file, overriding its name.
+.Load a specific recording session configuration from a specific file, overriding its name.
====
See the option:--input-path and option:--override-name options.
lttng-metadata(1)
=================
-:revdate: 30 April 2021
+:revdate: 14 June 2021
NAME
----
-lttng-metadata - Manage the metadata generation of an LTTng tracing session
+lttng-metadata - Manage the metadata generation of an LTTng recording session
SYNOPSIS
option:-s 'SESSION', option:--session='SESSION'::
- Manage the metadata generation of the tracing session named
- 'SESSION' instead of the current tracing session (see
- man:lttng-concepts(7) to learn more about the current tracing
+ Manage the metadata generation of the recording session named
+ 'SESSION' instead of the current recording session (see
+ man:lttng-concepts(7) to learn more about the current recording
session).
lttng-regenerate(1)
===================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-regenerate - Regenerate specific data of an LTTng tracing session
+lttng-regenerate - Regenerate specific data of an LTTng recording session
SYNOPSIS
--------
-Regenerate the metadata of a tracing session:
+Regenerate the metadata of a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate metadata* [option:--session='SESSION']
-Regenerate the state dump event records of a tracing session:
+Regenerate the state dump event records of a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate statedump* [option:--session='SESSION']
The `lttng regenerate` command regenerates specific data of:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
As of this version, the `metadata` and `statedump` targets are
available.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-Regenerate the metadata of a tracing session
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Regenerate the metadata of a recording session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the `metadata` target to resample the offset between the monotonic
clock and the wall time of the system, and then regenerate the metadata
stream files.
-More specifically, you may want to resample the wall time
-following a major
-link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP]
+More specifically, you may want to resample the wall time following a
+major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP]
correction. As such, LTTng can trace a system booting with an incorrect
wall time before its wall time is NTP-corrected. Regenerating the
-metadata of the selected tracing session ensures that trace readers can
-accurately determine the event record timestamps relative to the
+metadata of the selected recording session ensures that trace readers
+can accurately determine the event record timestamps relative to the
Unix epoch.
Note that if you plan to rotate (see man:lttng-concepts(7) to learn
-more) the selected tracing session, this target only regenerates the
+more) the selected recording session, this target only regenerates the
metadata stream files of the current and next trace chunks.
[IMPORTANT]
====
You can only use the `metadata` target when the selected
-tracing session:
+recording session:
* Is not in live mode (nloption:--live option of
man:lttng-create(1)).
====
-Regenerate the state dump event records of a tracing session
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Regenerate the state dump event records of a recording session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the `statedump` target to collect up-to-date state dump information
and create corresponding event records.
-This is particularly useful if the selected tracing session is in
+This is particularly useful if the selected recording session is in
snapshot mode (nloption:--snapshot option of the man:lttng-create(1)
command) or if LTTng rotates trace files for one of its channels (see
man:lttng-concepts(7)): in both cases, the state dump information may be
option:-s 'SESSION', option:--session='SESSION'::
- Regenerate specific data of the tracing session named 'SESSION'
- instead of the current tracing session.
+ Regenerate specific data of the recording session named 'SESSION'
+ instead of the current recording session.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Regenerate the metadata of the current tracing session.
+.Regenerate the metadata of the current recording session.
====
[role="term"]
----
----
====
-.Regenerate the state dump event records of a specific tracing session.
+.Regenerate the state dump event records of a specific recording session.
====
See the option:--session option.
lttng-relayd(8)
===============
-:revdate: 30 April 2021
+:revdate: 14 June 2021
:daemon-bin-name: lttng-relayd
:daemon-ini-section: relayd
writes it to the local file system. The relay daemon also accepts LTTng
live connections from compatible readers (for example,
man:babeltrace2(1)); this is the recommended approach to read trace data
-while the remote tracing session is active.
+while the remote recording session is active.
By default, a relay daemon listens on all network interfaces to receive
trace data, but only on `localhost` for LTTng live connections. Override
+
See the ``<<cfg,Daemon configuration>>'' section above.
-* The tracing session configuration of the connected peer.
+* The recording session configuration of the connected peer.
* The LTTng session daemon (see man:lttng-sessiond(8)) version
of the connected peer.
Hostname of the connected peer.
'SESSION'::
- Tracing session name.
+ Recording session name.
'DATETIME'::
- Unique tracing session date/time.
+ Unique recording session date/time.
'TRACEDIR'::
Custom trace directory path ('TRACEDIR' part of the argument of the
[verse]
'BASE'/'HOSTNAME'/'TRACEDIR'
-With the option:--group-output-by-session option (tracing session grouping)::
+With the option:--group-output-by-session option (recording session grouping)::
Without a custom trace directory:::
'SESSIONDV' is at least{nbsp}2.4::::
+
strategy, but this may change in the future.
option:-s, option:--group-output-by-session::
- Group the written trace directories by tracing session name instead
- of by hostname.
+ Group the written trace directories by recording session name
+ instead of by hostname.
option:-o 'DIR', option:--output='DIR'::
Set the base output directory of the written trace directories to
lttng-rotate(1)
===============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-rotate - Archive the current trace chunk of an LTTng tracing session
+lttng-rotate - Archive the current trace chunk of an LTTng recording session
SYNOPSIS
the current trace chunk of:
With the 'SESSION' argument::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the 'SESSION' argument::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-This action is called a _tracing session rotation_.
+This action is called a _recording session rotation_.
-See man:lttng-concepts(7) to learn more about the tracing session
+See man:lttng-concepts(7) to learn more about the recording session
rotation and trace chunk concepts.
You can use the `rotate` command:
-* Any time the tracing session is active.
+* Any time the recording session is active.
-* A single time once the tracing session becomes inactive.
+* A single time once the recording session becomes inactive.
See man:lttng-concepts(7) to learn more about the activity of a
-tracing session.
+recording session.
By default, the `rotate` command ensures that LTTng finished performing
-the tracing session rotation before it prints the path of the archived
-trace chunk and exits. The printed path is absolute when the tracing
+the recording session rotation before it prints the path of the archived
+trace chunk and exits. The printed path is absolute when the recording
session was created in normal mode and relative to the base output
directory of the relay daemon (see the nloption:--output option of
man:lttng-relayd(8)) when it was created in network streaming mode (see
becomes archived, and the command does :not: print the path of the
archived trace chunk.
-Because LTTng flushes the current sub-buffers of the selected tracing
-session when it performs a tracing session rotation, archived trace
+Because LTTng flushes the current sub-buffers of the selected recording
+session when it performs a recording session rotation, archived trace
chunks are never redundant, that is, they do not overlap over time like
snapshots can (see man:lttng-snapshot(1)). Also, a rotation does :not:
directly cause discarded event records or packets.
-A `rotate-session` trigger action can also rotate a tracing session (see
-man:lttng-add-trigger(1)).
+A `rotate-session` trigger action can also rotate a recording session
+(see man:lttng-add-trigger(1)).
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
====
You may only use the `rotate` command when:
-* The selected tracing session was created in normal mode or in network
- streaming mode (see man:lttng-create(1)).
+* The selected recording session was created in normal mode or in
+ network streaming mode (see man:lttng-create(1)).
* No channel was created with a configured trace file count or size
limit (see the nloption:--tracefile-size and
option:-n, option:--no-wait::
- Do not ensure that the tracing session rotation operation is
+ Do not ensure that the recording session rotation operation is
completed before exiting.
[[examples]]
EXAMPLES
--------
-.Rotate the current tracing session.
+.Rotate the current recording session.
====
[role="term"]
----
----
====
-.Rotate a specific tracing session.
+.Rotate a specific recording session.
====
[role="term"]
----
----
====
-.Rotate the current tracing session without waiting for completion.
+.Rotate the current recording session without waiting for completion.
====
See the option:--no-wait option.
lttng-save(1)
=============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-save - Save LTTng tracing session configurations
+lttng-save - Save LTTng recording session configurations
SYNOPSIS
The `lttng save` command saves to files the configurations of:
With the 'SESSION' argument::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the 'SESSION' argument::
- Implicit option:--all option: *all* the tracing sessions of the
+ Implicit option:--all option: *all* the recording sessions of the
connected session daemon for your Unix user, or for all users if
your Unix user is `root`, as listed in the output of `lttng list`
(see man:lttng-list(1)).
See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
Use the `save` command in conjunction with the man:lttng-load(1) command
-to save and restore the complete configurations of tracing sessions.
+to save and restore the complete configurations of recording sessions.
-The `save` command does :not: save tracing data, only the tracing
+The `save` command does :not: save tracing data, only the recording
session parameters, including the channel and recording event rule
configurations.
The default output directory path is `$LTTNG_HOME/.lttng/sessions`
(`$LTTNG_HOME` defaults to `$HOME`). Override the default output
-directory path with the option:--output-path option. Each tracing
+directory path with the option:--output-path option. Each recording
session configuration file is named __SNAME__++.lttng++,
-where{nbsp}__SNAME__ is the original tracing session name.
+where{nbsp}__SNAME__ is the original recording session name.
-By default, the `save` command does :not: overwrite existing tracing
+By default, the `save` command does :not: overwrite existing recording
session configuration files: the command fails. Allow the `save` command
-to overwrite existing tracing session configuration files with the
+to overwrite existing recording session configuration files with the
option:--force option.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
option:-a, option:--all::
- Save all the tracing session configurations of your Unix user, or of
- all users if your Unix user is `root`, as listed in the output of
- man:lttng-list(1), instead of the current tracing session or the
- tracing session named 'SESSION'.
+ Save all the recording session configurations of your Unix user, or
+ of all users if your Unix user is `root`, as listed in the output of
+ man:lttng-list(1), instead of the current recording session or the
+ recording session named 'SESSION'.
option:-f, option:--force::
- Overwrite existing tracing session configuration files when
+ Overwrite existing recording session configuration files when
saving.
option:-o 'DIR', option:--output-path='DIR'::
- Save tracing session configuration files to the directory 'DIR'
+ Save recording session configuration files to the directory 'DIR'
instead of `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to
`$HOME`).
[[examples]]
EXAMPLES
--------
-.Save all the tracing session configurations to the default output directory.
+.Save all the recording session configurations to the default output directory.
====
[role="term"]
----
----
====
-.Save a specific tracing session configuration to a specific output directory.
+.Save a specific recording session configuration to a specific output directory.
====
See the option:--output-path option.
----
====
-.Allow LTTng to overwrite existing tracing session configuration files when saving.
+.Allow LTTng to overwrite existing recording session configuration files when saving.
====
See the option:--force option.
lttng-sessiond(8)
=================
-:revdate: 21 April 2021
+:revdate: 14 June 2021
:daemon-bin-name: lttng-sessiond
:daemon-ini-section: sessiond
An LTTng session daemon, `lttng-sessiond`, is a program which:
-* Manages tracing sessions (see man:lttng-concepts(7) to learn more
- about tracing sessions).
+* Manages recording sessions (see man:lttng-concepts(7) to learn more
+ about recording sessions).
* Controls the various components (like tracers and consumer daemons) of
LTTng.
[[load]]
-Tracing session configuration loading
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When the session daemon starts, it loads tracing session configurations
-from:
+Recording session configuration loading
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When the session daemon starts, it loads recording session
+configurations from:
Without the option:--load option::
In this order:
. All the files in +{system_sessions_auto_dir}+.
--
+
-`lttng-sessiond` only loads tracing configuration files from the
-directories above if its UID and their UID are the same.
+`lttng-sessiond` only loads recording session configuration files from
+the directories above if its UID and their UID are the same.
With the option:--load='PATH' option::
'PATH' is a directory:::
and, therefore, control LTTng kernel tracing.
option:-l 'PATH', option:--load='PATH'::
- Load tracing session configurations from 'PATH', either a directory
- or a file, instead of loading them from the default search
+ Load recording session configurations from 'PATH', either a
+ directory or a file, instead of loading them from the default search
directories.
+
-See the ``<<load,Tracing session configuration loading>>'' section
+See the ``<<load,Recording session configuration loading>>'' section
above.
option:-S, option:--sig-parent::
Set to `0` or `-1` to use the timeout of the operating system (default).
`LTTNG_SESSION_CONFIG_XSD_PATH`::
- Tracing session configuration XML schema definition (XSD) path.
+ Recording session configuration XML schema definition (XSD) path.
FILES
man:lttng-create(1) command.
`$LTTNG_HOME/.lttng/sessions/auto`::
- Directory from which `lttng-sessiond` loads Unix user tracing
+ Directory from which `lttng-sessiond` loads Unix user recording
session configurations when starting.
+
-See the ``<<load,Tracing session configuration loading>>'' section above
-to learn more.
+See the ``<<load,Recording session configuration loading>>'' section
+above to learn more.
+{system_sessions_auto_dir}+::
- Directory from which `lttng-sessiond` loads system-wide tracing
+ Directory from which `lttng-sessiond` loads system-wide recording
session configurations when starting.
+
-See the ``<<load,Tracing session configuration loading>>'' section above
-to learn more.
+See the ``<<load,Recording session configuration loading>>'' section
+above to learn more.
`$LTTNG_HOME/.lttng/lttng.conf`::
Unix user's LTTng daemon INI configuration file.
lttng-set-session(1)
====================
-:revdate: 29 April 2021
+:revdate: 14 June 2021
NAME
----
-lttng-set-session - Set the current LTTng tracing session
+lttng-set-session - Set the current LTTng recording session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng set-session` command sets the current tracing session of your
-Unix user to the tracing session named 'SESSION'.
+The `lttng set-session` command sets the current recording session of your
+Unix user to the recording session named 'SESSION'.
-See man:lttng-concepts(7) to learn more about the current tracing session.
+See man:lttng-concepts(7) to learn more about the current recording
+session.
The `set-session` command effectively updates the `$LTTNG_HOME/.lttngrc`
file.
-List the tracing sessions of your Unix user, or of all users if
+List the recording sessions of your Unix user, or of all users if
your Unix user is `root`, within the connected session daemon with the
man:lttng-list(1) command.
lttng-snapshot(1)
=================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-snapshot - Take a snapshot of an LTTng tracing session
+lttng-snapshot - Take a snapshot of an LTTng recording session
SYNOPSIS
--------
-Take a tracing session snapshot:
+Take a recording session snapshot:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *record* [option:--max-size='SIZE']
[option:--name='NAME'] [option:--session='SESSION']
[option:--ctrl-url='URL' option:--data-url='URL' | 'URL']
-Add a snapshot output to a tracing session:
+Add a snapshot output to a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *add-output* [option:--max-size='SIZE']
[option:--name='NAME'] [option:--session='SESSION']
(option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
-Show the snapshot output of a tracing session:
+Show the snapshot output of a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION']
-Remove the snapshot output from a tracing session:
+Remove the snapshot output from a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1*
snapshot output, and show the snapshot output of:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn more
+ about the current recording session).
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
A _snapshot_ is a dump of the current sub-buffers of all the channels of
-the selected tracing session.
+the selected recording session.
When LTTng takes a snapshot, it sends the sub-buffer dump of the
-selected tracing session to the local file system or over the network to
-a listening relay daemon (man:lttng-relayd(8)). See the
+selected recording session to the local file system or over the network
+to a listening relay daemon (man:lttng-relayd(8)). See the
``<<output,Snapshot output>>'' section below to learn more.
When LTTng takes a snapshot, it does :not: clear the sub-buffers of the
-selected tracing session. In other words, different snapshots of the
-selected tracing session can contain the same event records.
+selected recording session. In other words, different snapshots of the
+selected recording session can contain the same event records.
-You must have created the selected tracing session in snapshot mode (see
-the nloption:--snapshot option of the man:lttng-create(1) command as
-well as man:lttng-concepts(7) to learn more about tracing session modes)
-to use the `snapshot` command.
+You must have created the selected recording session in snapshot mode
+(see the nloption:--snapshot option of the man:lttng-create(1) command
+as well as man:lttng-concepts(7) to learn more about recording session
+modes) to use the `snapshot` command.
-A `snapshot-session` trigger action can also take a tracing session
+A `snapshot-session` trigger action can also take a recording session
snapshot (see man:lttng-add-trigger(1)).
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
If you want, instead, to keep all the trace data, but divide it into
archived chunks which are then, like snapshots, ready to be processed,
-see the tracing session rotation feature in man:lttng-concepts(7). Trace
-chunk archives do :not: overlap like snapshots can.
+see the recording session rotation feature in man:lttng-concepts(7).
+Trace chunk archives do :not: overlap like snapshots can.
[NOTE]
====
the tracers overwriting unconsumed trace packets during the snapshot
operation.
-After LTTng writes the snapshot trace data, you can restart the tracing
-session with the man:lttng-start(1) command.
+After LTTng writes the snapshot trace data, you can restart the
+recording session with the man:lttng-start(1) command.
====
[[output]]
Snapshot output
~~~~~~~~~~~~~~~
-When you take a tracing session snapshot with the `record` action, LTTng
+When you take a recording session snapshot with the `record` action, LTTng
writes the snapshot trace files to:
If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options::
See man:lttng-create(1) for the format of 'URL'.
Otherwise::
- The snapshot output of the selected tracing session.
+ The snapshot output of the selected recording session.
+
-Add a snapshot output to a tracing session with the `add-output` action.
-As of LTTng{nbsp}{lttng_version}, you may only add one snapshot output
-to a given tracing session.
+Add a snapshot output to a recording session with the `add-output`
+action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot
+output to a given recording session.
+
-When you create a snapshot mode tracing session with the
+When you create a snapshot mode recording session with the
nloption:--snapshot option of the man:lttng-create(1) command, and
without its nloption:--no-output option, the `create` command
automatically adds a snapshot output named `snapshot-1` to the created
-tracing session:
+recording session:
+
--
With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options::
Equivalent to using the `add-output` action with the provided or
- equivalent URL(s) immediately after creating the tracing session.
+ equivalent URL(s) immediately after creating the recording session.
Otherwise::
A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
defaults to `$HOME`) directory, of which the name contains the
- tracing session name and the date/time.
+ recording session name and the date/time.
--
+
-Show the current snapshot output of a tracing session with the
+Show the current snapshot output of a recording session with the
`list-output` action.
+
-Remove the snapshot output of a tracing session with the
+Remove the snapshot output of a recording session with the
`del-output` action.
For both the `record` and `add-output` actions:
to this output.
* By default, the snapshot files can be as big as the sum of the sizes
- of all the sub-buffers of all the channels of the selected tracing
+ of all the sub-buffers of all the channels of the selected recording
session.
+
Set the maximum total size of all the snapshot trace files LTTng writes
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Take a snapshot of the sub-buffers of the tracing session named
- 'SESSION' instead of the current tracing session.
+ Take a snapshot of the sub-buffers of the recording session named
+ 'SESSION' instead of the current recording session.
Output
[[examples]]
EXAMPLES
--------
-.Take a snapshot of the current tracing session, sending the trace files to its snapshot output.
+.Take a snapshot of the current recording session, sending the trace files to its snapshot output.
====
[role="term"]
----
----
====
-.Take a snapshot of a specific tracing session, giving it a custom name.
+.Take a snapshot of a specific recording session, giving it a custom name.
====
See the option:--session and option:--name options.
----
====
-.Take a snapshot of the current tracing session, sending the trace files to a custom location.
+.Take a snapshot of the current recording session, sending the trace files to a custom location.
====
See the ``Output directory'' section of man:lttng-relayd(8) to
understand where the relay daemon to connect to (`3.96.87.215`) writes
----
====
-.Replace the snapshot output of a specific tracing session with a local file system path.
+.Replace the snapshot output of a specific recording session with a local file system path.
====
See the option:--session option.
----
====
-.Take a snapshot of the current tracing session, making sure its size is not over 4{nbsp}MiB.
+.Take a snapshot of the current recording session, making sure its size is not over 4{nbsp}MiB.
====
See the option:--max-size option.
lttng-start(1)
==============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-start - Start an LTTng tracing session
+lttng-start - Start an LTTng recording session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng start` command starts a tracing session, that is, it
+The `lttng start` command starts a recording session, that is, it
activates the LTTng tracers for:
With the 'SESSION' argument::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the 'SESSION' argument::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
-The selected tracing session must be inactive (stopped). A tracing
+The selected recording session must be inactive (stopped). A recording
session is inactive on creation (see man:lttng-create(1)).
-A `start-session` trigger action can also start a tracing session
+A `start-session` trigger action can also start a recording session
(see man:lttng-add-trigger(1)).
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-Stop an active tracing session with the man:lttng-stop(1) command.
+Stop an active recording session with the man:lttng-stop(1) command.
include::common-lttng-cmd-options-head.txt[]
[[examples]]
EXAMPLES
--------
-.Start the current tracing session.
+.Start the current recording session.
====
[role="term"]
----
----
====
-.Start a specific tracing session.
+.Start a specific recording session.
====
[role="term"]
----
lttng-status(1)
===============
-:revdate: 29 April 2021
+:revdate: 14 June 2021
NAME
----
-lttng-status - Show the status of the current LTTng tracing session
+lttng-status - Show the status of the current LTTng recording session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng status` command shows the status of the current tracing
+The `lttng status` command shows the status of the current recording
session (see man:lttng-concepts(7) to learn more about the current
-tracing session).
+recording session).
This command is equivalent to:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* 'CURSESSION'
-where `CURSESSION` is the name of the current tracing session.
+where `CURSESSION` is the name of the current recording session.
include::common-lttng-cmd-options-head.txt[]
lttng-stop(1)
=============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
----
-lttng-stop - Stop an LTTng tracing session
+lttng-stop - Stop an LTTng recording session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng stop` command stops a tracing session, that is, it
+The `lttng stop` command stops a recording session, that is, it
deactivates the LTTng tracers for:
With the 'SESSION' argument::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the 'SESSION' argument::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn more
+ about the current recording session).
-See man:lttng-concepts(7) to learn more about tracing sessions.
+See man:lttng-concepts(7) to learn more about recording sessions.
-The selected tracing session must be active (started; see
-man:lttng-start(1)). A tracing session is inactive on creation (see
+The selected recording session must be active (started; see
+man:lttng-start(1)). A recording session is inactive on creation (see
man:lttng-create(1)).
-A `stop-session` trigger action can also stop a tracing session (see
+A `stop-session` trigger action can also stop a recording session (see
man:lttng-add-trigger(1)).
-Start an inactive tracing session with the man:lttng-start(1) command.
+Start an inactive recording session with the man:lttng-start(1) command.
By default, the `stop` command ensures that the trace data of the
-selected tracing session is valid before it exits. Make the command exit
-immediately with the option:--no-wait option. In this case, however, the
-traces(s) might not be valid when the command exits, and there's no way
-to know when it/they becomes valid.
+selected recording session is valid before it exits. Make the command
+exit immediately with the option:--no-wait option. In this case,
+however, the traces(s) might not be valid when the command exits, and
+there's no way to know when it/they becomes valid.
If LTTng archived the current trace chunk (see man:lttng-rotate(1) and
-man:lttng-enable-rotation(1)) of the selected tracing session at least
+man:lttng-enable-rotation(1)) of the selected recording session at least
once during its lifetime, the `stop` command renames the current trace
chunk subdirectory and prints the renamed path. Although it's safe to
-read the content of this renamed subdirectory while the tracing session
-remains inactive, it's :not: a trace chunk archive: you need to destroy
-the tracing session with man:lttng-destroy(1) or perform a rotation with
-man:lttng-rotate(1) to archive it.
+read the content of this renamed subdirectory while the recording
+session remains inactive, it's :not: a trace chunk archive: you need to
+destroy the recording session with man:lttng-destroy(1) or perform a
+rotation with man:lttng-rotate(1) to archive it.
See the ``<<examples,EXAMPLES>>'' section below for usage examples.
option:-n, option:--no-wait::
- Do :not: ensure that the trace data of the selected tracing session
- is valid before exiting.
+ Do :not: ensure that the trace data of the selected recording
+ session is valid before exiting.
include::common-lttng-cmd-help-options.txt[]
[[examples]]
EXAMPLES
--------
-.Stop the current tracing session.
+.Stop the current recording session.
====
[role="term"]
----
----
====
-.Stop a specific tracing session.
+.Stop a specific recording session.
====
[role="term"]
----
----
====
-.Stop the current tracing session without waiting for completion.
+.Stop the current recording session without waiting for completion.
====
See the option:--no-wait option.
lttng-track(1)
==============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
events based on their attributes within:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-See man:lttng-concepts(7) to learn more about tracing sessions and
+See man:lttng-concepts(7) to learn more about recording sessions and
recording event rules.
The `track` command adds values to _inclusion sets_ of process
-attributes. The available inclusion sets are, for a given tracing
+attributes. The available inclusion sets are, for a given recording
session:
With the option:--kernel option::
When an event{nbsp}__E__ satisfies all the other explicit and implicit
conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if
the attributes of the process for which LTTng creates{nbsp}__E__ are
-*all* part of the inclusion sets of the tracing session and domain
+*all* part of the inclusion sets of the recording session and domain
of{nbsp}__ER__.
-By default, on tracing session creation (see man:lttng-create(1)),
+By default, on recording session creation (see man:lttng-create(1)),
all processes are allowed to record events. In other words, all the
-inclusion sets of the tracing session contain all the possible
+inclusion sets of the recording session contain all the possible
process attribute values.
If a given inclusion set{nbsp}__IS__ contains all the possible values
Inclusion set example
~~~~~~~~~~~~~~~~~~~~~
This example operates on the Linux kernel process ID (PID) inclusion set
-of the current tracing session to show how an inclusion set works.
+of the current recording session to show how an inclusion set works.
Assume the maximum system PID is 7 for this example.
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Add values to one or more inclusion sets of the tracing session
- named 'SESSION' instead of the current tracing session.
+ Add values to one or more inclusion sets of the recording session
+ named 'SESSION' instead of the current recording session.
Inclusion set selection
~~~~~~~~~~~~~~~~~~~~~~~
option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
For each 'PID' argument, add 'PID' to the process ID inclusion set
- of the selected tracing session and domain.
+ of the selected recording session and domain.
+
'PID' is the process ID attribute of a process as seen from the root
PID namespace (see man:pid_namespaces(7)).
option:--vpid[='VPID'[,'VPID']...]::
For each 'VPID' argument, add 'VPID' to the virtual process ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'VPID' is the virtual process ID attribute of a process as seen from
the PID namespace of the process (see man:pid_namespaces(7)).
option:--uid[='USER'[,'USER']...]::
For each 'USER' argument, add 'USER' to the user ID inclusion set of
- the selected tracing session and domain.
+ the selected recording session and domain.
+
'USER' is either:
+
option:--vuid[='VUSER'[,'VUSER']...]::
For each 'VUSER' argument, add 'VUSER' to the virtual user ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'VUSER' is either:
+
option:--gid[='GROUP'[,'GROUP']...]::
For each 'GROUP' argument, add 'GROUP' to the group ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'GROUP' is either:
+
option:--vgid[='VGROUP'[,'VGROUP']...]::
For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'VGROUP' is either:
+
[[examples]]
EXAMPLES
--------
-.Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current tracing session.
+.Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session.
====
See the option:--pid option.
----
====
-.Add the ID of a specific user to the user space virtual user ID inclusion set of a specific tracing session.
+.Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session.
====
See the option:--vuid and option:--session options.
----
====
-.Add all the possible group IDs to the Linux kernel group ID inclusion set of the current tracing session.
+.Add all the possible group IDs to the Linux kernel group ID inclusion set of the current recording session.
====
See the option:--all and option:--gid options.
lttng-untrack(1)
================
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
LTTng events based on their attributes within:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-concepts(7) to learn more
- about the current tracing session).
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-See man:lttng-concepts(7) to learn more about tracing sessions and
+See man:lttng-concepts(7) to learn more about recording sessions and
recording event rules.
The `untrack` command removes values from _inclusion sets_ of process
Inclusion set example
~~~~~~~~~~~~~~~~~~~~~
-A common operation is to create a tracing session (see
+A common operation is to create a recording session (see
man:lttng-create(1)), remove all the entries from the Linux kernel
-process ID inclusion set, start tracing, and then manually add PIDs
-while the tracing session is active.
+process ID inclusion set, start recording, and then manually add PIDs
+while the recording session is active.
Assume the maximum system PID is 7 for this example.
Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Remove values from one or more inclusion sets of the tracing session
- named 'SESSION' instead of the current tracing session.
+ Remove values from one or more inclusion sets of the recording
+ session named 'SESSION' instead of the current recording session.
Inclusion set selection
~~~~~~~~~~~~~~~~~~~~~~~
option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
For each 'PID' argument, remove 'PID' from the process ID inclusion
- set of the selected tracing session and domain.
+ set of the selected recording session and domain.
+
'PID' is the process ID attribute of a process as seen from the root
PID namespace (see man:pid_namespaces(7)).
option:--vpid[='VPID'[,'VPID']...]::
For each 'VPID' argument, remove 'VPID' from the virtual process ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'VPID' is the virtual process ID attribute of a process as seen from
the PID namespace of the process (see man:pid_namespaces(7)).
option:--uid[='USER'[,'USER']...]::
For each 'USER' argument, remove 'USER' from the user ID inclusion
- set of the selected tracing session and domain.
+ set of the selected recording session and domain.
+
'USER' is either:
+
option:--vuid[='VUSER'[,'VUSER']...]::
For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'VUSER' is either:
+
option:--gid[='GROUP'[,'GROUP']...]::
For each 'GROUP' argument, remove 'GROUP' from the group ID
- inclusion set of the selected tracing session and domain.
+ inclusion set of the selected recording session and domain.
+
'GROUP' is either:
+
option:--vgid[='VGROUP'[,'VGROUP']...]::
For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
- ID inclusion set of the selected tracing session and domain.
+ ID inclusion set of the selected recording session and domain.
+
'VGROUP' is either:
+
[[examples]]
EXAMPLES
--------
-.Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current tracing session.
+.Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current recording session.
====
See the option:--pid option.
----
====
-.Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific tracing session.
+.Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific recording session.
====
See the option:--vgid and option:--session options.
----
====
-.Remove all the user IDs from the Linux kernel user ID inclusion set of the current tracing session.
+.Remove all the user IDs from the Linux kernel user ID inclusion set of the current recording session.
====
See the option:--all and option:--uid options.
lttng-view(1)
=============
-:revdate: 17 May 2021
+:revdate: 14 June 2021
NAME
current traces of:
With the option:--session='SESSION' option::
- The tracing session named 'SESSION'.
+ The recording session named 'SESSION'.
With the option:--trace-path='DIR' option::
The local file system directory 'DIR'.
Otherwise::
- The current tracing session (see man:concepts(1) to learn more about
- the current tracing session).
+ The current recording session (see man:concepts(1) to learn more
+ about the current recording session).
With the option:--session option or without the option:--trace-path
-option, the mode of the selected tracing session may :not: be network
+option, the mode of the selected recording session may :not: be network
streaming or live.
By default, the `view` command attempts to launch man:babeltrace2(1) or,
option:-t 'DIR', option:--trace-path='DIR'::
Pass 'DIR' as the last argument of the trace reader command instead
- of the output directory of the selected tracing session.
+ of the output directory of the selected recording session.
option:-e 'READER', option:--viewer='READER'::
Use the trace reader 'READER' to read the traces.
[[examples]]
EXAMPLES
--------
-.Read the traces of the current tracing session with Babeltrace.
+.Read the traces of the current recording session with Babeltrace.
====
[role="term"]
----
----
====
-.Read the traces of a specific tracing session with a custom trace reader.
+.Read the traces of a specific recording session with a custom trace reader.
====
See the option:--viewer option.
lttng(1)
========
-:revdate: 12 May 2021
+:revdate: 14 June 2021
NAME
listening LTTng session daemon (man:lttng-sessiond(8)). A session
daemon:
-* Manages tracing sessions (see man:lttng-concepts(7) to learn more
- about tracing sessions).
+* Manages recording sessions (see man:lttng-concepts(7) to learn more
+ about recording sessions).
* Controls the various components (like tracers and consumer daemons) of
LTTng.
The following commands also have their own nloption:--help option.
-Tracing session
-~~~~~~~~~~~~~~~
+Recording session
+~~~~~~~~~~~~~~~~~
[options="header"]
|===
|Command |Description
>>> lttng.create("session-name", "path/to/trace")
-4) Create a handle for the tracing session and domain
+4) Create a handle for the recording session and domain
>>> domain = lttng.Domain()
>>> domain.type = lttng.DOMAIN_KERNEL *
>>> lttng.stop("session-name")
-7) Destroy the tracing session
+7) Destroy the recording session
>>> lttng.destroy("session-name")
2011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is
supported meaning that if you enable a tracepoint for user-space it will be
-enabled for all applications for the current tracing session you are working
+enabled for all applications for the current recording session you are working
on.
QUICKSTART
lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing
registry. To trace any instrumented applications or the kernel, a registered
-tracing session is needed beforehand. To interact with the session daemon and a
-tracing session, you should use the lttng command line UI (lttng). It is also
+recording session is needed beforehand. To interact with the session daemon and a
+recording session, you should use the lttng command line UI (lttng). It is also
possible to use the liblttngctl library for tracing control (lttng.h).
Here is a list of some powerful features the LTTng 2.0 kernel tracer offers:
# lttng list -k
-1) Create a tracing session. The .lttng directory will be created with .lttngrc
+1) Create a recording session. The .lttng directory will be created with .lttngrc
file in $HOME containing the session name (here 'mysession') you are working
on.
$ lttng list -u
-1) Create a tracing session. The .lttng directory will be created with a
+1) Create a recording session. The .lttng directory will be created with a
.lttngrc file in $HOME containing the session name (here 'mysession') you are
working on.
Simple and quick network streaming.
-1) Create a tracing session that will be streamed over the network for the
+1) Create a recording session that will be streamed over the network for the
specified domain. This session will contain, in our example, syscall events.
# lttng create syscall-session
This example uses all possible options to fine grained control the streaming.
-1) Again, create a tracing session that will be streamed over the network for
+1) Again, create a recording session that will be streamed over the network for
the specified domain.
# lttng create syscall-session
-2) Set relayd URIs for the tracing session and kernel domain.
+2) Set relayd URIs for the recording session and kernel domain.
ONLY set the remote relayd URIs (both control and data at the same destination
and using default ports) on the consumer but does not enable the consumer to use
//Functions not needing redefinition
%feature("docstring")"create(str name, str path) -> int
-Create a new tracing session using name and path.
+Create a new recording session using name and path.
Returns 0 on success or a negative error code."
int lttng_create_session(const char *name, const char *path);
%feature("docstring")"create_snapshot(str name, str snapshot_url) -> int
-Create a new tracing session using name and snapshot_url in snapshot
+Create a new recording session using name and snapshot_url in snapshot
mode (flight recorder).
Returns 0 on success or a negative error code."
int lttng_create_session_snapshot(const char *name, const char *path);
%feature("docstring")"destroy(str name) -> int
-Tear down tracing session using name.
+Tear down recording session using name.
Returns 0 on success or a negative error code."
int lttng_destroy_session(const char *name);
} else {
/* Pretty print */
if (count == 0) {
- MSG("Currently no available tracing session");
+ MSG("Currently no available recording session");
goto end;
}
if (session_name == NULL) {
- MSG("Available tracing sessions:");
+ MSG("Available recording sessions:");
}
for (i = 0; i < count; i++) {
if (session_name != NULL) {
if (strncmp(sessions[i].name, session_name, NAME_MAX) == 0) {
session_found = 1;
- MSG("Tracing session %s: [%s%s]", session_name,
+ MSG("Recording session %s: [%s%s]", session_name,
active_string(sessions[i].enabled),
snapshot_string(sessions[i].snapshot_mode));
if (*sessions[i].path) {
puts("");
puts("Available commands:");
puts("");
- puts("Tracing sessions:");
+ puts("Recording sessions:");
puts(" create " CONFIG_CMD_DESCR_CREATE);
puts(" clear " CONFIG_CMD_DESCR_CLEAR);
puts(" destroy " CONFIG_CMD_DESCR_DESTROY);
puts(" start " CONFIG_CMD_DESCR_START);
puts(" stop " CONFIG_CMD_DESCR_STOP);
puts("");
- puts("Tracing session rotation:");
+ puts("Recording session rotation:");
puts(" disable-rotation " CONFIG_CMD_DESCR_DISABLE_ROTATION);
puts(" enable-rotation " CONFIG_CMD_DESCR_ENABLE_ROTATION);
puts(" rotate " CONFIG_CMD_DESCR_ROTATE);
[ ERROR_INDEX(LTTNG_ERR_FILTER_INVAL) ] = "Invalid filter bytecode",
[ ERROR_INDEX(LTTNG_ERR_FILTER_NOMEM) ] = "Not enough memory for filter bytecode",
[ ERROR_INDEX(LTTNG_ERR_FILTER_EXIST) ] = "Filter already exist",
- [ ERROR_INDEX(LTTNG_ERR_NO_CONSUMER) ] = "Consumer not found for tracing session",
+ [ ERROR_INDEX(LTTNG_ERR_NO_CONSUMER) ] = "Consumer not found for recording session",
[ ERROR_INDEX(LTTNG_ERR_NO_SESSIOND) ] = "No session daemon is available",
[ ERROR_INDEX(LTTNG_ERR_SESSION_STARTED) ] = "Session is running",
[ ERROR_INDEX(LTTNG_ERR_NOT_SUPPORTED) ] = "Operation not supported",
[ ERROR_INDEX(LTTNG_ERR_OVERFLOW) ] = "Overflow occurred",
[ ERROR_INDEX(LTTNG_ERR_SESSION_NOT_STARTED) ] = "Session not started",
[ ERROR_INDEX(LTTNG_ERR_LIVE_SESSION) ] = "Live sessions are not supported",
- [ ERROR_INDEX(LTTNG_ERR_PER_PID_SESSION) ] = "Per-PID tracing sessions are not supported",
+ [ ERROR_INDEX(LTTNG_ERR_PER_PID_SESSION) ] = "Per-PID recording sessions are not supported",
[ ERROR_INDEX(LTTNG_ERR_KERN_CONTEXT_UNAVAILABLE) ] = "Context unavailable on this kernel",
[ ERROR_INDEX(LTTNG_ERR_REGEN_STATEDUMP_FAIL) ] = "Failed to regenerate the state dump",
[ ERROR_INDEX(LTTNG_ERR_REGEN_STATEDUMP_NOMEM) ] = "Failed to regenerate the state dump, not enough memory",
[ ERROR_INDEX(LTTNG_ERR_MKDIR_FAIL_CONSUMER) ] = "Directory creation failure on consumer",
[ ERROR_INDEX(LTTNG_ERR_CHAN_NOT_FOUND) ] = "Channel not found",
[ ERROR_INDEX(LTTNG_ERR_SNAPSHOT_UNSUPPORTED) ] = "Session configuration does not allow the use of snapshots",
- [ ERROR_INDEX(LTTNG_ERR_SESSION_NOT_EXIST) ] = "Tracing session does not exist",
+ [ ERROR_INDEX(LTTNG_ERR_SESSION_NOT_EXIST) ] = "Recording session does not exist",
[ ERROR_INDEX(LTTNG_ERR_CREATE_TRACE_CHUNK_FAIL_CONSUMER) ] = "Trace chunk creation failed on consumer",
[ ERROR_INDEX(LTTNG_ERR_CLOSE_TRACE_CHUNK_FAIL_CONSUMER) ] = "Trace chunk close failed on consumer",
[ ERROR_INDEX(LTTNG_ERR_TRACE_CHUNK_EXISTS_FAIL_CONSUMER) ] = "Failed to query consumer for trace chunk existence",
includedir=@includedir@
Name: LTTng control library
-Description: The LTTng control and utility library is a library used to control the tracing sessions of a LTTng-session daemon
+Description: Control LTTng recording sessions and triggers
Version: @PACKAGE_VERSION@
Requires:
Requires.private:
function lttng_session_is_active()
{
local SESSION_NAME="$1"
- "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Tracing session" | grep -q "\[active\]"
+ "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Recording session" | grep -q "\[active\]"
ok $ret "Session \"$SESSION_NAME\" is active"
}
function lttng_session_is_inactive()
{
local SESSION_NAME="$1"
- "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Tracing session" | grep -q "\[inactive\]"
+ "$FULL_LTTNG_BIN" list "$SESSION_NAME" | grep "Recording session" | grep -q "\[inactive\]"
ok $ret "Session \"$SESSION_NAME\" is inactive"
}
res = create(session_name, trace_path)
if res < 0:
- bail("Failed to create tracing session.")
+ bail("Failed to create recording session.")
channel = Channel()
channel.name = "channel0"