This patch updates the remaining manual pages for LTTng-tools 2.13.
This patch:
* Improves the consistency of some command descriptions in
`configure.ac`.
* Adds `common-daemon-cfg.txt` which is a section explaining how to
configure a daemon (session or relay).
lttng-sessiond(8) and lttng-relayd(8) include this file.
* Adds `lttng-concepts.7.txt` which is an adapted copy of the
"Core concepts" section of the online LTTng Documentation.
This centralizes all the LTTng theory into a single manual page
instead of having this information split into multiple lttng(1)
command manual pages.
Many manual pages now refer to lttng-concepts(7), making it possible
to cut a lot of text in those.
* Updates existing manual pages to:
* Have a style and voice which is more consistent with the LTTng
Documentation (website) for 2.13.
* Fix various terminology ambiguities.
* Use more textual variables and lists to explain more complex logic
and processes.
* Always use the same pattern to specify the behaviour of an lttng(1)
command depending on the `SESSION` argument or the `--session`
option.
* For the commands which can perform more than one task, list their
available tasks at the beginning of the "DESCRIPTION" section.
* For some lttng(1) commands which can operate on all tracing sessions
(for example, lttng-clear(1) and lttng-destroy(1)), always indicate
that they target all your Unix user's tracing sessions or, if your
Unix user is `root`, the tracing sessions of all the Unix users
within the root session daemon.
* Clean the "SEE ALSO" sections.
* Always have "LTTng" in the "NAME" section of a manual page.
More specifically:
lttng-create(1):
* Clarify the tracing session modes.
* Clarify how the command adds (or not) a snapshot output for a
snapshot mode tracing session.
* Specify that `--output=DIR` is equivalent to
`--set-url=file://DIR`.
lttng-enable-channel(1):
Include the `--discard`, `--buffers-uid`, and `--buffers-global`
options in the "SYNOPSIS" section even if they are the current
defaults.
lttng-list(1):
Explain what this command does exactly using a tree of options
and arguments.
lttng-load(1):
Clarify how LTTng finds tracing session configurations.
lttng-relayd(8):
* Document the missing `--group` option.
* Rework the text in general.
* Add a daemon configuration section with an INI file example.
* Add more cross-references between options and equivalent
environment variables.
lttng-rotate(1):
Specify that the `rotate-session` trigger action can also rotate
a tracing session.
lttng-save(1):
Clarify the output path.
lttng-sessiond(8):
Add more cross-references between options and equivalent
environment variables.
lttng-shapshot(1):
* Clarify everything related to the snapshot output of a tracing
session, including when and how the lttng-create(1) command adds
an initial snapshot output.
* Specify that the `snapshot-session` trigger action can also take
a snapshot of a tracing session.
lttng-track(1):
lttng-untrack(1):
* Simply refer to allowing processes to record events and to
process attribute inclusion sets instead of using the vague
"tracker" terminology.
* Restate that those commands control an implicit condition of
a recording event rule, as per lttng-concepts(7).
* Improve the documentation of each inclusion set selection
option.
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: Iac7498ee979fe077f0927a9b8335f6c07f203989
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Destroy tracing 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 rotation schedule])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a tracing 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 rotation schedule])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a tracing 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, tracing domains, channels, and recording event rules])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing 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_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_TRACK], [Track process attrbutes])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack process attributes])
+_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])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VIEW], [Launch a trace reader])
lttng-remove-trigger \
lttng-list-triggers
MAN3_NAMES =
-MAN7_NAMES = lttng-event-rule
+MAN7_NAMES = lttng-event-rule lttng-concepts
MAN8_NAMES = lttng-sessiond lttng-relayd
MAN1_NO_ASCIIDOC_NAMES =
MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
$(srcdir)/common-cmd-options-head.txt \
$(srcdir)/common-cmd-help-options.txt \
$(srcdir)/common-help-option.txt \
- $(srcdir)/common-intro.txt
+ $(srcdir)/common-intro.txt \
+ $(srcdir)/common-daemon-cfg.txt
# config
ASCIIDOC_CONF = $(srcdir)/asciidoc.conf
configuration XML schema.
`LTTNG_SESSIOND_PATH`::
- Absolute path to the LTTng session daemon (see
- man:lttng-sessiond(8)) binary.
+ Absolute path to the LTTng session daemon binary (see
+ man:lttng-sessiond(8)).
+
The genoption:--sessiond-path general option overrides this environment
variable.
--- /dev/null
+[[cfg]]
+Daemon configuration
+~~~~~~~~~~~~~~~~~~~~
+When you run +{daemon-bin-name}+, it configures itself from, in this order:
+
+. The INI configuration file +{system_lttng_conf}+, if any.
+
+. The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any.
++
+`$LTTNG_HOME` defaults to `$HOME`.
+
+. With the option:--config='PATH' option: the INI configuration file
+ 'PATH'.
+
+. The command-line options.
+
+Each step can override a previous configuration property.
+
+In INI configuration files, the session daemon only reads the properties
+under the +{daemon-ini-section}+ INI section. Each INI property is:
+
+Key::
+ The long name of a command-line option to set (see the
+ <<options,OPTIONS>> section below).
+
+Value::
+ The selected command-line option accepts an argument:::
+ Option argument (string).
+
+ The selected command-line option is a switch:::
+ `true`::::
+ `yes`::::
+ `on`::::
+ Enable the option.
+
+ `false`::::
+ `no`::::
+ `off`::::
+ Disable the option.
lttng-add-context(1)
====================
-:revdate: 8 April 2021
+:revdate: 3 May 2021
NAME
SYNOPSIS
--------
-Add context fields to be recorded to the LTTng event records of
-one or more channels:
+Add context fields to be recorded to the event records of one or more
+channels:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
DESCRIPTION
-----------
-The `lttng add-context` command adds one or more context fields to be
-recorded to the event records of a given channel, or of all the channels
-of a selected tracing session, by LTTng.
+The `lttng add-context` command can:
-See man:lttng-enable-channel(1) to learn more about LTTng channels.
+Without the option:--list option::
+ Add one or more context fields to be recorded by LTTng to the event
+ records of a given channel, or of all the channels of:
++
+With the option:--session='SESSION' option:::
+ The tracing 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).
-When you use the `add-context` command to add context fields for a given
-channel, all the event records which LTTng writes to a sub-buffer of
-that channel contain the dynamic values of those context fields.
+With the option:--list option::
+ List the available context field types.
-Without the option:--session option, the `add-context` command selects
-the current tracing session (see man:lttng-create(1) and
-man:lttng-set-session(1) to learn more about the current tracing
-session).
+See man:lttng-concepts(7) to learn more about tracing sessions and
+channels.
Without the option:--channel option, LTTng adds context fields to be
recorded to the event records of *all* the channels of the selected
tracing session.
-Repeat the option:--type option to add more than one context field to be
-recorded.
+Repeat the option:--type='TYPE' option to add more than one context
+field to be recorded. 'TYPE' is one of:
-perf counter context fields are available:
+* A statically-known, or built-in context field named.
+* A perf counter name:
++
+--
Per-CPU::
- Prefix: `perf:cpu:`.
+ Prefix: `perf:cpu:`
+
-Only available for Linux kernel (option:--kernel option) channels.
+Only available with the option:--kernel option.
Per-thread::
- Prefix: `perf:thread:`.
+ Prefix: `perf:thread:`
+
-Only available for user application/library (option:--userspace,
-option:--jul, and option:--log4j options) channels.
-
-Add PMU counter context fields by raw ID with the
-++perf:cpu:raw:r++__N__++:++__NAME__ (Linux kernel tracing domain) or
-++perf:thread:raw:r++__N__++:++__NAME__ (user space tracing domain)
-types, with:
-
+Only available with the option:--userspace, option:--jul, or
+option:--log4j option.
+--
++
+Add Performance Monitoring Unit (PMU) counter context fields by raw ID
+with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option)
+or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace,
+option:--jul, or option:--log4j option) types, with:
++
+--
'N'::
A hexadecimal event descriptor which follows the man:perf-record(1)
format: a concatenation of the event number and umask value which
the manufacturer of the processor provides.
+
-The possible values for this field are processor-specific.
+The possible values for this part are processor-specific.
'NAME'::
- Custom name to easily recognize the counter.
-
-Add an application-specific context field with the following syntax:
+ Custom name to identify the counter.
+--
+* An LTTng application-specific context field name:
++
[verse]
$app.'PROVIDER':__TYPE__
-
++
'PROVIDER'::
Provider name.
'TYPE'::
Context type name.
-NOTE: Make sure to **single-quote** the argument of the option:--type
-option when you run the `add-context` command from a shell, as `$` is a
-special character for variable substitution in most shells.
-
-List the available context field types with the option:--list option and
-without other arguments.
+IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
+`add-context` command from a shell, as `$` is a special character for
+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.
+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.
include::common-cmd-options-head.txt[]
SEE ALSO
--------
man:lttng(1),
-man:lttng-enable-channel(1),
-man:lttng-set-session(1)
+man:lttng-concepts(7),
+man:lttng-enable-channel(1)
lttng-add-trigger(1)
====================
-:revdate: 23 April 2021
+:revdate: 3 May 2021
NAME
DESCRIPTION
-----------
The `lttng add-trigger` command creates and adds an LTTng _trigger_ to
-the session daemon (see man:lttng-sessiond(8)).
+the connected session daemon (see man:lttng-sessiond(8)).
-A trigger is an association between a _condition_ and one or more
-_actions_. When the condition of a trigger{nbsp}__T__ is satisfied,
-LTTng requests to execute the actions of{nbsp}__T__. Depending on the
-rate policy of an action, an execution request can become an actual
-execution.
+See man:lttng-concepts(7) to learn more about LTTng triggers.
-A trigger doesn't belong to a specific tracing session: it's global to
-the session daemon. Within the session daemon, and for a given Unix
-user, a trigger has a unique name. By default, the `add-trigger` command
-automatically assigns a name to the added trigger. Use the option:--name
-option to assign a specific name instead.
+By default, the `add-trigger` command automatically assigns a name,
+unique for a given session daemon and Unix user, to the added trigger.
+Assign a custom name with the option:--name.
The `add-trigger` command adds a trigger for your Unix user. If your
-Unix user is `root`, you can add the trigger as another user with the
+Unix user is `root`, you may add the trigger as another user with the
option:--owner-uid option.
Specify the condition of the trigger to add with a <<cond-spec,condition
specifier>> and its actions with one or more <<action-spec,action
specifiers>>. The order of the action specifiers is significant: LTTng
-attempts to execute the actions of a trigger in order.
+attempts to execute the actions of a firing trigger in this order.
-List the available triggers for your Unix user (or for all users if your
-Unix user is `root`) with the man:lttng-list-triggers(1) command.
+List the triggers of your Unix user, or of all users if your
+Unix user is `root`, with the man:lttng-list-triggers(1) command.
-Remove an existing trigger with the man:lttng-remove-trigger(1) command.
+Remove a trigger with the man:lttng-remove-trigger(1) command.
[[cond-spec]]
Synopsis:
+
[verse]
-option:--condition=event-rule-matches [nloption:--capture='CDESCR']... 'ERSPEC'
+option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
{nbsp}
+
An `event-rule-matches` condition is considered satisfied when the event
Synopsis:
+
[verse]
-option:--action=notify [nloption:--rate-policy='POLICY']
+option:--action=**notify** [nloption:--rate-policy='POLICY']
{nbsp}
+
Sends a notification through the notification
Synopsis:
+
[verse]
-option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Starts the tracing session named 'SESSION' like man:lttng-start(1)
Synopsis:
+
[verse]
-option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
Synopsis:
+
[verse]
-option:--action=rotate-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Archives the current trace chunk of the tracing session named 'SESSION'
Synopsis:
+
[verse]
-option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Takes a snapshot of the tracing session named 'SESSION' like
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-list-triggers(1),
man:lttng-remove-trigger(1)
lttng-clear(1)
==============
-:revdate: 8 April 2021
+:revdate: 3 May 2021
NAME
----
-lttng-clear - Clear a tracing session
+lttng-clear - Clear an LTTng tracing session
SYNOPSIS
it deletes the contents of their tracing buffers and of all their local
and streamed trace data.
+See man:lttng-concepts(7) to learn more about tracing sessions.
+
The `clear` command clears:
Without any option::
The current tracing session.
+
-See man:lttng-create(1) and man:lttng-set-session(1) to learn more about
-the current tracing session.
+See man:lttng-concepts(7) to learn more about the current tracing
+session.
With the 'SESSION' argument::
- The existing tracing session named 'SESSION'.
+ The tracing session named 'SESSION'.
With the option:--all option::
- *All* the tracing sessions of your Unix user, as listed in the
- output of `lttng list` (see man:lttng-list(1)).
+ *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)).
++
+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
nloption:--snapshot option of the man:lttng-create(1) command), the
`clear` command only clears the tracing buffers.
For a given tracing session, if at least one rotation occurred (see
-man:lttng-rotate(1)), the `clear` command only clears its tracing
+man:lttng-concepts(7)), the `clear` command only clears its tracing
buffers and its current trace chunk, :not: its archived trace chunks.
NOTE: The nloption:--disallow-clear option and the
Recording target
~~~~~~~~~~~~~~~~
option:-a, option:--all::
- Clear all the tracing sessions of your Unix user, as listed in the
- output of man:lttng-list(1), instead of the current tracing session
- or the tracing session named 'SESSION'.
+ Clear 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'.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-create(1),
-man:lttng-relayd(8),
-man:lttng-rotate(1),
-man:lttng-set-session(1)
+man:lttng-relayd(8)
--- /dev/null
+lttng-concepts(7)
+=================
+:revdate: 3 May 2021
+:sect-event-rule: INSTRUMENTATION POINT, EVENT RULE, AND EVENT
+:sect-session: TRACING SESSION
+:sect-domain: TRACING DOMAIN
+:sect-channel: CHANNEL AND RING BUFFER
+:sect-recording-event-rule: RECORDING EVENT RULE AND EVENT RECORD
+
+
+NAME
+----
+lttng-concepts - LTTng concepts
+
+
+DESCRIPTION
+-----------
+This manual page documents the concepts of LTTng.
+
+Many other LTTng manual pages refer to this one so that you can
+understand what are the various LTTng objects and how they relate to
+each other.
+
+The concepts of LTTng{nbsp}{lttng_version} are:
+
+* Instrumentation point, event rule, and event
+* Trigger
+* Tracing session
+* Tracing domain
+* Channel and ring buffer
+* Recording event rule and event record
+
+
+[[event-rule]]
+{sect-event-rule}
+-----------------
+An _instrumentation point_ is a point, within a piece of software,
+which, when executed, creates an LTTng _event_.
+
+LTTng offers various types of instrumentation; see the
+<<inst-point-types,Instrumentation point types>> section below to learn
+about them.
+
+An _event rule_ is a set of conditions to match a set of events.
+
+When LTTng creates an event{nbsp}__E__, an event rule{nbsp}__ER__ is
+said to __match__{nbsp}__E__ when{nbsp}__E__ satisfies *all* the
+conditions of{nbsp}__ER__. This concept is similar to a regular
+expression which matches a set of strings.
+
+When an event rule matches an event, LTTng _emits_ the event, therefore
+attempting to execute one or more actions.
+
+[IMPORTANT]
+====
+The event creation and emission processes are documentation concepts to
+help understand the journey from an instrumentation point to the
+execution of actions.
+
+The actual creation of an event can be costly because LTTng needs to
+evalute the arguments of the instrumentation point.
+
+In practice, LTTng implements various optimizations for the Linux kernel
+and user space tracing domains (see the <<domain,{sect-domain}>> section
+below) to avoid actually creating an event
+when the tracer knows, thanks to properties which are independent from
+the event payload and current context, that it would never emit such an
+event. Those properties are:
+
+* The instrumentation point type (see the
+ <<inst-point-types,Instrumentation point types>> section below).
+
+* The instrumentation point name.
+
+* The instrumentation point log level.
+
+* For a recording event rule (see the
+ <<recording-event-rule,{sect-recording-event-rule}>> section
+ below):
+** The status of the rule itself.
+** The status of the channel (see the <<channel,{sect-channel}>> section
+ below).
+** The activity of the tracing session (started or stopped; see
+ the <<session,{sect-session}>> section below).
+** Whether or not the process for which LTTng would create the event is
+ allowed to record events (see man:lttng-track(1)).
+
+In other words: if, for a given instrumentation point{nbsp}__IP__, the
+LTTng tracer knows that it would never emit an event,
+executing{nbsp}__IP__ represents a simple boolean variable check and,
+for a Linux kernel recording event rule, a few process attribute checks.
+====
+
+As of LTTng{nbsp}{lttng_version}, there are two places where you can
+find an event rule:
+
+Recording event rule::
+ A specific type of event rule of which the action is to record the
+ matched event as an event record.
++
+See the <<recording-event-rule,{sect-recording-event-rule}>> section
+below.
++
+Create or enable a recording event rule with the
+man:lttng-enable-event(1) command.
++
+List the recording event rules of a specific tracing session
+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.
++
+See man:lttng-add-trigger(1) and man:lttng-event-rule(7).
+
+For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
+basic conditions of an event rule{nbsp}__ER__, that is:
+
+* The instrumentation point from which LTTng creates{nbsp}__E__ has a
+ specific type.
++
+See the <<inst-point-types,Instrumentation point types>> section below.
+
+* A pattern matches the name of{nbsp}__E__ while another pattern
+ doesn't.
+
+* The log level of the instrumentation point from which LTTng
+ creates{nbsp}__E__ is at least as severe as some value, or is exactly
+ some value.
+
+* The fields of the payload of{nbsp}__E__ and the current context fields
+ satisfy a filter expression.
+
+A recording event rule has additional, implicit conditions to satisfy.
+See the <<recording-event-rule,{sect-recording-event-rule}>> section
+below to learn more.
+
+
+[[inst-point-types]]
+Instrumentation point types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+As of LTTng{nbsp}{lttng_version}, the available instrumentation point
+types are, depending on the tracing domain (see the
+<<domain,{sect-domain}>> section below):
+
+Linux kernel::
+ LTTng tracepoint:::
+ A statically defined point in the source code of the kernel
+ image or of a kernel module using the LTTng-modules macros.
++
+List the available Linux kernel tracepoints with `lttng list --kernel`.
+See man:lttng-list(1) to learn more.
+
+ Linux kernel system call:::
+ Entry, exit, or both of a Linux kernel system call.
++
+List the available Linux kernel system call instrumentation points with
+`lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
+
+ Linux kprobe:::
+ A single probe dynamically placed in the compiled kernel code.
++
+When you create such an instrumentation point, you set its memory
+address or symbol name.
+
+ Linux user space probe:::
+ A single probe dynamically placed at the entry of a compiled
+ user space application/library function through the kernel.
++
+When you create such an instrumentation point, you set:
++
+--
+With the ELF method::
+ Its application/library path and its symbol name.
+
+With the USDT method::
+ Its application/library path, its provider name, and its probe name.
++
+``USDT'' stands for SystemTap User-level Statically Defined Tracing,
+a DTrace-style marker.
+--
++
+As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
+are :not: reference-counted.
+
+ Linux kretprobe:::
+ Entry, exit, or both of a Linux kernel function.
++
+When you create such an instrumentation point, you set the memory
+address or symbol name of its function.
+
+User space::
+ LTTng tracepoint:::
+ A statically defined point in the source code of a C/$$C++$$
+ application/library using the LTTng-UST macros.
++
+List the available Linux kernel tracepoints with
+`lttng list --userspace`. See man:lttng-list(1) to learn more.
+
+`java.util.logging`, Apache log4j, and Python::
+ Java or Python logging statement:::
+ A method call on a Java or Python logger attached to an
+ LTTng-UST handler.
++
+List the available Java and Python loggers with `lttng list --jul`,
+`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
+to learn more.
+
+
+[[trigger]]
+TRIGGER
+-------
+A _trigger_ associates a condition to one or more actions.
+
+When the condition of a trigger is satisfied, LTTng attempts to execute
+its actions.
+
+As of LTTng{nbsp}{lttng_version}, the available trigger conditions and
+actions are:
+
+Conditions::
++
+* The consumed buffer size of a given tracing
+ session (see the <<session,{sect-session}>> section below)
+ becomes greater than some value.
+
+* The buffer usage of a given channel (see the
+ <<channel,{sect-channel}>> section below) becomes greater than some
+ value.
+
+* 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).
+
+* A tracing session rotation becomes completed.
+
+* An event rule matches an event.
++
+As of LTTng{nbsp}{lttng_version}, this is the only available condition
+when you add a trigger with the man:lttng-add-trigger(1) command. The
+other ones are available through the liblttng-ctl C{nbsp}API.
+
+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),
+ like man:lttng-rotate(1) would do.
+* Take a snapshot of a given tracing 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
+user has its own, private triggers. Note, however, that the `root` Unix
+user may, for the root session daemon:
+
+* Add a trigger as another Unix user.
+
+* List all the triggers, regardless of their owner.
+
+* Remove a trigger which belongs to another Unix user.
+
+For a given session daemon and Unix user, a trigger has a unique name.
+
+Add a trigger to a session daemon with the man:lttng-add-trigger(1)
+command.
+
+List the triggers of your Unix user (or of all users if your
+Unix user is `root`) with the man:lttng-list-triggers(1) command.
+
+Remove a trigger with the man:lttng-remove-trigger(1) command.
+
+
+[[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.
+
+Everything that you do when you control LTTng tracers to record events
+happens within a tracing session. In particular, a tracing session:
+
+* Has its own name, unique for a given session daemon.
+
+* Has its own set of trace files, if any.
+
+* 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).
+
+* Has its own mode (local, network streaming, snapshot, or live).
++
+See the <<session-modes,Tracing session modes>> section below to learn
+more.
+
+* Has its own channels (see the <<channel,{sect-channel}>> section
+ below) to which are attached their own recording event rules.
+
+* Has its own process attribute inclusion sets (see man:lttng-track(1)).
+
+Those attributes and objects are completely isolated between different
+tracing sessions.
+
+A tracing 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
+the man:lttng-create(1) command to the man:lttng-destroy(1) command.
+
+A tracing 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.
+
+Create a tracing session with the man:lttng-create(1) command.
+
+List the tracing 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
+man:lttng-stop(1) commands.
+
+Save and load a tracing 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
+man:lttng-rotate(1) command.
+
+Destroy a tracing session with the man:lttng-destroy(1) command.
+
+
+Current tracing 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
+session_.
+
+When you create a new tracing session with the `create` command, LTTng
+updates the current tracing session.
+
+The following man:lttng(1) commands select the current tracing session
+if you don't specify one:
+
+* man:lttng-add-context(1)
+* man:lttng-clear(1)
+* man:lttng-destroy(1)
+* man:lttng-disable-channel(1)
+* man:lttng-disable-event(1)
+* man:lttng-disable-rotation(1)
+* man:lttng-enable-channel(1)
+* man:lttng-enable-event(1)
+* man:lttng-enable-rotation(1)
+* man:lttng-regenerate(1)
+* man:lttng-rotate(1)
+* man:lttng-save(1)
+* man:lttng-snapshot(1)
+* man:lttng-start(1)
+* man:lttng-status(1)
+* man:lttng-stop(1)
+* man:lttng-track(1)
+* man:lttng-untrack(1)
+* man:lttng-view(1)
+
+Set the current tracing 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:
+
+Local mode::
+ Write the trace data to the local file system.
+
+Network streaming mode::
+ Send the trace data over the network to a listening relay daemon
+ (see man:lttng-relayd(8)).
+
+Snapshot mode::
+ Only write the trace data to the local file system or send it to a
+ listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
+ snapshot.
++
+LTTng forces all the channels (see the <<channel,{sect-channel}>>
+section below) to be created to be configured to be snapshot-ready.
++
+LTTng takes a snapshot of such a tracing session when:
++
+--
+* You run the man:lttng-snapshot(1) command.
+
+* LTTng executes a `snapshot-session` trigger action (see the
+ <<trigger,TRIGGER>> section above).
+--
+
+Live mode::
+ Send the trace data over the network to a listening relay daemon
+ (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
+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.
+
+Once LTTng archives a trace chunk, it does :not: manage it anymore: you
+can read it, modify it, move it, or remove it.
+
+An _archived trace chunk_ is a collection of metadata and data stream
+files which form a self-contained LTTng trace. See the
+<<trace-chunk-naming,Trace chunk naming>> section below to learn how
+LTTng names a trace chunk archive directory.
+
+The _current trace chunk_ of a given tracing 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
+ man:lttng-start(1) command or with a `start-session` trigger action
+ (see the <<trigger,TRIGGER>> section above).
+
+** The last rotation, performed with:
+
+*** An man:lttng-rotate(1) command.
+
+*** A rotation schedule previously set with
+ man:lttng-enable-rotation(1).
+
+*** An executed `rotate-session` trigger action (see the
+ <<trigger,TRIGGER>> section above).
+
+* The content of all the non-flushed sub-buffers of the channels of the
+ tracing 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
+nloption:--output option of the man:lttng-create(1) command and
+of man:lttng-relayd(8)).
+
+A trace chunk archive contains, through tracing domain and possibly
+UID/PID subdirectories, metadata and data stream files.
+
+A trace chunk archive is, at the same time:
+
+* A self-contained LTTng trace.
+
+* A member of a set of trace chunk archives which form the complete
+ trace of a tracing session.
+
+In other words, an LTTng trace reader can read both the tracing
+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
+trace chunk archive as such, relative to the output directory of the
+tracing session:
+
+[verse]
+archives/__BEGIN__-__END__-__ID__
+
+__BEGIN__::
+ Date and time of the beginning of the trace chunk archive with
+ the ISO{nbsp}8601-compatible __YYYYmmddTHHMMSS±HHMM__ form, where
+ __YYYYmmdd__ is the date and __HHMMSS±HHMM__ is the time with the
+ time zone offset from UTC.
++
+Example: `20171119T152407-0500`
+
+__END__::
+ Date and time of the end of the trace chunk archive with
+ the ISO{nbsp}8601-compatible __YYYYmmddTHHMMSS±HHMM__ form, where
+ __YYYYmmdd__ is the date and __HHMMSS±HHMM__ is the time with the
+ time zone offset from UTC.
++
+Example: `20180118T152407+0930`
+
+__ID__::
+ Unique numeric identifier of the trace chunk within its tracing
+ session.
+
+Trace chunk archive name example:
+
+----
+archives/20171119T152407-0500-20171119T151422-0500-3
+----
+
+
+[[domain]]
+{sect-domain}
+-------------
+A _tracing domain_ identifies a type of LTTng tracer.
+
+A tracing domain has its own properties and features.
+
+There are currently five available tracing domains:
+
+[options="header"]
+|===
+|Tracing domain |``Event rule matches'' trigger condition option |Option for other CLI commands
+
+|Linux kernel
+|nloption:--domain=++kernel++
+|nloption:--kernel
+
+|User space
+|nloption:--domain=++user++
+|nloption:--userspace
+
+|`java.util.logging` (JUL)
+|nloption:--domain=++jul++
+|nloption:--jul
+
+|Apache log4j
+|nloption:--domain=++log4j++
+|nloption:--log4j
+
+|Python
+|nloption:--domain=++python++
+|nloption:--python
+|===
+
+You must specify a tracing domain to target a type of LTTng tracer when
+using some man:lttng(1) to avoid ambiguity. For example, because the
+Linux kernel and user space tracing domains support named tracepoints as
+instrumentation points (see the <<"event-rule","{sect-event-rule}">> section
+above), you need to specify a tracing domain when you create an event
+rule because both tracing domains could have tracepoints sharing the
+same name.
+
+You can create channels (see the <<channel,{sect-channel}>> section
+below) in the Linux kernel and user space tracing domains. The other
+tracing domains have a single, default channel.
+
+
+[[channel]]
+{sect-channel}
+--------------
+A _channel_ is an object which is responsible for a set of ring buffers.
+
+Each ring buffer is divided into multiple _sub-buffers_. When a
+recording event rule (see the
+<<recording-event-rule,{sect-recording-event-rule} section below)
+matches an event, LTTng can record it to one or more sub-buffers of one
+or more channels.
+
+When you create a channel with the man:lttng-enable-channel(1) command,
+you set its final attributes, that is:
+
+* Its buffering scheme.
++
+See the <<channel-buf-scheme,Buffering scheme>> section below.
+
+* What to do when there's no
+ space left for a new event record because all sub-buffers are full.
++
+See the <<channel-er-loss-mode,Event record loss mode>> section below.
+
+* The size of each ring buffer and how many sub-buffers a ring buffer
+ has.
++
+See the <<channel-sub-buf-size-count,Sub-buffer size and count>> section
+below.
+
+* The size of each trace file LTTng writes for this channel and the
+ maximum count of trace files.
++
+See the <<channel-max-trace-file-size-count,Maximum trace file size and
+count>> section below.
+
+* The periods of its read, switch, and monitor timers.
++
+See the <<channel-timers,Timers>> section below.
+
+* For a Linux kernel channel: its output type (man:mmap(2) or
+ man:splice(2)).
++
+See the nloption:--output option of the man:lttng-enable-channel(1)
+command.
+
+* For a user space channel: the value of its blocking timeout.
++
+See the nloption:--blocking-timeout option of the
+man:lttng-enable-channel(1) command.
+
+Note that the man:lttng-enable-event(1) command can automatically create
+a default channel with sane defaults when no channel exists for the
+provided tracing domain.
+
+A channel is always associated to a tracing domain (see the
+<<domain,{sect-domain}>> section below). The `java.util.logging` (JUL),
+log4j, and Python tracing domains each have a default channel which you
+can't configure.
+
+A channel owns recording event rules.
+
+List the channels of a given tracing session with the
+man:lttng-list(1) and man:lttng-status(1) commands.
+
+Disable an enabled channel with the man:lttng-disable-channel(1)
+command.
+
+
+[[channel-buf-scheme]]
+Buffering scheme
+~~~~~~~~~~~~~~~~
+A channel has at least one ring buffer per CPU. LTTng always records an
+event to the ring buffer dedicated to the CPU which emits it.
+
+The buffering scheme of a user space channel determines what has its own
+set of per-CPU ring buffers:
+
+Per-user buffering (nloption:--buffers-uid option of the man:lttng-enable-channel(1) command)::
+ Allocate one set of ring buffers (one per CPU) shared by all the
+ instrumented processes of:
+ If your Unix user is `root`:::
+ Each Unix user.
+ Otherwise:::
+ Your Unix user.
+
+Per-process buffering (nloption:--buffers-pid option of the man:lttng-enable-channel(1) command)::
+ Allocate one set of ring buffers (one per CPU) for each instrumented
+ process of:
+ If your Unix user is `root`:::
+ All Unix users.
+ Otherwise:::
+ Your Unix user.
+
+The per-process buffering scheme tends to consume more memory than the
+per-user option because systems generally have more instrumented
+processes than Unix users running instrumented processes. However, the
+per-process buffering scheme ensures that one process having a high
+event throughput won't fill all the shared sub-buffers of the same Unix
+user, only its own.
+
+The buffering scheme of a Linux kernel channel is always to allocate a
+single set of ring buffers for the whole system. This scheme is similar
+to the per-user option, but with a single, global user ``running'' the
+kernel.
+
+
+[[channel-er-loss-mode]]
+Event record loss mode
+~~~~~~~~~~~~~~~~~~~~~~
+When LTTng emits an event, LTTng can record it to a specific, available
+sub-buffer within the ring buffers of specific channels. When there's no
+space left in a sub-buffer, the tracer marks it as consumable and
+another, available sub-buffer starts receiving the following event
+records. An LTTng consumer daemon eventually consumes the marked
+sub-buffer, which returns to the available state.
+
+In an ideal world, sub-buffers are consumed faster than they are filled.
+In the real world, however, all sub-buffers can be full at some point,
+leaving no space to record the following events.
+
+By default, LTTng-modules and LTTng-UST are _non-blocking_ tracers: when
+there's no available sub-buffer to record an event, it's acceptable to
+lose event records when the alternative would be to cause substantial
+delays in the execution of the instrumented application. LTTng
+privileges performance over integrity; it aims at perturbing the
+instrumented application as little as possible in order to make the
+detection of subtle race conditions and rare interrupt cascades
+possible.
+
+Since LTTng{nbsp}2.10, the LTTng user space tracer, LTTng-UST, supports
+a _blocking mode_. See the nloption:--blocking-timeout of the
+man:lttng-enable-channel(1) command to learn how to use the blocking
+mode.
+
+When it comes to losing event records because there's no available
+sub-buffer, or because the blocking timeout of the channel is
+reached, the _event record loss mode_ of the channel determines what to
+do. The available event record loss modes are:
+
+Discard mode::
+ Drop the newest event records until a sub-buffer becomes available.
++
+This is the only available mode when you specify a blocking timeout.
++
+With this mode, LTTng increments a count of lost event records when an
+event record is lost and saves this count to the trace. A trace reader
+can use the saved discarded event record count of the trace to decide
+whether or not to perform some analysis even if trace data is known to
+be missing.
+
+Overwrite mode::
+ Clear the sub-buffer containing the oldest event records and start
+ writing the newest event records there.
++
+This mode is sometimes called _flight recorder mode_ because it's
+similar to a https://en.wikipedia.org/wiki/Flight_recorder[flight
+recorder]: always keep a fixed amount of the latest data. It's also
+similar to the roll mode of an oscilloscope.
++
+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.
++
+With this mode, LTTng doesn't write to the trace the exact number of
+lost event records in the lost sub-buffers.
+
+Which mechanism you should choose depends on your context: prioritize
+the newest or the oldest event records in the ring buffer?
+
+Beware that, in overwrite mode, the tracer abandons a _whole sub-buffer_
+as soon as a there's no space left for a new event record, whereas in
+discard mode, the tracer only discards the event record that doesn't
+fit.
+
+Set the event record loss mode of a channel with the nloption:--discard
+and nloption:--overwrite options of the man:lttng-enable-channel(1)
+command.
+
+There are a few ways to decrease your probability of losing event
+records. The <<channel-sub-buf-size-count,Sub-buffer size and count>>
+section below shows how to fine-tune the sub-buffer size and count of a
+channel to virtually stop losing event records, though at the cost of
+greater memory usage.
+
+
+[[channel-sub-buf-size-count]]
+Sub-buffer size and count
+~~~~~~~~~~~~~~~~~~~~~~~~~
+A channel has one or more ring buffer for each CPU of the target system.
+
+See the <<channel-buf-scheme,Buffering scheme>> section above to learn
+how many ring buffers of a given channel are dedicated to each CPU
+depending on its buffering scheme.
+
+Set the size of each sub-buffer the ring buffers of a channel contain
+with the nloption:--subbuf-size option of the
+man:lttng-enable-channel(1) command.
+
+Set the number of sub-buffers each ring buffer of a channel contains
+with the nloption:--num-subbuf option of the man:lttng-enable-channel(1)
+command.
+
+Note that LTTng switching the current sub-buffer of a ring buffer
+(marking a full one as consumable and switching to an available one for
+LTTng to record the next events) introduces noticeable CPU overhead.
+Knowing this, the following list presents a few practical situations
+along with how to configure the sub-buffer size and count for them:
+
+High event throughput::
+ In general, prefer large sub-buffers to lower the risk of losing
+ event records.
++
+Having larger sub-buffers also ensures a lower sub-buffer switching
+frequency (see the <<channel-timers,Timers>> section below).
++
+The sub-buffer count is only meaningful if you create the channel in
+overwrite mode (see the <<channel-er-loss-mode,Event record loss mode>>
+section above): in this case, if LTTng overwrites a sub-buffer, then the
+other sub-buffers are left unaltered.
+
+Low event throughput::
+ In general, prefer smaller sub-buffers since the risk of losing
+ event records is low.
++
+Because LTTng emits events less frequently, the sub-buffer switching
+frequency should remain low and therefore the overhead of the tracer
+shouldn't be a problem.
+
+Low memory system::
+ If your target system has a low memory limit, prefer fewer first,
+ then smaller sub-buffers.
++
+Even if the system is limited in memory, you want to keep the
+sub-buffers as large as possible to avoid a high sub-buffer switching
+frequency.
+
+Note that LTTng uses https://diamon.org/ctf/[CTF] as its trace format,
+which means event record data is very compact. For example, the average
+LTTng kernel event record weights about 32{nbsp}bytes. Therefore, a
+sub-buffer size of 1{nbsp}MiB is considered large.
+
+The previous scenarios highlight the major trade-off between a few large
+sub-buffers and more, smaller sub-buffers: sub-buffer switching
+frequency vs. how many event records are lost in overwrite mode.
+Assuming a constant event throughput and using the overwrite mode, the
+two following configurations have the same ring buffer total size:
+
+Two sub-buffers of 4{nbsp}MiB each::
+ Expect a very low sub-buffer switching frequency, but if LTTng
+ ever needs to overwrite a sub-buffer, half of the event records so
+ far (4{nbsp}MiB) are definitely lost.
+
+Eight sub-buffers of 1{nbsp}MiB each::
+ Expect four times the tracer overhead of the configuration above,
+ but if LTTng needs to overwrite a sub-buffer, only the eighth of
+ event records so far (1{nbsp}MiB) are definitely lost.
+
+In discard mode, the sub-buffer count parameter is pointless: use two
+sub-buffers and set their size according to your requirements.
+
+
+[[channel-max-trace-file-size-count]]
+Maximum trace file size and count
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default, trace files can grow as large as needed.
+
+Set the maximum size of each trace file that LTTng writes of a given
+channel with the nloption:--tracefile-size option of the man:lttng-enable-channel(1)
+command.
+
+When the size of a trace file reaches the fixed maximum size of the
+channel, LTTng creates another file to contain the next event records.
+LTTng appends a file count to each trace file name in this case.
+
+If you set the trace file size attribute when you create a channel, the
+maximum number of trace files that LTTng creates is _unlimited_ by
+default. To limit them, use the nloption:--tracefile-count option of
+man:lttng-enable-channel(1). When the number of trace files reaches the
+fixed maximum count of the channel, LTTng overwrites the oldest trace
+file. This mechanism is called _trace file rotation_.
+
+[IMPORTANT]
+====
+Even if you don't limit the trace file count, always assume that LTTng
+manages all the trace files of the tracing session.
+
+In other words, there's no safe way to know if LTTng still holds a given
+trace file open with the trace file rotation feature.
+
+The only way to obtain an unmanaged, self-contained LTTng trace before
+you destroy the tracing session is with the tracing session rotation
+feature (see the <<rotation,Tracing session rotation>> section above),
+which is available since LTTng{nbsp}2.11.
+====
+
+
+[[channel-timers]]
+Timers
+~~~~~~
+Each channel can have up to three optional timers:
+
+Switch timer::
+ When this timer expires, a sub-buffer switch happens: for each ring
+ buffer of the channel, LTTng marks the current sub-buffer as
+ consumable and switches to an available one to record the next
+ events.
++
+A switch timer is useful to ensure that LTTng consumes and commits trace
+data to trace files or to a distant relay daemon (man:lttng-relayd(8))
+periodically in case of a low event throughput.
++
+Such a timer is also convenient when you use large sub-buffers (see the
+<<channel-sub-buf-size-count,Sub-buffer size and count>> section above)
+to cope with a sporadic high event throughput, even if the throughput is
+otherwise low.
++
+Set the period of the switch timer of a channel, or disable the timer
+altogether, with the nloption:--switch-timer option of the
+man:lttng-enable-channel(1) command.
+
+Read timer::
+ When this timer expires, LTTng checks for full, consumable
+ sub-buffers.
++
+By default, the LTTng tracers use an asynchronous message mechanism to
+signal a full sub-buffer so that a consumer daemon can consume it.
++
+When such messages must be avoided, for example in real-time
+applications, use this timer instead.
++
+Set the period of the read timer of a channel, or disable the timer
+altogether, with the nloption:--read-timer option of the
+man:lttng-enable-channel(1) command.
+
+Monitor timer::
+ When this timer expires, the consumer daemon samples some channel
+ (see the <<channel,{sect-channel}>> section above)
+ statistics to evaluate the following trigger conditions:
++
+--
+. The consumed buffer size of a given tracing session becomes greater
+ 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__
+ could be wrong for trigger condition type{nbsp}1: the consumed buffer
+ size of{nbsp}__C__ won't be part of the grand total.
+
+* The buffer usage trigger conditions (types{nbsp}2 and{nbsp}3)
+ for{nbsp}__C__ will never be satisfied.
+--
++
+See the <<trigger,TRIGGER>> section above to learn more about triggers.
++
+Set the period of the monitor timer of a channel, or disable the timer
+altogether, with the nloption:--monitor-timer option of the
+man:lttng-enable-channel(1) command.
+
+
+[[recording-event-rule]]
+{sect-recording-event-rule}
+---------------------------
+A _recording event rule_ is a specific type of event rule (see the
+<<"event-rule","{sect-event-rule}">> section above) of which the action is
+to serialize and record the matched event as an _event record_.
+
+Set the explicit conditions of a recording event rule when you create it
+with the man:lttng-enable-event(1) command. A recording event rule also
+has the following implicit conditions:
+
+* The recording event rule itself is enabled.
++
+A recording event rule is enabled on creation.
+
+* The channel to which the recording event rule is attached is enabled.
++
+A channel is enabled on creation.
++
+See the <<channel,{sect-channel}>> section above.
+
+* The tracing session of the recording event rule is active (started).
++
+A tracing session is inactive (stopped) on creation.
++
+See the <<session,{sect-session}>> section above.
+
+* 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
+creation.
++
+Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
+which processes are allowed to record events based on specific process
+attributes.
+
+You always attach a recording event rule to a channel, which belongs to
+a tracing 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
+available sub-buffers of the channel to which{nbsp}__E__ is attached.
+
+When multiple matching recording event rules are attached to the same
+channel, LTTng attempts to serialize and record the matched event
+_once_. In the following example, the second recording event rule is
+redundant when both are enabled:
+
+[role="term"]
+----
+$ lttng enable-event --userspace hello:world
+$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
+----
+
+List the recording event rules of a specific tracing session
+and/or channel with the man:lttng-list(1) and man:lttng-status(1)
+commands.
+
+Disable a recording event rule with the man:lttng-disable-event(1)
+command.
+
+As of LTTng{nbsp}{lttng_version}, you cannot remove a recording event
+rule: it exists as long as its tracing session exists.
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:lttng(1),
+man:lttng-relayd(8),
+man:lttng-sessiond(8)
lttng-crash(1)
==============
-:revdate: 8 April 2021
+:revdate: 3 May 2021
NAME
--------
man:babeltrace2(1),
man:lttng(1),
-man:lttng-create(1),
-man:lttng-relayd(8),
-man:lttng-sessiond(8),
-man:lttng-ust(3)
+man:lttng-create(1)
lttng-create(1)
===============
-:revdate: 8 April 2021
+:revdate: 3 May 2021
NAME
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
- [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR']
+ [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
Create a network streaming mode tracing session:
Create a snapshot mode tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot
- [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
+*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:
DESCRIPTION
-----------
The `lttng create` command creates a new tracing session for your Unix
-user.
-
-A tracing session 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:
-
-* Has its own name.
-
-* Has its own set of trace files, if any.
+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).
-* Has its own state of activity (started or stopped).
-
-* Has its own mode (local, network streaming,
- snapshot, or live).
-+
-See the <<modes,Tracing session modes>> section below to learn more.
-
-* Has its own channels (see man:lttng-enable-channel(1)) to which are
- attached their own recording event rules (see
- man:lttng-enable-event(1)).
-
-* Has its own process attribute tracking inclusion sets (see
- man:lttng-track(1)).
+See man:lttng-concepts(7) to learn more about tracing sessions.
Without the 'SESSION' argument, LTTng automatically generates a tracing
session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
genoption:--sessiond-path option. Avoid automatically spawning a session
daemon with the general genoption:--no-sessiond option.
-List the tracing sessions of your Unix user with the man:lttng-list(1)
-command.
+On success, the `create` command sets the current tracing session (see
+man:lttng-concepts(7) to learn more) to the created tracing session.
+
+Show the status of the current tracing session with the
+man:lttng-status(1) command.
+
+List the tracing 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
man:lttng-stop(1) commands.
Save and load a tracing session with the man:lttng-save(1) and
man:lttng-load(1) commands.
-Archive the current trace chunk (rotate) a tracing session with the
+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
man:lttng-rotate(1) command.
Destroy a tracing session with the man:lttng-destroy(1) command.
-Current tracing session
-~~~~~~~~~~~~~~~~~~~~~~~
-When you run the `create` 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
-session_.
-
-When you create a new tracing session with the `create` command, LTTng
-updates the current tracing session.
-
-The following man:lttng(1) commands select the current tracing session
-if you don't specify one:
-
-* man:lttng-add-context(1)
-* man:lttng-clear(1)
-* man:lttng-destroy(1)
-* man:lttng-disable-channel(1)
-* man:lttng-disable-event(1)
-* man:lttng-disable-rotation(1)
-* man:lttng-enable-channel(1)
-* man:lttng-enable-event(1)
-* man:lttng-enable-rotation(1)
-* man:lttng-regenerate(1)
-* man:lttng-rotate(1)
-* man:lttng-save(1)
-* man:lttng-snapshot(1)
-* man:lttng-start(1)
-* man:lttng-status(1)
-* man:lttng-stop(1)
-* man:lttng-track(1)
-* man:lttng-untrack(1)
-* man:lttng-view(1)
-
-Set the current tracing session manually with the
-man:lttng-set-session(1) command, without having to edit the `.lttngrc`
-file.
-
-
[[modes]]
Tracing session modes
~~~~~~~~~~~~~~~~~~~~~
-LTTng offers four tracing session modes:
+As documented in man:lttng-concepts(7), LTTng offers four tracing
+session modes:
[[local-mode]]Local mode::
Write the trace data to the local file system.
+
-The option:--output option specifies the trace path. Using
-option:--set-url=++file://++__DIR__ is equivalent to using
-option:--output='DIR'.
-+
-Disable the file system output with the
-option:--no-output option.
+The trace data output directory is:
+
-If you don't use any of the option:--output, option:--set-url, or
-option:--no-output options, then LTTng writes the trace data locally to
-the `$LTTNG_HOME/lttng-traces` directory (`$LTTNG_HOME` defaults to
-`$HOME`).
+With the option:--no-output option:::
+ None: the file system output is disabled.
+
+With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
+ The directory 'DIR'.
+
+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.
[[network-streaming-mode]]Network streaming mode::
Send the trace data over the network to a listening relay daemon
<<url-format,URL format>> section below).
[[snapshot-mode]]Snapshot mode (option:--snapshot option)::
- Don't write the trace data to the local file system by default
- (implicit option:--no-output option): only write the trace data to
- the local file system or send it to a listening relay daemon
- (man:lttng-relayd(8)) when LTTng takes a snapshot.
+ Only write the trace data to the local file system or send it to a
+ listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
+ snapshot (see the man:lttng-snapshot(1) command).
+
-LTTng automatically configures the channels of such a tracing session to
-be snapshot-ready on creation (see man:lttng-enable-channel(1)).
+With this mode, LTTng:
+
-LTTng takes a snapshot of such a tracing session when:
-+
---
-* You run the man:lttng-snapshot(1) command.
-* LTTng executes a `snapshot-session` trigger action (see
- man:lttng-add-trigger(1)).
---
+With the option:--no-output option:::
+ Does :not: add any snapshot output to the created tracing
+ 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.
+
+Otherwise:::
+ Adds an automatic snapshot output named `snapshot-1` to the created
+ tracing session.
+
-Set the default snapshot output destination with the
-option:--set-url option, or with the option:--ctrl-url and
-option:--data-url options (see the <<url-format,URL format>> section
-below).
+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
+date/time.
[[live-mode]]Live mode (option:--live option)::
Send the trace data over the network to a listening relay daemon
[[url-format]]
URL format
~~~~~~~~~~
-The argument of the option:--set-url, option:--ctrl-url, and
-option:--data-url options is an URL.
+The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
+option:--data-url='URL' options is an URL.
-There are two available URL formats.
+There are two available 'URL' formats.
Local format::
+
{nbsp}
+
This format is only available when you create the tracing session in
-network streaming, snapshot, or live mode (see the <<modes,Tracing
-session modes>> section above).
+network streaming, snapshot (option:--snapshot), or live (option:--live)
+mode (see the <<modes,Tracing session modes>> section above).
+
'NETPROTO':::
Network protocol, amongst:
--
+
('HOST' | 'IPADDR'):::
- Hostname or IP address (IPv6 address *must* be enclosed in square
- brackets (`[` and{nbsp}`]`); see
- https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]).
+ Hostname or IP address.
++
+IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
+see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
'CTRLPORT':::
Control TCP port.
option:--snapshot::
Create the tracing session in snapshot mode.
+
-This is equivalent to using the option:--no-output option and creating
-all the channels of this new tracing session with the
-nloption:--override and nloption:--output=++mmap++ options (see
-man:lttng-enable-channel(1)).
+This is equivalent to:
++
+* One of:
++
+--
+With the option:--no-output option::
+ Not adding any snapshot output after LTTng creates the tracing
+ 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.
+
+Otherwise::
+ Adding an automatic snapshot output named `snapshot-1` immediately
+ after LTTng creates the tracing 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
+date/time.
+--
+
+* Forcing all the channels to be created for the tracing session to be
+ configured with the nloption:--override and nloption:--output=++mmap++
+ options (see man:lttng-enable-channel(1)).
Output
~~~~~~
option:--no-output::
- In local mode (see the <<modes,Tracing session modes>> section
- above), do :not: write any trace data.
+ Depending on the tracing session mode (see the <<modes,Tracing
+ session modes>> section above):
+
-You may :not: use this option with the option:--output option.
+Local mode:::
+ Disable the file system output.
+
+Snapshot mode (option:--snapshot option):::
+ Do :not: add a snapshot output after creating the tracing session.
option:-o 'DIR', option:--output='DIR'::
- In local mode, set the trace output path to 'DIR'.
-+
-You may :not: use this option with the option:--no-output option.
+ Equivalent to option:--set-url=++file://++__DIR__.
option:--shm-path='DIR'::
Set the path of the directory containing the shared memory files
Set the control path URL to 'URL'.
+
You must also use the option:--data-url option.
++
+Not available in local mode (see the <<modes,Tracing 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.
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).
++
+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.
option:-U 'URL', option:--set-url='URL'::
Set the destination URL of the control path and trace data to 'URL'.
+
-This URL stays the same as long as the tracing session exists.
+This URL remains unchanged as long as the tracing session exists.
++
+Depending on the tracing session mode (see the <<modes,Tracing session
+modes>> section above):
+
-In local mode (see the <<modes,Tracing session modes>> section above),
-'URL' must start with `file://`, followed with the destination directory
-path on the local file system.
+Local mode:::
+ 'URL' must start with `file://`, followed with the destination
+ directory path on the local file system.
+
+Network streaming and live modes:::
+ Equivalent to using both the option:--ctrl-url and option:--data-url
+ options.
+
+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.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-destroy(1),
man:lttng-enable-channel(1),
+man:lttng-list(8),
man:lttng-relayd(8),
man:lttng-rotate(1),
+man:lttng-save(1),
man:lttng-sessiond(8),
man:lttng-set-session(1),
man:lttng-start(1),
-man:lttng-stop(1),
+man:lttng-status(8),
man:lttng-track(1)
lttng-destroy(1)
================
-:revdate: 12 April 2021
+:revdate: 3 May 2021
NAME
DESCRIPTION
-----------
-The `lttng destroy` command destroys one or more tracing sessions
-previously created with the man:lttng-create(1) command.
-
-``Destroying'' a tracing session means freeing the resources acquired by
-the LTTng daemons and tracers 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
-session mode.
-
-Use the `destroy` command to destroy:
+The `lttng destroy` command destroys:
With the 'SESSION' argument::
The tracing session named 'SESSION'.
With the option:--all option::
- *All* the tracing sessions of your Unix user,
- as listed in the output of `lttng list` (see man:lttng-list(1)).
+ *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)).
++
+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-create(1) and
- man:lttng-set-session(1) to learn more about the current tracing
- session).
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+
In that case, the current tracing session becomes nonexistent.
+See man:lttng-concepts(7) to learn more about tracing sessions.
+
+``Destroying'' a tracing 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
+session mode.
+
The `destroy` command stops any tracing activity within the selected
-tracing session(s). By default, the command runs the implicit
+tracing session(s). By default, the command runs an implicit
man:lttng-stop(1) command to ensure that the trace data of the tracing
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 becomes valid.
+when it/they become valid.
If, for a tracing session{nbsp}__TS__ to destroy with the `destroy`
command, the following statements are true:
-* You don't use the option:--no-wait option.
+* You don't specify the option:--no-wait option.
-* LTTng archived the current trace chunk (see man:lttng-rotate(1) and
- man:lttng-enable-rotation(1)) of{nbsp}__TS__ at least once during its
- lifetime.
+* LTTng archived the current trace chunk (see man:lttng-concepts(7))
+ of{nbsp}__TS__ at least once during its lifetime.
Then all the subdirectories of the output directory of{nbsp}__TS__
(local or remote) are considered trace chunk archives once the `destroy`
option:-a, option:--all::
- Destroy all the tracing sessions of your Unix user, as listed in the
- output of man:lttng-list(1).
+ 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'.
option:-n, option:--no-wait::
Do :not: ensure that the trace data of the tracing session(s) to
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-create(1),
-man:lttng-list(1),
-man:lttng-set-session(1)
+man:lttng-list(1)
lttng-disable-channel(1)
========================
-:revdate: 21 April 2021
+:revdate: 29 April 2021
NAME
----
DESCRIPTION
-----------
The `lttng disable-channel` command disables one or more channels
-previously enabled with the man:lttng-enable-channel(1) command.
+previously enabled with the man:lttng-enable-channel(1) command
+which belong to:
-A channel always belongs to a tracing session (see man:lttng-create(1)
-to create a tracing session). Without the option:--session option, the
-`disable-channel` command disables one or more channels of the current
-tracing session (see man:lttng-create(1) and man:lttng-set-session(1) to
-learn more about the current tracing session).
+With the option:--session='SESSION' option::
+ The tracing 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).
+
+See man:lttng-concepts(7) to learn more about channels.
The `disable-channel` command disables one channel per 'CHANNEL'
argument.
Disable one or more user space channels.
-Target
-~~~~~~
+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.
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-enable-channel(1)
lttng-disable-event(1)
======================
-:revdate: 21 April 2021
+:revdate: 3 May 2021
NAME
-----------
The `lttng disable-event` command disables one or more enabled recording
event rules previously created with the man:lttng-enable-event(1)
-command.
+command which belong to:
+
+With the option:--session='SESSION' option::
+ The tracing 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).
+
+With the option:--channel='CHANNEL' option::
+ The channel named 'CHANNEL'.
+
+Without the option:--channel option::
+ The channel named `channel0`.
+
+See man:lttng-concepts(7) to learn more about recording event rules.
As of LTTng{nbsp}{lttng_version}, the `disable-event` command can only
find recording event rules to disable by their instrumentation point
event rules having a specific instrumentation point log level condition,
for example.
-List the existing recording event rules of a given tracing session
+List the recording event rules of a given tracing session
and/or channel with the man:lttng-list(1) command.
Without the option:--all-events option, the `disable-event` command
disable, as listed in the output of `lttng list` (see
man:lttng-list(1)).
-Without the option:--channel option, the `disable-event` command selects
-the channel named `channel0`.
-
-Without the option:--session option, the `disable-event` command selects
-the current tracing session (see man:lttng-create(1) and
-man:lttng-set-session(1) to learn more about the current tracing
-session).
-
You may disable an enabled recording event rule regardless of the
activity (started or stopped) of its tracing session (see
man:lttng-start(1) and man:lttng-stop(1)).
~~~~~~~~~~~~~~~~~~~~
option:-a, option:--all-events::
Disable recording event rules regardless of their event name
- condition is.
+ condition.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-enable-event(1),
man:lttng-list(1)
lttng-disable-rotation(1)
=========================
-:revdate: 21 April 2021
+:revdate: 30 April 2021
NAME
----
-lttng-disable-rotation - Unset a tracing session rotation schedule
+lttng-disable-rotation - Unset an LTTng tracing session rotation schedule
SYNOPSIS
The tracing session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-create(1) and
- man:lttng-set-session(1) to learn more about the current tracing
- session).
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+
+See man:lttng-concepts(7) to learn more about the tracing session
+rotation and trace chunk concepts.
include::common-cmd-options-head.txt[]
lttng-enable-channel(1)
=======================
-:revdate: 9 November 2018
+:revdate: 3 May 2021
NAME
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
- [option:--overwrite] [option:--output=(`mmap` | `splice`)]
+ [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)]
[option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
[option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
- [option:--monitor-timer='PERIODUS']
- [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
+ [option:--monitor-timer='PERIODUS'] [option:--buffers-global]
+ [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
[option:--session='SESSION'] 'CHANNEL'
Create a user space channel:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
- [option:--overwrite | option:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid]
+ [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS']
+ [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid]
[option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
[option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
[option:--monitor-timer='PERIODUS']
- [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
+ [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
[option:--session='SESSION'] 'CHANNEL'
-Enable existing channel(s):
+Enable channel(s):
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
DESCRIPTION
-----------
-The `lttng enable-channel` command can create a new channel, or enable
-one or more existing and disabled ones.
-
-A channel is the owner of sub-buffers holding recorded events. Recording
-event rules, when created using man:lttng-enable-event(1), are always
-assigned to a channel. When creating a new channel, many parameters
-related to those sub-buffers can be fine-tuned. They are described in
-the subsections below.
+The `lttng enable-channel` command does one of:
-When 'CHANNEL' does not name an existing channel, a channel named
-'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
-is enabled.
+* Create a channel named 'CHANNEL'.
-Note that the man:lttng-enable-event(1) command can automatically
-create default channels when no channel exist.
+* Enable one or more disabled channels named 'CHANNEL'
+ (non-option argument, comma-separated).
-A channel is always contained in a tracing session
-(see man:lttng-create(1) for creating a tracing session). The
-session in which a channel is created using `lttng enable-channel` can
-be specified using the option:--session option. If the option:--session
-option is omitted, the current tracing session is targeted.
+See man:lttng-concepts(7) to learn more about channels.
-Existing enabled channels can be disabled using
-man:lttng-disable-channel(1). Channels of a given session can be
-listed using man:lttng-list(1).
+The channel(s) to create or enable belong to:
-See the <<limitations,LIMITATIONS>> section below for a list of
-limitations of this command to consider.
+With the option:--session='SESSION' option::
+ The tracing 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).
-Event loss modes
-~~~~~~~~~~~~~~~~
-LTTng tracers are non-blocking by default: when no empty sub-buffer
-exists, losing events is acceptable when the alternative would be to
-cause substantial delays in the instrumented application's execution.
-
-LTTng privileges performance over integrity, aiming at perturbing the
-traced system as little as possible in order to make tracing of subtle
-race conditions and rare interrupt cascades possible.
-
-You can allow the user space tracer to block with a
-option:--blocking-timeout option set to a positive value or to `inf`,
-and with an application which is instrumented with LTTng-UST started
-with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable. See
-man:lttng-ust(3) for more details.
-
-When it comes to losing events because no empty sub-buffer is available,
-the channel's event loss mode, specified by one of the option:--discard
-and option:--overwrite options, determines what to do amongst:
-
-Discard::
- Drop the newest events until a sub-buffer is released.
-
-Overwrite::
- Clear the sub-buffer containing the oldest recorded events and start
- recording the newest events there. This mode is sometimes called
- _flight recorder mode_ because it behaves like a flight recorder:
- always keep a fixed amount of the latest data.
-
-Which mechanism to choose depends on the context: prioritize the newest
-or the oldest events in the ring buffer?
-
-Beware that, in overwrite mode (option:--overwrite option), a whole
-sub-buffer is abandoned as soon as a new event doesn't find an empty
-sub-buffer, whereas in discard mode (option:--discard option), only the
-event that doesn't fit is discarded.
-
-Also note that a count of lost events is incremented and saved in the
-trace itself when an event is lost in discard mode, whereas no
-information is kept when a sub-buffer gets overwritten before being
-committed.
-
-The probability of losing events, if it is experience in a given
-context, can be reduced by fine-tuning the sub-buffers count and size
-(see next subsection).
-
-
-Sub-buffers count and size
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-The option:--num-subbuf and option:--subbuf-size options respectively
-set the number of sub-buffers and their individual size when creating
-a new channel.
-
-Note that there is a noticeable tracer's CPU overhead introduced when
-switching sub-buffers (marking a full one as consumable and switching
-to an empty one for the following events to be recorded). Knowing this,
-the following list presents a few practical situations along with how
-to configure sub-buffers for them when creating a channel in overwrite
-mode (option:--overwrite option):
-
-High event throughput::
- In general, prefer bigger sub-buffers to lower the risk of losing
- events. Having bigger sub-buffers also ensures a lower sub-buffer
- switching frequency. The number of sub-buffers is only meaningful
- if the channel is enabled in overwrite mode: in this case, if a
- sub-buffer overwrite happens, the other sub-buffers
- are left unaltered.
-
-Low event throughput::
- In general, prefer smaller sub-buffers since the risk of losing
- events is already low. Since events happen less frequently, the
- sub-buffer switching frequency should remain low and thus the
- tracer's overhead should not be a problem.
-
-Low memory system::
- If the target system has a low memory limit, prefer fewer first,
- then smaller sub-buffers. Even if the system is limited in memory,
- it is recommended to keep the sub-buffers as big as possible to
- avoid a high sub-buffer switching frequency.
-
-In discard mode (option:--discard option), the sub-buffers count
-parameter is pointless: using two sub-buffers and setting their size
-according to the requirements of the context is fine.
-
-
-Switch timer
-~~~~~~~~~~~~
-When a channel's switch timer fires, a sub-buffer switch happens. This
-timer may be used to ensure that event data is consumed and committed
-to trace files periodically in case of a low event throughput.
-
-It's also convenient when big sub-buffers are used to cope with sporadic
-high event throughput, even if the throughput is normally lower.
-
-Use the option:--switch-timer option to control the switch timer's
-period of the channel to create.
-
-
-Read timer
-~~~~~~~~~~
-By default, an internal notification mechanism is used to signal a full
-sub-buffer so that it can be consumed. When such notifications must be
-avoided, for example in real-time applications, the channel's read timer
-can be used instead. When the read timer fires, sub-buffers are checked
-for consumption when they are full.
-
-Use the option:--read-timer option to control the read timer's period of
-the channel to create.
-
-
-Monitor timer
-~~~~~~~~~~~~~
-When a channel's monitor timer fires, its registered trigger conditions
-are evaluated using the current values of its properties (for example,
-the current usage of its sub-buffers). When a trigger condition is true,
-LTTng executes its associated action. The only type of action currently
-supported is to notify one or more user applications.
-
-See the installed $$C/C++$$ headers in `lttng/action`,
-`lttng/condition`, `lttng/notification`, and `lttng/trigger` to learn
-more about application notifications and triggers.
-
-Use the option:--monitor-timer option to control the monitor timer's
-period of the channel to create.
+NOTE: The man:lttng-enable-event(1) command can automatically create a
+default channel when no channel exists for the provided tracing domain.
+List the channels of a given tracing session with the
+man:lttng-list(1) and man:lttng-status(1) commands.
-Buffering scheme
-~~~~~~~~~~~~~~~~
-In the user space tracing domain, two buffering schemes are available
-when creating a channel:
+Disable an enabled channel with the man:lttng-disable-channel(1)
+command.
-Per-process buffering (option:--buffers-pid option)::
- Keep one ring buffer per process.
+[IMPORTANT]
+====
+As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
+operations with the `enable-channel` command:
-Per-user buffering (option:--buffers-uid option)::
- Keep one ring buffer for all the processes of a single user.
+* Change an attribute of an existing channel.
-The per-process buffering scheme consumes more memory than the per-user
-option if more than one process is instrumented for LTTng-UST.
-However, per-process buffering ensures that one process having a high
-event throughput won't fill all the shared sub-buffers, only its own.
+* Enable a disabled channel once its tracing session has been active
+ (started; see man:lttng-start(1)) at least once.
-The Linux kernel tracing domain only has one available buffering scheme
-which is to use a single ring buffer for the whole system
-(option:--buffers-global option).
+* Create a channel once its tracing 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.
+====
-Trace files limit and size
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-By default, trace files can grow as large as needed. The maximum size
-of each trace file written by a channel can be set on creation using the
-option:--tracefile-size option. When such a trace file's size reaches
-the channel's fixed maximum size, another trace file is created to hold
-the next recorded events. A file count is appended to each trace file
-name in this case.
-If the option:--tracefile-size option is used, the maximum number of
-created trace files is unlimited. To limit them, the
-option:--tracefile-count option can be used. This option is always used
-in conjunction with the option:--tracefile-size option.
+include::common-cmd-options-head.txt[]
-For example, consider this command:
-[role="term"]
-----
-$ lttng enable-channel --kernel --tracefile-size=4096 \
- --tracefile-count=32 my-channel
-----
+Tracing domain
+~~~~~~~~~~~~~~
+One of:
-Here, for each stream, the maximum size of each trace file is
-4 kiB and there can be a maximum of 32 different files. When there is
-no space left in the last file, _trace file rotation_ happens: the first
-file is cleared and new sub-buffers containing events are written there.
+option:-k, option:--kernel::
+ Create or enable channels in the Linux kernel domain.
-LTTng does not guarantee that you can view the trace of an active
-tracing session before you run the man:lttng-stop(1) command, even
-with multiple trace files, because LTTng could overwrite them at any
-moment, or some of them could be incomplete. You can archive a
-tracing session's current trace chunk while the tracing session is
-active to obtain an unmanaged and self-contained LTTng trace: see
-the man:lttng-rotate(1) and man:lttng-enable-rotation(1) commands.
+option:-u, option:--userspace::
+ Create or enable channels in the user space domain.
-include::common-cmd-options-head.txt[]
+Recording target
+~~~~~~~~~~~~~~~~
+option:-s 'SESSION', option:--session='SESSION'::
+ Create or enable channels in the tracing session named 'SESSION'
+ instead of the current tracing session.
-Domain
-~~~~~~
+Buffering scheme
+~~~~~~~~~~~~~~~~
One of:
-option:-k, option:--kernel::
- Enable channel in the Linux kernel domain.
+option:--buffers-global::
+ Allocate a single set of ring buffers for the whole system.
++
+Only available with the option:--kernel option.
++
+As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
+for the Linux kernel tracing domain, but this may change in the future.
-option:-u, option:--userspace::
- Enable channel in the user space domain.
+option:--buffers-pid::
+ Allocate one set of ring buffers (one per CPU) for each instrumented
+ process of:
++
+--
+If you connect to the root session daemon::
+ All Unix users.
++
+See the ``Session daemon connection'' section of man:lttng(1) to learn
+how a user application connects to a session daemon.
+Otherwise::
+ Your Unix user.
+--
++
+Only available with the option:--userspace option.
-Target
-~~~~~~
-option:-s 'SESSION', option:--session='SESSION'::
- Create or enable channel in the tracing session named 'SESSION'
- instead of the current tracing session.
+option:--buffers-uid::
+ Allocate one set of ring buffers (one per CPU) shared by all the
+ instrumented processes of:
++
+--
+If you connect to the root session daemon::
+ Each Unix user.
++
+See the ``Session daemon connection'' section of man:lttng(1) to learn
+how a user application connects to a session daemon.
+
+Otherwise::
+ Your Unix user.
+--
++
+Only available with the option:--userspace option.
++
+As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
+for the user space tracing domain, but this may change in the future.
-Event loss mode
-~~~~~~~~~~~~~~~
+Event record loss mode
+~~~~~~~~~~~~~~~~~~~~~~
option:--blocking-timeout='TIMEOUTUS'::
- Set the channel's blocking timeout value to 'TIMEOUTUS' µs for
- instrumented applications executed with a set
- `LTTNG_UST_ALLOW_BLOCKING` environment variable:
+ Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs
+ for instrumented applications executed with a set
+ `LTTNG_UST_ALLOW_BLOCKING` environment variable.
++
+'TIMEOUTUS' is one of:
+
--
-0 (default)::
+`0` (default)::
Do not block (non-blocking mode).
`inf`::
- Block forever until room is available in the sub-buffer to write the
- event record.
+ Block forever until a sub-buffer is available to write the event
+ record.
-__n__, a positive value::
- Wait for at most __n__ µs when trying to write into a sub-buffer.
- After __n__ µs, discard the event record.
+__N__, a positive value::
+ Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer.
+ After __N__{nbsp}µs, discard the event record.
--
+
-This option is only available with the option:--userspace option and
-without the option:--overwrite option.
+This option is only available with both the option:--userspace and
+option:--discard options.
One of:
option:--discard::
- Discard events when sub-buffers are full (default).
+ Discard event records when there's no available sub-buffer.
++
+As of LTTng{nbsp}{lttng_version}, this is the default event record loss
+mode, but this may change in the future.
option:--overwrite::
- Flight recorder mode: always keep a fixed amount of the latest
- data.
+ Overwrite the whole sub-buffer containing the oldest event records
+ when there's no available sub-buffer (flight recorder mode).
Sub-buffers
~~~~~~~~~~~
option:--num-subbuf='COUNT'::
- Use 'COUNT' sub-buffers. Rounded up to the next power of two.
+ Use 'COUNT' sub-buffers per ring buffer.
++
+The effective value is 'COUNT' rounded up to the next power of two.
+
Default values:
+
-* option:--userspace and option:--buffers-uid options:
- {default_ust_uid_channel_subbuf_num}
-* option:--userspace and option:--buffers-pid options:
- {default_ust_pid_channel_subbuf_num}
-* option:--kernel option: {default_kernel_channel_subbuf_num}
-* `metadata` channel: {default_metadata_subbuf_num}
+option:--userspace and option:--buffers-uid options:::
+ +{default_ust_uid_channel_subbuf_num}+
+option:--userspace and option:--buffers-pid options:::
+ +{default_ust_pid_channel_subbuf_num}+
+option:--kernel and option:--buffers-global options:::
+ +{default_kernel_channel_subbuf_num}+
+`metadata` channel:::
+ +{default_metadata_subbuf_num}+
option:--output='TYPE'::
Set channel's output type to 'TYPE'.
+
-Available types: `mmap` (always available) and `splice` (only available
-with the option:--kernel option).
+'TYPE' is one of:
++
+--
+`mmap`:::
+ Share ring buffers between the tracer and the consumer daemon with
+ the man:mmap(2) system call.
+
+`splice`:::
+ Share ring buffers between the tracer and the consumer daemon
+ with the man:splice(2) system call.
++
+Only available with the option:--kernel option.
+--
+
Default values:
+
-* option:--userspace and option:--buffers-uid options: `mmap`
-* option:--userspace and option:--buffers-pid options: `mmap`
-* option:--kernel option: `splice`
-* `metadata` channel: `mmap`
+option:--userspace and option:--buffers-uid options:::
+ `mmap`
+option:--userspace and option:--buffers-pid options:::
+ `mmap`
+option:--kernel and option:--buffers-global options:::
+ `splice`
+`metadata` channel:::
+ `mmap`
option:--subbuf-size='SIZE'::
- Set the individual size of sub-buffers to 'SIZE' bytes.
- The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
- Rounded up to the next power of two.
+ Set the size of each sub-buffer to 'SIZE' bytes.
++
+The effective value is 'SIZE' rounded up to the next power of two.
++
+The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
+supported.
+
The minimum sub-buffer size, for each tracer, is the maximum value
-between the default below and the system's page size. The following
-command shows the current system's page size: `getconf PAGE_SIZE`.
+between the default below and the system page size (see man:getconf(1)
+with the `PAGE_SIZE` variable).
+
Default values:
+
-* option:--userspace and option:--buffers-uid options:
- {default_ust_uid_channel_subbuf_size}
-* option:--userspace and option:--buffers-pid options:
- {default_ust_pid_channel_subbuf_size}
-* option:--kernel option: {default_kernel_channel_subbuf_size}
-* `metadata` channel: {default_metadata_subbuf_size}
-
-
-Buffering scheme
-~~~~~~~~~~~~~~~~
-One of:
-
-option:--buffers-global::
- Use shared sub-buffers for the whole system (only available with the
- option:--kernel option).
-
-option:--buffers-pid::
- Use different sub-buffers for each traced process (only available
- with the the option:--userspace option). This is the default
- buffering scheme for user space channels.
-
-option:--buffers-uid::
- Use shared sub-buffers for all the processes of the user running
- the command (only available with the option:--userspace option).
+option:--userspace and option:--buffers-uid options:::
+ +{default_ust_uid_channel_subbuf_size}+
+option:--userspace and option:--buffers-pid options:::
+ +{default_ust_pid_channel_subbuf_size}+
+option:--kernel and option:--buffers-global options:::
+ +{default_kernel_channel_subbuf_size}+
+`metadata` channel:::
+ +{default_metadata_subbuf_size}+
Trace files
~~~~~~~~~~~
option:--tracefile-count='COUNT'::
- Limit the number of trace files created by this channel to
- 'COUNT'. 0 means unlimited. Default:
- {default_channel_tracefile_count}.
+ Limit the number of trace files which LTTng writes for this channel
+ to 'COUNT'.
+
-Use this option in conjunction with the option:--tracefile-size option.
+'COUNT' set to `0` means ``unlimited''.
+
-The file count within a stream is appended to each created trace
-file. If 'COUNT' files are created and more events need to be recorded,
-the first trace file of the stream is cleared and used again.
+Default: +{default_channel_tracefile_count}+.
++
+You must also use the option:--tracefile-size option with this option.
option:--tracefile-size='SIZE'::
- Set the maximum size of each trace file written by
- this channel within a stream to 'SIZE' bytes. 0 means unlimited.
- Default: {default_channel_tracefile_size}.
+ Set the maximum size of each trace file which LTTng writes for
+ this channel to __SIZE__{nbsp}bytes.
++
+'SIZE' set to `0` means ``unlimited''.
++
+Default: +{default_channel_tracefile_size}+.
+
-Note: traces generated with this option may inaccurately report
-discarded events as of CTF 1.8.
+NOTE: Data streams which LTTng writes for a channel configured with this
+option may inaccurately report discarded event records as of
+CTF{nbsp}1.8.
Timers
~~~~~~
-option:--monitor-timer::
- Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
- disabled monitor timer.
+option:--monitor-timer='PERIODUS'::
+ Set the period of the monitor timer of the channel to
+ __PERIODUS__{nbsp}µs.
++
+Set 'PERIODUS' to `0` to disable the monitor timer.
+
Default values:
+
-* option:--userspace and option:--buffers-uid options:
- {default_ust_uid_channel_monitor_timer}
-* option:--userspace and option:--buffers-pid options:
- {default_ust_pid_channel_monitor_timer}
-* option:--kernel option: {default_kernel_channel_monitor_timer}
-
-option:--read-timer::
- Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
- disabled read timer.
+option:--userspace and option:--buffers-uid options:::
+ +{default_ust_uid_channel_monitor_timer}+
+option:--userspace and option:--buffers-pid options:::
+ +{default_ust_pid_channel_monitor_timer}+
+option:--kernel and option:--buffers-global options:::
+ +{default_kernel_channel_monitor_timer}+
+
+option:--read-timer='PERIODUS'::
+ Set the period of the read timer of the channel to
+ __PERIODUS__{nbsp}µs.
++
+Set 'PERIODUS' to `0` to disable the read timer.
+
Default values:
+
-* option:--userspace and option:--buffers-uid options:
- {default_ust_uid_channel_read_timer}
-* option:--userspace and option:--buffers-pid options:
- {default_ust_pid_channel_read_timer}
-* option:--kernel option: {default_kernel_channel_read_timer}
-* `metadata` channel: {default_metadata_read_timer}
+option:--userspace and option:--buffers-uid options:::
+ +{default_ust_uid_channel_read_timer}+
+option:--userspace and option:--buffers-pid options:::
+ +{default_ust_pid_channel_read_timer}+
+option:--kernel and option:--buffers-global options:::
+ +{default_kernel_channel_read_timer}+
+`metadata` channel:::
+ +{default_metadata_read_timer}+
option:--switch-timer='PERIODUS'::
- Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
- a disabled switch timer.
+ Set the period of the switch timer of the channel to
+ __PERIODUS__{nbsp}µs.
++
+Set 'PERIODUS' to `0` to disable the switch timer.
+
Default values:
+
-* option:--userspace and option:--buffers-uid options:
- {default_ust_uid_channel_switch_timer}
-* option:--userspace and option:--buffers-pid options:
- {default_ust_pid_channel_switch_timer}
-* option:--kernel option: {default_kernel_channel_switch_timer}
-* `metadata` channel: {default_metadata_switch_timer}
+option:--userspace and option:--buffers-uid options:::
+ +{default_ust_uid_channel_switch_timer}+
+option:--userspace and option:--buffers-pid options:::
+ +{default_ust_pid_channel_switch_timer}+
+option:--kernel and option:--buffers-global options:::
+ +{default_kernel_channel_switch_timer}+
+`metadata` channel:::
+ +{default_metadata_switch_timer}+
include::common-cmd-help-options.txt[]
-[[limitations]]
-LIMITATIONS
------------
-As of this version of LTTng, it is not possible to perform the following
-actions with the `lttng enable-channel` command:
-
-* Reconfigure a channel once it is created.
-* Re-enable a disabled channel once its tracing session has been active
- at least once.
-* Create a channel once its tracing 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.
-
-
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng-disable-channel(1),
man:lttng(1),
-man:lttng-ust(3)
+man:lttng-concepts(7),
+man:lttng-disable-channel(1),
+man:lttng-list(1)
lttng-enable-event(1)
=====================
-:revdate: 13 April 2021
+:revdate: 3 May 2021
NAME
* Create one or more recording event rules.
-* Enable one or more existing, disabled recording event rules.
+* Enable one or more disabled recording event rules.
+
See the <<enable,Enable a disabled recording event rule>> section
below.
-An _instrumentation point_ is a point, within a piece of software,
-which, when executed, creates an LTTng _event_.
+See man:lttng-concepts(7) to learn more about instrumentation points,
+events, recording event rules, and event records.
-LTTng offers various types of instrumentation; see the
-<<inst-point-type-cond,Instrumentation point type condition>> section
-below to learn about them.
-
-An _event rule_ is a set of conditions to match a set of events. A
-_recording event rule_ is a specific type of event rule of which the
-associated action is to serialize and record the matched event.
-
-When LTTng creates an event{nbsp}__E__, a recording event
-rule{nbsp}__ER__ is said to __match__{nbsp}__E__ when{nbsp}__E__
-satisfies *all* the conditions of{nbsp}__ER__. This concept is similar
-to a regular expression which matches a set of strings.
-
-When a recording event rule matches an event, LTTng _emits_ the event,
-therefore attempting to serialize and record it to one of the
-sub-buffers of its attached channel (see man:lttng-enable-channel(1) to
-learn more about LTTng channels).
-
-Without the option:--channel option, the `enable-event` command selects
-the channel named `channel0`. When the `enable-event` command creates a
-recording event rule, it automatically creates the `channel0` channel
-(for the specified tracing domain in the selected tracing session) if it
-doesn't exist.
-
-When multiple matching recording event rules are attached to the same
-channel, LTTng attempts to serialize and record the matched event
-_once_. In the following example, the second recording event
-rule is redundant when both are enabled:
-
-[role="term"]
-----
-$ lttng enable-event --userspace hello:world
-$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
-----
+The recording event rule(s) to create or enable belong to:
-Without the option:--session option, the `enable-event` command selects
-the current tracing session (see man:lttng-create(1) and
-man:lttng-set-session(1) to learn more about the current tracing
-session).
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-[NOTE]
-====
-The event creation and emission processes are documentation concepts to
-help understand the journey from an instrumentation point to the
-serialization and recording of an event.
-
-The actual creation of an event can be costly because LTTng needs to
-evalute the arguments of the instrumentation point.
-
-In practice, LTTng implements various optimizations for the Linux kernel
-and user space tracing domains (option:--kernel and option:--userspace
-options) to avoid actually creating an event when the tracer knows,
-thanks to properties which are independent from the event payload and
-current context, that it would never emit such an event. Those
-properties are:
-
-* The status of the rule itself (enabled or disabled).
-* The status of the channel (enabled or disabled; see
- man:lttng-enable-channel(1) and man:lttng-disable-channel(1)).
-* The activity of the tracing session (started or stopped; see
- man:lttng-start(1) and man:lttng-stop(1)).
-* The instrumentation point type (see the
- <<inst-point-type-cond,Instrumentation point type>> section below).
-* The instrumentation point name (or event name)
- (see the <<event-name-cond,Event name condition>> section below).
-* The instrumentation point log level (see the
- <<inst-point-log-level-cond,Instrumentation point log level condition>>
- section below).
-
-In other words: if, for a given instrumentation point{nbsp}__IP__, the
-LTTng tracer knows that it would never emit and record an event,
-executing{nbsp}__IP__ represents a simple boolean variable check and,
-for the kernel tracer, a few process attribute checks.
-====
+Without the option:--session option::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+
+With the option:--channel='CHANNEL' option::
+ The channel named 'CHANNEL'.
-List the existing recording event rules of a given tracing session
-and/or channel with the man:lttng-list(1) command.
+Without the option:--channel option::
+ The channel named `channel0`.
++
+If such a channel doesn't exist, the `enable-event` automatically
+creates it.
-Disable an existing, enabled recording event rule with the
+List the recording event rules of a specific tracing session
+and/or channel with the man:lttng-list(1) and man:lttng-status(1)
+commands.
+
+Disable an enabled recording event rule with the
man:lttng-disable-event(1) command.
-Recording event rule overview
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Overview of recording event rule conditions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must
satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that
is:
+
A recording event rule is enabled on creation.
+
-Enable an existing, disabled recording event rule with the
-`enable-event` command.
+Enable a disabled recording event rule with the `enable-event` command.
* The channel to which{nbsp}__ER__ is attached is enabled.
+
A channel is enabled on creation.
+
-Enable an existing, disabled channel with the
-man:lttng-enable-channel(1) command.
+Enable a disabled channel with the man:lttng-enable-channel(1) command.
* The tracing session of{nbsp}__ER__ is active (started).
+
+
Start an inactive tracing session with the man:lttng-start(1) command.
-* The process for which LTTng creates{nbsp}__E__ to match is allowed to
- record events.
+* The process for which LTTng creates{nbsp}__E__ is allowed to record
+ events.
+
All processes are allowed to record events on tracing session
creation.
~~~~~~~~~~~~~~~~~
When LTTng records an event{nbsp}__E__, the resulting event record has a
name which depends on the instrumentation point type condition (see the
-<<inst-point-type-cond,Instrumentation point type condition>> section)
-of the recording event rule which matched{nbsp}__E__:
+<<inst-point-type-cond,Instrumentation point type condition>> section
+above) of the recording event rule which matched{nbsp}__E__:
LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
Full name of the tracepoint from which LTTng creates{nbsp}__E__.
[[enable]]
Enable a disabled recording event rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `enable-event` command can enable an existing, disabled recording
-event rule, as listed in the output of the man:lttng-list(1) command.
+The `enable-event` command can enable a disabled recording event rule,
+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
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-disable-event(1),
man:lttng-enable-channel(1),
man:lttng-list(1),
lttng-enable-rotation(1)
========================
-:revdate: 21 April 2021
+:revdate: 3 May 2021
NAME
----
-lttng-enable-rotation - Set a tracing session rotation schedule
+lttng-enable-rotation - Set an LTTng tracing session rotation schedule
SYNOPSIS
The tracing session named 'SESSION'.
Without the option:--session option::
- The current tracing session (see man:lttng-create(1) and
- man:lttng-set-session(1) to learn more about the current tracing
- session).
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
-See man:lttng-rotate(1) for more information about the concepts of a
-tracing session _rotation_ and a _trace chunk_.
+See man:lttng-concepts(7) to learn more about the tracing session
+rotation and trace chunk concepts.
With the option:--timer='PERIODUS' option, the `enable-rotation` command
sets a rotation schedule so that LTTng performs an automatic rotation at
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 man:lttng-enable-channel(1)). This means that:
+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
You may combine the option:--timer and option:--size options.
-The naming convention of a trace chunk archive which an automatic
-rotation operation creates is the same as with the immediate rotation
-command, man:lttng-rotate(1).
+See the man:lttng-concepts(7) to learn how LTTng names a trace chunk
+archive directory.
Unset a tracing session rotation schedule with the
man:lttng-disable-rotation(1) command.
[IMPORTANT]
====
-The `enable-rotation` command only works when:
+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)).
* No channel was created with a configured trace file count or size
limit (see the nloption:--tracefile-size and
- nloption:--tracefile-count options of man:lttng-enable-channel(1)).
+ nloption:--tracefile-count options of the man:lttng-enable-channel(1)
+ command).
For a given tracing session, LTTng only performs an automatic rotation
-when no other rotation is currently happening.
+when it's not currently performing a rotation.
====
supported.
option:--timer='PERIODUS'::
- Set a rotation schedule so that LTTng performs an automatic rotation at
- least every 'PERIODUS' microseconds.
+ Set a rotation schedule so that LTTng performs an automatic rotation
+ approximately every 'PERIODUS' microseconds.
+
The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
and `h`{nbsp}(hours) suffixes are supported.
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-create(1),
man:lttng-disable-rotation(1),
man:lttng-rotate(1)
lttng-event-rule(7)
===================
-:revdate: 19 April 2021
+:revdate: 3 May 2021
NAME
events:
[verse]
-option:--domain=kernel option:--type=(tracepoint | syscall[:entry|:exit|:entry+exit])]
+option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])]
pass:[[]option:--name='NAME'] [option:--filter='EXPR']
Specify an event rule to match Linux kernel kprobe or user space
probe events:
[verse]
-option:--domain=kernel option:--type=(kprobe | uprobe) option:--location='LOC'
+option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC'
pass:[[]option:--event-name='EVENTNAME'] [option:--filter='EXPR']
Specify an event rule to match user space tracepoint events:
[verse]
-option:--domain=user [option:--type=tracepoint] [option:--name='NAME'] [option:--exclude-name='XNAME']...
+option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']...
pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
Specify an event rule to match Java/Python logging events:
[verse]
-option:--domain=(jul | log4j | python) [option:--type=logging] [option:--name='NAME']
+option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME']
pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
here only apply to the `event-rule-matches` trigger condition specifier
(see man:lttng-add-trigger(1)).
+See man:lttng-concepts(7) to learn more about instrumentation points,
+events, and event rules.
+
[NOTE]
====
This manual page only describes the common event rule options. The
====
-Core concepts
-~~~~~~~~~~~~~
-An _instrumentation point_ is a point, within a piece of software,
-which, when executed, creates an LTTng _event_.
-
-LTTng offers various types of instrumentation; see the
-<<inst-point-type-cond,Instrumentation point type condition>> section
-below to learn about them.
-
-An _event rule_ is a set of conditions to match a set of events.
-
-When LTTng creates an event{nbsp}__E__, a event rule{nbsp}__ER__ is said
-to __match__{nbsp}__E__ when{nbsp}__E__ satisfies *all* the conditions
-of{nbsp}__ER__. This concept is similar to a regular expression which
-matches a set of strings.
-
-When an event rule matches an event, LTTng _emits_ the event,
-therefore attempting to execute one or more actions.
-
-[NOTE]
-====
-The event creation and emission processes are documentation concepts to
-help understand the journey from an instrumentation point to the
-execution of actions.
-
-The actual creation of an event can be costly because LTTng needs to
-evalute the arguments of the instrumentation point.
-
-In practice, LTTng implements various optimizations for the Linux kernel
-and user space tracing domains (option:--domain=++kernel++ and
-option:--domain=++user++ options) to avoid actually creating an event
-when the tracer knows, thanks to properties which are independent from
-the event payload and current context, that it would never emit such an
-event. Those properties are:
-
-* The instrumentation point type (see the
- <<inst-point-type-cond,Instrumentation point type>> section below).
-* The instrumentation point name (or event name)
- (see the <<event-name-cond,Event name condition>> section below).
-* The instrumentation point log level (see the
- <<inst-point-log-level-cond,Instrumentation point log level condition>>
- section below).
-
-In other words: if, for a given instrumentation point{nbsp}__IP__, the
-LTTng tracer knows that it would never emit an event,
-executing{nbsp}__IP__ represents a simple boolean variable check.
-====
-
-
-Event rule overview
-~~~~~~~~~~~~~~~~~~~
+Overview of event rule condtions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
conditions of an event rule, that is:
event payload and current context fields, is _true_.
+include::common-footer.txt[]
+
+
SEE ALSO
--------
man:lttng(1),
-man:lttng-add-trigger(1)
+man:lttng-add-trigger(1),
+man:lttng-concepts(7),
+man:lttng-list(1)
The `help` command is equivalent to:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] ['COMMAND'] --help
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] ['COMMAND'] nloption:--help
The `help` command attempts to launch `/usr/bin/man` to view this the
manual page of the command. Override the manual pager path with the
lttng-list-triggers(1)
======================
-:revdate: 3 March 2021
+:revdate: 3 May 2021
NAME
DESCRIPTION
-----------
-The `lttng list-triggers` command lists the available LTTng triggers
-of your Unix user and their properties.
+The `lttng list-triggers` command lists the available LTTng triggers of
+your Unix user, or of all users if your Unix user is `root`, and their
+properties.
-See man:lttng-add-trigger(1) to learn more about triggers.
+See man:lttng-concepts(7) to learn more about triggers.
OPTIONS
SEE ALSO
--------
+man:lttng(1),
man:lttng-add-trigger(1),
-man:lttng-remove-trigger(1),
-man:lttng(1)
+man:lttng-concepts(7),
+man:lttng-remove-trigger(1)
lttng-list(1)
=============
-:revdate: 28 November 2016
+:revdate: 3 May 2021
NAME
----
-lttng-list - List LTTng tracing sessions, domains, channels, and events
+lttng-list - List LTTng tracing sessions and instrumentation points
SYNOPSIS
--------
-List existing tracing sessions:
+List the tracing sessions:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list*
-List available event sources:
+List the tracing domains with at least one channel of a tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--fields]
- [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION'
-List tracing session's domains:
+List the channels and recording event rules of a tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION'
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION'
+ [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--python]
-List tracing session's channels and recording event rules:
+List the available LTTng tracepoints, Linux system calls, and/or
+Java/Python loggers:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION'
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--fields]
+ [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python]
DESCRIPTION
-----------
-The `lttng list` command lists tracing sessions, tracing domains,
-channels, and events.
-
-Without arguments, `lttng list` lists the existing tracing sessions
-and shows if they are active or not.
-
-With one or more of the option:--kernel, option:--userspace,
-option:--jul, option:--log4j, and option:--python domain options, the
-command lists the available event sources of the selected domain on the
-system. The JUL, log4j, and Python domains list the names of their
-available _loggers_. The option:--syscall option can be used alongside
-the option:--kernel option to get a list of traceable Linux system
-calls. The option:--fields option can be used to show the fields of the
-listed event sources.
-
-Providing a tracing session name 'SESSION' targets a specific tracing
-session. If the option:--domain option is used, domains containing at
-least one channel in the selected tracing session are listed. Otherwise,
-all the domains, channels, and recording event rules of the selected
-tracing session are listed along with its details (trace path, for
-example), except when the option:--channel option is used to isolate a
-specific channel by name.
+The `lttng list` command lists:
+
+Without arguments::
+ The tracing 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
+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
+ 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'.
+
+ Without the option:--channel option::::
+ The channels of the tracing session named 'SESSION' and
+ their recording event rules.
++
+Use the dedicated tracing domain options (option:--kernel,
+option:--userspace, option:--jul, option:--log4j, and option:--python)
+to only show specific channels.
+
+Without the 'SESSION' argument and with at least one dedicated tracing domain option::
++
+--
+With the option:--kernel option::
+ Without the option:--syscall option:::
+ The available LTTng kernel tracepoints.
+ With the option:--syscall option:::
+ The available, instrumented Linux system calls.
+With the option:--userspace option::
+ The available LTTng user space tracepoints.
+With the option:--jul, option:--log4j, and/or option:--python options::
+ The available `java.util.logging`, Apache log4j, and/or Python
+ logger names.
+--
++
+Also list the available instrumentation point fields with the
+option:--fields option.
+
+See man:lttng-concept(7) to learn more about tracing sessions, tracing
+domains, channels, recording event rules, and instrumentation points.
+
+List the channels and recording event rules of the current tracing
+session (see man:lttng-concept(7) to learn more) with the
+man:lttng-status(1) command.
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
option:-j, option:--jul::
- List event sources in the `java.util.logging` (JUL) domain.
+ Without the 'SESSION' argument:::
+ List the `java.util.logging` logger names.
+ With the 'SESSION' argument:::
+ Only list the `java.util.logging` channels and their recording
+ event rules.
option:-k, option:--kernel::
- List event sources in the Linux kernel domain.
+ Without the 'SESSION' argument:::
+ List the LTTng kernel instrumentation points.
+ With the 'SESSION' argument:::
+ Only list the Linux kernel channels and their recording event
+ rules.
option:-l, option:--log4j::
- List event sources in the Apache log4j domain.
+ Without the 'SESSION' argument:::
+ List the Apache log4j logger names.
+ With the 'SESSION' argument:::
+ Only list the Apache log4j channels and their recording event
+ rules.
option:-p, option:--python::
- List event sources in the Python domain.
+ Without the 'SESSION' argument:::
+ List the Python logger names.
+ With the 'SESSION' argument:::
+ Only list the Python channels and their recording event rules.
option:-u, option:--userspace::
- List event sources in the user space domain.
+ Without the 'SESSION' argument:::
+ List the LTTng user space tracepoints.
+ With the 'SESSION' argument:::
+ Only list the user space channels and their recording event
+ rules.
-Target
-~~~~~~
+Filtering
+~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
- Only list the details of the channel named 'CHANNEL'.
-
+ Only list the properties and recording event rules of the channel
+ named 'CHANNEL'.
++
+Only available with the 'SESSION' argument.
-Listing
-~~~~~~~
option:-d, option:--domain::
- Show the domains of the target tracing session in which at least one
- channel exists.
+ Show the tracing domains with at least one channel of the tracing
+ session named 'SESSION'.
option:-f, option:--fields::
- When listing the event sources with one of the domain options,
- also show their fields.
+ When listing instrumentation points, also show their fields if
+ they're available.
option:--syscall::
- When listing the event sources of the Linux kernel domain, list
- the traceable system calls instead of the kernel tracepoints.
+ When listing LTTng kernel instrumentation points, only list Linux
+ system calls.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7)
lttng-load(1)
=============
-:revdate: 28 November 2016
+:revdate: 30 April 2021
NAME
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *load* [option:--force] [option:--input-path='PATH']
- [option:--override-url='URL'] ['SESSION' [option:--override-name='NAME']]
+ [option:--override-url='URL'] [option:--all | 'SESSION' [option:--override-name='NAME']]
DESCRIPTION
The `lttng load` command loads the configurations of one or more
tracing sessions from files.
-The `lttng load` command is used in conjunction with the
-man:lttng-save(1) command to save and restore the complete
-configurations of tracing sessions. This includes the enabled channels
-and recording event rules, the context added to channels, the tracing
+See man:lttng-concepts(7) to learn more about tracing 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
activity, and more.
-Once one or more tracing session configurations are loaded, they appear
+Once LTTng loads one or more tracing session configurations, they appear
exactly as they were saved from the user's point of view.
-The following directories are searched, non-recursively, in this order
-for configuration files:
+LTTng searches the following directories, non-recursively, in this order
+for tracing session configuration files:
. `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`)
. +{system_sessions_dir}+
-The input path can be overridden with the option:--input-path option.
-When this option is specified, the default directories are :not:
-searched for configuration files. When it's not specified, _both_
-default directories are searched for configuration files.
+Override the input path with the option:--input-path='PATH' option. With
+this option, LTTng does :not: search the default directories above.
+'PATH' can be the path of one of:
+
+A directory::
+ With the 'SESSION' argument:::
+ LTTng searches for the tracing session configuration named
+ 'SESSION' in all the files of the directory 'PATH' and loads it
+ if found.
-If the input path is a *directory*, then:
+ 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'.
-* If 'SESSION' is specified, the tracing session configuration named
- 'SESSION' is searched for in all the files of this directory and
- loaded if found.
-* If 'SESSION' is not specified, the option:--all option is implicit:
- all the tracing session configurations found in all the files in this
- directory are loaded.
+A file::
+ With the 'SESSION' argument:::
+ LTTng searches for the tracing session configuration named
+ 'SESSION' in the file 'PATH' and loads it if found.
-If the input path is a *file*, then:
+ Without the 'SESSION' argument:::
+ The option:--all option is implicit: LTTng loads all the tracing
+ session configurations found in the file 'PATH'.
-* If 'SESSION' is specified, the tracing session configuration named
- 'SESSION' is searched for in this file and loaded if found.
-* If 'SESSION' is not specified, the option:--all option is implicit:
- all the tracing session configurations found in this file are loaded.
+Override the output URL of the loaded tracing session configurations
+with the option:--override-url option.
-Aspects of the loaded configurations can be overridden at load time
-using the option:--override-url and option:--override-name options.
+With the 'SESSION' argument, override the name of the loaded tracing
+session configuration with the option:--override-name option.
-By default, existing tracing sessions are not overwritten when loading:
-the command fails. The option:--force option can be used to allow this.
+By default, the `load` command does :not: overwrite existing tracing
+sessions: the command fails. Allow the `load` command to overwrite
+existing tracing sessions with the option:--force option.
include::common-cmd-options-head.txt[]
option:-a, option:--all::
- Load all tracing session configurations (default).
+ Load all the tracing session configurations (default).
option:-f, option:--force::
Overwrite existing tracing sessions when loading.
option:--override-name='NAME'::
Override the name of the loaded tracing session configuration,
'SESSION', with 'NAME'.
-+
-You must specify a tracing session name to load ('SESSION') and :not:
-use the option:--all option when using this option.
option:--override-url='URL'::
- Override the URL of the loaded tracing session configurations
+ Override the output URL of the loaded tracing session configurations
with 'URL'.
+
This is the equivalent of the nloption:--set-url option of
SEE ALSO
--------
-man:lttng-save(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7),
+man:lttng-save(1)
lttng-metadata(1)
=================
-:revdate: 28 November 2016
+:revdate: 30 April 2021
NAME
----
-lttng-metadata - Manage an LTTng tracing session's metadata generation
+lttng-metadata - Manage the metadata generation of an LTTng tracing session
SYNOPSIS
--------
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *metadata regenerate* [option:--session='SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *metadata* *regenerate* [option:--session='SESSION']
DESCRIPTION
-----------
-WARNING: This command is **deprecated**; it has been replaced by
+WARNING: This command is **deprecated**; it's been replaced with
`lttng regenerate metadata` (see man:lttng-regenerate(1)).
option:-s 'SESSION', option:--session='SESSION'::
- Manage the metadata generation of the tracing session named 'SESSION'
- instead of the current tracing 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
+ session).
include::common-cmd-help-options.txt[]
-LIMITATIONS
------------
-The `lttng metadata regenerate` command can only be used on kernel and
-user space tracing sessions (using per-user buffering), in non-live
-mode.
-
-See man:lttng-enable-channel(1) for more information about
-buffering schemes and man:lttng-create(1) for more information
-about the different tracing session modes.
-
-
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7),
+man:lttng-regenerate(1)
lttng-regenerate(1)
===================
-:revdate: 18 January 2018
+:revdate: 30 April 2021
NAME
----
-lttng-regenerate - Manage an LTTng tracing session's data regeneration
+lttng-regenerate - Regenerate specific data of an LTTng tracing session
SYNOPSIS
--------
-Regenerate the metadata of a session:
+Regenerate the metadata of a tracing session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate metadata* [option:--session='SESSION']
-Regenerate the state dump of a session:
+Regenerate the state dump event records of a tracing session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate statedump* [option:--session='SESSION']
+
DESCRIPTION
-----------
-The `lttng regenerate` command regenerates specific data of a tracing session.
-
-As of this version, the `metadata` and `statedump` actions are
-available.
+The `lttng regenerate` command regenerates specific data of:
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-Regenerating a tracing session's metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `lttng regenerate metadata` action can be used to resample the offset
-between the system's monotonic clock and the wall-clock time.
+Without the option:--session option::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
-This action is meant to be used to resample the wall-clock time following a
-major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] correction.
-As such, a system booting with an incorrect wall time can be traced before its
-wall time is NTP-corrected. Regenerating the tracing session's metadata ensures
-that trace viewers can accurately determine the events time relative to Unix
-Epoch.
+See man:lttng-concepts(7) to learn more about tracing sessions.
-If you use man:lttng-rotate(1) or man:lttng-enable-rotation(1) to make
-tracing session rotations, this action regenerates the current and
-next trace chunks's metadata files.
+As of this version, the `metadata` and `statedump` targets are
+available.
-Regenerating a tracing session's state dump
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `lttng regenerate statedump` action can be used to collect up-to-date state
-dump information during the tracing session. This is particularly useful in
-snapshot (see man:lttng-snapshot(1)) or trace file rotation (see
-man:lttng-enable-channel(1)) modes where the state dump information may be
+Regenerate the metadata of a tracing 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]
+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
+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
+metadata stream files of the current and next trace chunks.
+
+[IMPORTANT]
+====
+You can only use the `metadata` target when the selected
+tracing session:
+
+* Is not in live mode (nloption:--live option of
+ man:lttng-create(1)).
+
+* If it has user space channels, they're configured to use a
+ per-user buffering scheme (nloption:--buffers-uid option of
+ man:lttng-enable-channel(1)).
++
+See man:lttng-concepts(7) to learn more about channels.
+====
+
+
+Regenerate the state dump event records of a tracing 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
+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
lost.
option:-s 'SESSION', option:--session='SESSION'::
- Regenerate the data of the tracing session named 'SESSION'
+ Regenerate specific data of the tracing session named 'SESSION'
instead of the current tracing session.
include::common-cmd-help-options.txt[]
-LIMITATIONS
------------
-The `lttng regenerate metadata` command can only be used on kernel and
-user space tracing sessions (using per-user buffering), in non-live
-mode.
-
-See man:lttng-enable-channel(1) for more information about
-buffering schemes and man:lttng-create(1) for more information
-about the different tracing session modes.
-
-
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7)
lttng-relayd(8)
===============
-:revdate: 2 April 2020
+:revdate: 30 April 2021
+:daemon-bin-name: lttng-relayd
+:daemon-ini-section: relayd
NAME
----
-lttng-relayd - LTTng 2 relay daemon
+lttng-relayd - LTTng relay daemon
SYNOPSIS
[verse]
*lttng-relayd* [option:--background | option:--daemonize] [option:--config='PATH']
[option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT']
- [option:--live-port='URL'] [option:--output='PATH']
- [option:-v | option:-vv | option:-vvv] [option:--working-directory='PATH']
- [option:--group-output-by-session] [option:--disallow-clear]
+ [option:--live-port='URL'] [option:--output='DIR'] [option:--group='GROUP']
+ [option:--verbose]... [option:--working-directory='DIR']
+ [option:--group-output-by-host | option:--group-output-by-session] [option:--disallow-clear]
DESCRIPTION
-----------
-The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
-source software package used for correlated tracing of the Linux kernel,
-user applications, and user libraries.
+include::common-intro.txt[]
-LTTng consists of Linux kernel modules (for Linux kernel tracing) and
-dynamically loaded libraries (for user application and library tracing).
+An LTTng relay daemon, `lttng-relayd`, is a program which receives trace
+data from (possibly remote) LTTng session/consumer daemons and which
+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.
-The _LTTng relay daemon_ is responsible for receiving trace data from
-possibly remote LTTng session/consumer daemons and for writing it to
-the local file system. The relay daemon also accepts _LTTng live_
-connections from compatible viewers; this is the official approach to
-viewing LTTng events as they are emitted.
+By default, a relay daemon listens on all network interfaces to receive
+trace data, but only on `localhost` for LTTng live connections. Override
+the listening URLs with the option:--control-port, option:--data-port,
+and option:--live-port options (see the <<url-format,URL format>>
+section below). For example, use the
+option:--live-port=+tcp://0.0.0.0:{default_network_viewer_port}+ option
+to make a relay daemon listen to LTTng live connections on all network
+interfaces.
-The relay daemon listens by default on all network interfaces to gather
-trace data, but only on localhost for LTTng live connections.
+Once LTTng has completely sent a trace to a relay daemon{nbsp}__RD__,
+any LTTng trace reader can read the trace located on the local file
+system of{nbsp}__RD__.
-The relay daemon does not require any particular permissions, as long as
-it can write to the output directory and listen on the configured ports.
-If a user is within a secured network and/or has proper firewall
-settings, `lttng-relayd` can listen to LTTng live connections from _all_
-network interfaces by specifying
-+--live-port=tcp://0.0.0.0:{default_network_viewer_port}+.
+By default, `lttng-relayd` doesn't start as a daemon. Make it a daemon
+with the option:--daemonize or option:--background option. With those
+options, `lttng-relayd` ensures the daemon is listening to incoming
+connections before it exits.
-Once a trace has been streamed completely, the trace can be processed by
-any tool that can process an LTTng trace located on the local
-file system.
+
+include::common-daemon-cfg.txt[]
+
+INI configuration file example:
+
+[source,ini]
+----
+[relayd]
+daemonize=yes
+live-port=tcp://0.0.0.0:4567
+disallow-clear=yes
+----
[[output-directory]]
The relay daemon uses different output path patterns depending on:
* Its configuration.
-* The connected peer's tracing session configuration.
-* The connected peer's LTTng session daemon (see man:lttng-sessiond(8))
- version.
++
+See the <<cfg,Daemon configuration>> section above.
+
+* The tracing session configuration of the connected peer.
+* The LTTng session daemon (see man:lttng-sessiond(8)) version
+ of the connected peer.
Consider the following variables:
'BASE'::
- Base output directory: `$LTTNG_HOME/lttng-traces` or the
- argument of the option:--output option.
-+
-NOTE: `$LTTNG_HOME` defaults to `$HOME`.
+ Base output directory: `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
+ defaults to `$HOME`) or the argument of the option:--output option.
'HOSTNAME'::
- Peer's hostname.
+ Hostname of the connected peer.
'SESSION'::
Tracing session name.
'DATETIME'::
Unique tracing session date/time.
-'TRACEPATH'::
- Custom trace path ('TRACEPATH' part of the man:lttng-create(1)
- command's nloption:--set-url option's argument, if any).
+'TRACEDIR'::
+ Custom trace directory path ('TRACEDIR' part of the argument of the
+ nloption:--set-url option of the man:lttng-create(1) command, if
+ any).
+
+'SESSIONDV'::
+ The version of the LTTng session daemon of the connected peer.
The relay daemon output path patterns are:
-Hostname grouping (without option:--group-output-by-session)::
- Without a custom trace path:::
+With the option:--group-output-by-host option (hostname grouping)::
+ Without a custom trace directory:::
+
---
[verse]
'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
---
-With a custom trace path:::
+With a custom trace directory:::
+
---
[verse]
-'BASE'/'HOSTNAME'/'TRACEPATH'
---
+'BASE'/'HOSTNAME'/'TRACEDIR'
-Tracing session grouping (with option:--group-output-by-session)::
- Without a custom trace path:::
- The peer's LTTng session daemon version is at least 2.4::::
+With the option:--group-output-by-session option (tracing session grouping)::
+ Without a custom trace directory:::
+ 'SESSIONDV' is at least{nbsp}2.4::::
+
---
[verse]
'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'
---
Otherwise::::
Defaults to the hostname grouping pattern:
+
---
[verse]
'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
---
-With a custom trace path:::
- The peer's LTTng session daemon version is at least 2.4::::
+With a custom trace directory:::
+ 'SESSIONDV' is at least 2.4::::
+
---
[verse]
-'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEPATH'
---
+'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEDIR'
Otherwise::::
Defaults to the hostname grouping pattern:
+
---
[verse]
-'BASE'/'HOSTNAME'/'TRACEPATH'
---
+'BASE'/'HOSTNAME'/'TRACEDIR'
[[url-format]]
URL format
~~~~~~~~~~
-The option:--control-port, option:--data-port, and option:--live-port
-options specify URLs.
+The argument of the option:--control-port='URL',
+option:--data-port='URL', and option:--live-port='URL' options is an
+URL.
-The format of those URLs is:
+The format of 'URL' is:
[verse]
tcp://('HOST' | 'IPADDR'):__PORT__
with:
('HOST' | 'IPADDR')::
- Binding hostname or IP address (IPv6 address *must* be enclosed in
- brackets (`[` and `]`); see
- https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
+ Binding hostname or IP address.
++
+IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
+see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
'PORT'::
TCP port.
+[[options]]
OPTIONS
-------
-Daemon
-~~~~~~
+General daemon configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:-b, option:--background::
- Start as Unix daemon, but keep file descriptors (console) open.
- Use the option:--daemonize option instead to close the file
- descriptors.
+ Start as a Unix daemon, but keep file descriptors (console) open.
++
+With this option, `lttng-relayd` ensures the daemon is listening
+to incoming connections before it exits.
++
+Use the option:--daemonize option instead to close the file descriptors.
option:-f 'PATH', option:--config='PATH'::
- Load relay daemon configuration from path 'PATH'.
+ Configure the daemon using the INI configuration file 'PATH' in
+ addition to the default configuration files and the command-line
+ options.
++
+See the <<cfg,Daemon configuration>> section above.
option:-d, option:--daemonize::
- Start as Unix daemon, and close file descriptors (console). Use the
- option:--background option instead to keep the file descriptors
- open.
+ Start as a Unix daemon and close file descriptors (console).
++
+With this option, `lttng-relayd` ensures the daemon is listening
+to incoming connections before it exits.
++
+Use the option:--background option instead to keep the file descriptors
+open.
option:-x, option:--disallow-clear::
Disallow clearing operations (see man:lttng-clear(1)).
See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable.
option:--fd-pool-size='SIZE'::
- Set the size of the file descriptor pool to 'SIZE'.
+ Set the size of the file descriptor pool to 'SIZE' file descriptors.
+
-'SIZE' is the maximum number of file descriptors that may be kept opened
-simultaneously by the relay daemon.
+'SIZE' is the maximum number of file descriptors that the relay daemon
+may keep open simultaneously.
+
Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
man:getrlimit(2)).
option:-g 'GROUP', option:--group='GROUP'::
- Use 'GROUP' as Unix tracing group (default: `tracing`).
+ Set the Unix tracing group to 'GROUP' instead of `tracing`.
++
+This option is only meaningful when the `root` Unix user starts
+`lttng-relayd`.
++
+Members of the Unix tracing group may connect to the health check socket
+of the relay daemon.
++
+See also the `LTTNG_RELAYD_HEALTH` environment variable.
-option:-w 'PATH', option:--working-directory='PATH'::
+option:-w 'DIR', option:--working-directory='DIR'::
Set the working directory of the processes the relay daemon creates
- to 'PATH'.
+ to 'DIR'.
+
See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.
option:-v, option:--verbose::
Increase verbosity.
+
-Three levels of verbosity are available, which are triggered by
-appending additional `v` letters to the option
-(that is, `-vv` and `-vvv`).
+Specify this option up to three times to get more levels of verbosity.
Output
~~~~~~
-See the <<output-directory,Output directory>> section above for more
-information.
+See the <<output-directory,Output directory>> section above to learn
+more.
option:-p, option:--group-output-by-host::
- Group the written trace directories by hostname (default).
+ Group the written trace directories by hostname.
++
+As of LTTng{nbsp}{lttng_version}, this is the default output grouping
+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.
-option:-o 'PATH', option:--output='PATH'::
+option:-o 'DIR', option:--output='DIR'::
Set the base output directory of the written trace directories to
- 'PATH'.
+ 'DIR'.
Ports
~~~~~
-See the <<url-format,URL format>> section above for more information
-about the syntax of the following 'URL' argument.
+See the <<url-format,URL format>> section above to learn more about the
+syntax of the 'URL' argument of the following options.
option:-C 'URL', option:--control-port='URL'::
- Listen to control data on URL 'URL' (default:
- +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
+ Listen to control data on URL 'URL'.
++
+Default:
++tcp://{default_network_control_bind_address}:{default_network_control_port}+.
option:-D 'URL', option:--data-port='URL'::
- Listen to trace data on URL 'URL' (default:
- +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
+ Listen to trace data on URL 'URL'.
++
+Default:
++tcp://{default_network_data_bind_address}:{default_network_data_port}+.
option:-L 'URL', option:--live-port='URL'::
- Listen to LTTng live connections on URL 'URL'
- (default:
- +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
+ Listen to LTTng live connections on URL 'URL'.
++
+Default:
++tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
Program information
~~~~~~~~~~~~~~~~~~~
-option:-h, option:--help::
- Show help.
+include::common-help-option.txt[]
option:-V, option:--version::
- Show version.
+ Show version and quit.
ENVIRONMENT VARIABLES
---------------------
`LTTNG_ABORT_ON_ERROR`::
- Set to 1 to abort the process after the first error is encountered.
+ Set to `1` to abort the process after the first error is
+ encountered.
`LTTNG_NETWORK_SOCKET_TIMEOUT`::
- Socket connection, receive and send timeout (milliseconds). A value
- of 0 or -1 uses the timeout of the operating system (default).
+ Socket connection, receive, and send timeout (milliseconds).
++
+Set to `0` or `-1` to set an infinite timeout (default).
`LTTNG_RELAYD_DISALLOW_CLEAR`::
- Set to 1 to disallow clearing operations (see man:lttng-clear(1)).
+ Set to `1` to disallow clearing operations (see man:lttng-clear(1)).
+
-The option:--disallow-clear option overrides this variable.
+The option:--disallow-clear option overrides this environment variable.
`LTTNG_RELAYD_HEALTH`::
- Path to relay daemon health's socket.
+ Path to the health check socket of the relay daemon.
`LTTNG_RELAYD_TCP_KEEP_ALIVE`::
- Set to 1 to enable TCP keep-alive.
+ Set to `1` to enable TCP keep-alive.
+
The TCP keep-alive mechanism allows the detection of dead peers
-(man:lttng-sessiond(8)) in cases of unclean termination
-(for example, a hard reset) of a peer.
+(man:lttng-sessiond(8)) in cases of unclean termination (for example, a
+hard reset) of a peer.
+
Supported on Linux and Solaris only. The default behaviour of the TCP
keep-alive mechanism is OS-specific.
+
-Search for `tcp_keepalive` in man:tcp(7) for more information.
+Search for `tcp_keepalive` in man:tcp(7) to learn more.
`LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
- The time threshold in seconds to abort a TCP connection after the keep-alive
- probing mechanism has failed.
+ The time threshold (seconds) to abort a TCP connection after the
+ keep-alive probing mechanism has failed.
+
-Set to 0 or -1 to use the value chosen by the operating system (default).
+Set to `0` or `-1` to use the value chosen by the operating system
+(default).
+
Supported on Solaris 11 only.
+
-Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information.
+Search for `tcp_keepalive_abort_threshold` in man:tcp(7) to learn more.
`LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
Number of seconds a connection needs to be idle before TCP begins
sending out keep-alive probes.
+
-Set to 0 or -1 to use the value chosen by the operating system (default).
+Set to `0` or `-1` to use the value chosen by the operating system
+(default).
+
Supported on Linux and Solaris 11 only.
+
-On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000.
+On Solaris{nbsp}11, the accepted values are `-1`, `0`, and `10` to
+`864000`.
+
Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
-in man:tcp(7) on Solaris 11 for more information.
+in man:tcp(7) on Solaris{nbsp}11 to learn more.
`LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
Maximum number of TCP keep-alive probes to send before giving up and
killing the connection if no response is obtained from the other end.
+
-Set to 0 or -1 to use the value chosen by the operating system (default).
+Set to `0` or `-1` to use the value chosen by the operating system
+(default).
+
Supported on Linux only.
+
-Search for `tcp_keepalive_probes` in man:tcp(7) for more information.
+Search for `tcp_keepalive_probes` in man:tcp(7) to learn more.
`LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
Number of seconds between TCP keep-alive probes.
+
-Set to 0 or -1 to use the value chosen by the operating system (default).
+Set to `0` or `-1` to use the value chosen by the operating system
+(default).
+
Supported on Linux only.
+
-Search for `tcp_keepalive_intvl` in man:tcp(7) for more information.
+Search for `tcp_keepalive_intvl` in man:tcp(7) to learn more.
`LTTNG_RELAYD_WORKING_DIRECTORY`::
Working directory of the processes the relay daemon creates.
+
-The option:--working-directory option overrides this variable.
+The option:--working-directory option overrides this environment
+variable.
FILES
-----
`$LTTNG_HOME/.lttng`::
- User LTTng runtime and configuration directory.
+ Unix user's LTTng runtime and configuration directory.
`$LTTNG_HOME/lttng-traces`::
- Default base output directory of LTTng traces. This can be
- overridden with the option:--output option.
+ Default base output directory of LTTng traces.
++
+Override this path with the option:--output option.
NOTE: `$LTTNG_HOME` defaults to `$HOME`.
Fatal error
-LIMITATIONS
------------
-As of this version, only the TCP protocol is supported for both control
-and data ports. In future versions, TCP will remain the sole available
-protocol for control data since those communications are low-volume and
-need absolute reliability; trace data could be carried over UDP.
-
-For an unprivileged user running `lttng-relayd`, the maximum number of
-file descriptors per process is usually 1024. This limits the number of
-connections and opened trace files. This limit can be configured with
-*ulimit*(3).
-
-
include::common-footer.txt[]
--------
man:lttng(1),
man:lttng-sessiond(8),
-man:lttng-crash(1),
-man:lttng-ust(3),
man:babeltrace2(1)
lttng-remove-trigger(1)
=======================
-:revdate: 5 March 2021
+:revdate: 29 April 2021
NAME
-----------
The `lttng remove-trigger` command removes the trigger named 'NAME'.
-See man:lttng-add-trigger(1) to learn more about LTTng triggers.
+See man:lttng-concepts(7) to learn more about LTTng triggers.
-List the available triggers and their name with the
-man:lttng-list-triggers(1) command.
+List the triggers of your Unix user, or of all users if your
+Unix user is `root`, with the man:lttng-list-triggers(1) command.
The `remove-trigger` command removes a trigger which belong to your Unix
user. If your Unix user is `root`, you can remove the trigger of another
SEE ALSO
--------
+man:lttng(1),
man:lttng-add-trigger(1),
-man:lttng-list-triggers(1),
-man:lttng(1)
+man:lttng-concepts(7),
+man:lttng-list-triggers(1)
lttng-rotate(1)
===============
-:revdate: 18 October 2019
+:revdate: 30 April 2021
NAME
----
-lttng-rotate - Archive a tracing session's current trace chunk
+lttng-rotate - Archive the current trace chunk of an LTTng tracing session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng rotate` command archives the current trace chunk of the
-current tracing session, or of the tracing session named 'SESSION' if
-provided, to the file system. This action is called a tracing session
-_rotation_.
-
-Once LTTng archives a trace chunk, it does not manage it anymore: you
-can read it, modify it, move it, or remove it.
-
-An _archived trace chunk_ is a collection of metadata and data stream
-files which form a self-contained LTTng trace.
-
-The _current trace chunk_ of a given tracing session includes:
-
-* The stream files already written 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 with
- man:lttng-start(1).
-** The last rotation, either an immediate one with `lttng rotate`, or an
- automatic one from a rotation schedule previously set with
- man:lttng-enable-rotation(1).
-* The content of all the non-flushed sub-buffers of the tracing
- session's channels.
-
-You can use `lttng rotate`:
-
-* At any time when the tracing session is active (see
- man:lttng-start(1)).
-* A single time once the tracing session becomes inactive
- (see man:lttng-stop(1)).
-
-By default, the `lttng rotate` command ensures that LTTng finished
-performing the tracing session rotation before it prints the archived
-trace chunk's path and exits. The printed path is absolute when the
-tracing session was created in normal mode and relative to the relay
-daemon's output directory (see the nloption:--output option in
-man:lttng-relayd(8)) when it was created in network streaming mode (see
-man:lttng-create(1)).
-
-With the option:--no-wait option, the command finishes immediately, so
-that LTTng might not have completed the rotation when the command exits.
-In this case, there is no easy way to know when the current trace chunk
-becomes archived, and the command does not print the archived trace
-chunk's path.
+The `lttng rotate` command archives to the file system
+the current trace chunk of:
-Because when LTTng performs a tracing session rotation, it flushes the
-tracing session's current sub-buffers, 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.
+With the 'SESSION' argument::
+ The tracing session named 'SESSION'.
-See <<limitations,LIMITATIONS>> for important limitations regarding
-this command.
+Without the 'SESSION' argument::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+This action is called a _tracing session rotation_.
-Trace chunk archive naming
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-A trace chunk archive is a subdirectory of the `archives` subdirectory
-within a tracing session's output directory (see the nloption:--output
-option in man:lttng-create(1) and man:lttng-relayd(8)).
+See man:lttng-concepts(7) to learn more about the tracing session
+rotation and trace chunk concepts.
-A trace chunk archive contains, through tracing domain and possibly
-UID/PID subdirectories, metadata and data stream files.
+You can use the `rotate` command:
-A trace chunk archive is, at the same time:
+* Any time the tracing session is active.
-* A self-contained LTTng trace.
-* A member of a set of trace chunk archives which form the complete
- trace of a tracing session.
+* A single time once the tracing session becomes inactive.
-In other words, an LTTng trace reader can read both the tracing
-session output directory (all the trace chunk archives), or a
-single trace chunk archive.
+See man:lttng-concepts(7) to learn more about the activity of a
+tracing session.
-When LTTng performs a tracing session rotation, it names the resulting
-trace chunk archive as such, relative to the tracing session's output
-directory:
+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
+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
+man:lttng-create(1)).
-[verse]
-archives/__BEGIN__-__END__-__ID__
-
-__BEGIN__::
- Date and time of the beginning of the trace chunk archive with
- the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
- `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
- time zone offset from UTC.
-+
-Example: `20171119T152407-0500`
-
-__END__::
- Date and time of the end of the trace chunk archive with
- the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
- `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
- time zone offset from UTC.
-+
-Example: `20180118T152407+0930`
-
-__ID__::
- Unique numeric identifier of the trace chunk within its tracing
- session.
-
-Trace chunk archive name example:
+Make the command exit immediately with the option:--no-wait option. In
+this case, there's no easy way to know when the current trace chunk
+becomes archived, and the command does :not: print the path of the
+archived trace chunk.
-----
-archives/20171119T152407-0500-20171119T151422-0500-3
-----
+Because LTTng flushes the current sub-buffers of the selected tracing
+session when it performs a tracing 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)).
-include::common-cmd-options-head.txt[]
+[IMPORTANT]
+====
+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)).
-option:-n, option:--no-wait::
- Do not ensure that the rotation is done before returning to
- the prompt.
+* 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).
+* LTTng is not currently performing an immediate rotation (this
+ command).
+====
-include::common-cmd-help-options.txt[]
+include::common-cmd-options-head.txt[]
-[[limitations]]
-LIMITATIONS
------------
-The `lttng rotate` command only works when:
-* The tracing session is created in normal mode or in network streaming
- mode (see man:lttng-create(1)).
+option:-n, option:--no-wait::
+ Do not ensure that the tracing session rotation operation is
+ completed before exiting.
-* No channel was created with a configured trace file count or size
- limit (see the nloption:--tracefile-size and
- nloption:--tracefile-count options in man:lttng-enable-channel(1)).
-* No immediate rotation (`lttng rotate`) is currently happening.
+include::common-cmd-help-options.txt[]
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng-enable-rotation(1),
+man:lttng(1),
+man:lttng-concepts(7),
man:lttng-disable-rotation(1),
-man:lttng(1)
+man:lttng-enable-rotation(1)
lttng-save(1)
=============
-:revdate: 28 November 2016
+:revdate: 3 May 2021
NAME
SYNOPSIS
--------
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *save* [option:--force] [option:--output-path='PATH'] ['SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *save* [option:--force] [option:--output-path='DIR'] ['SESSION']
DESCRIPTION
-----------
-The `lttng save` command saves the configurations of one or more
-tracing sessions to files.
+The `lttng save` command saves to files the configurations of:
-The `lttng save` command is used in conjunction with the
-man:lttng-load(1) command to save and restore the complete
-configurations of tracing sessions. This includes the enabled channels
-and recording event rules, the context added to channels, the tracing
-activity, and more. `lttng save` does not save tracing data, only the
-tracing session parameters.
+With the 'SESSION' argument::
+ The tracing session named 'SESSION'.
-If 'SESSION' is omitted, all the existing tracing session configurations
-are saved (equivalent to using the option:--all option). Otherwise,
-'SESSION' is the name of an existing tracing session. `lttng list`
-outputs all the existing tracing sessions (see man:lttng-list(1)).
+Without the 'SESSION' argument::
+ *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)).
++
+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.
+
+Use the `save` command in conjunction with the man:lttng-load(1) command
+to save and restore the complete configurations of tracing sessions.
+
+The `save` command does :not: save tracing data, only the tracing
+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`). Each tracing session configuration
-file is named `SESSION.lttng`, where `SESSION` is the original tracing
-session name. The default output directory path can be overridden with
-the option:--output-path option.
+(`$LTTNG_HOME` defaults to `$HOME`). Override the default output
+directory path with the option:--output-path option. Each tracing
+session configuration file is named __SNAME__++.lttng++,
+where{nbsp}__SNAME__ is the original tracing session name.
-By default, existing tracing session configuration files are not
-overwritten when saving; the command fails. The option:--force option
-can be used to allow this.
+By default, the `save` command does :not: overwrite existing tracing
+session configuration files: the command fails. Allow the `save` command
+to overwrite existing tracing session configuration files with the
+option:--force option.
include::common-cmd-options-head.txt[]
option:-a, option:--all::
- Save all tracing session configurations (default).
+ 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'.
option:-f, option:--force::
Overwrite existing tracing session configuration files when
saving.
-option:-o 'PATH', option:--output-path='PATH'::
- Set output directory path to 'PATH'.
+option:-o 'DIR', option:--output-path='DIR'::
+ Save tracing session configuration files to the directory 'DIR'
+ instead of `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to
+ `$HOME`).
include::common-cmd-help-options.txt[]
SEE ALSO
--------
-man:lttng-load(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7),
+man:lttng-load(1)
lttng-sessiond(8)
=================
:revdate: 21 April 2021
+:daemon-bin-name: lttng-sessiond
+:daemon-ini-section: sessiond
NAME
An LTTng session daemon, `lttng-sessiond`, is a program which:
-* Manages tracing sessions (see man:lttng-create(1) to learn more about
- tracing sessions).
+* Manages tracing sessions (see man:lttng-concepts(7) to learn more
+ about tracing sessions).
* Controls the various components (like tracers and consumer daemons) of
LTTng.
NOTE: The LTTng project recommends that you start the session daemon at
boot time for stable and long-term tracing.
+[NOTE]
+====
+For an unprivileged Unix user running `lttng-sessiond`, the maximum
+number of file descriptors per process is usually 1024. This limits the
+number of traceable applications, since, for each instrumented
+application, there are two file descriptors per CPU as well as one
+socket for bidirectional communication.
-[[cfg]]
-Daemon configuration
-~~~~~~~~~~~~~~~~~~~~
-When you run `lttng-sessiond`, it configures itself from, in this order:
-
-. The INI configuration file +{system_lttng_conf}+, if any.
-
-. The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any.
-+
-`$LTTNG_HOME` defaults to `$HOME`.
-
-. With the option:--config='PATH' option: the INI configuration file
- 'PATH'.
-
-. The command-line options.
-
-Each step can override a previous configuration property.
-
-In INI configuration files, the session daemon only reads the properties
-under the `sessiond` INI section. Each INI property is:
-
-Key::
- The long name of a command-line option to set (see the
- <<options,OPTIONS>> section below).
-
-Value::
- The selected command-line option accepts an argument:::
- Option argument (string).
+For the `root` user, the limit is usually 65,535.
+====
- The selected command-line option is a switch:::
- `true`::::
- `yes`::::
- `on`::::
- Enable the option.
- `false`::::
- `no`::::
- `off`::::
- Disable the option.
+include::common-daemon-cfg.txt[]
INI configuration file example:
[[options]]
OPTIONS
-------
-Daemon configuration
-~~~~~~~~~~~~~~~~~~~~
+General daemon configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:-b, option:--background::
Start as a Unix daemon, but keep file descriptors (console) open.
+
For each 'PROBE' argument, load the LTTng kernel probe module
named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the
default LTTng kernel probe modules.
++
+See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable.
option:--kmod-probes='PROBE'[,'PROBE']...::
Only load, for each 'PROBE' argument, the LTTng kernel probe
module named ++lttng-probe-++__PROBE__++.ko++, instead of loading
the default LTTng kernel probe modules.
++
+See also the `LTTNG_KMOD_PROBES` environment variable.
option:--no-kernel::
Disable Linux kernel tracing.
option:--consumerd32-libdir='PATH'::
Set the 32-bit consumer daemon library directory to 'PATH'.
++
+See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable.
option:--consumerd32-path='PATH'::
Set the 32-bit consumer daemon binary path to 'PATH'.
++
+See also the `LTTNG_CONSUMERD32_BIN` environment variable.
option:--consumerd64-libdir='PATH'::
Set the 64-bit consumer daemon library directory to 'PATH'.
++
+See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable.
option:--consumerd64-path='PATH'::
Set the 64-bit consumer daemon binary path to 'PATH'.
++
+See also the `LTTNG_CONSUMERD32_BIN` environment variable.
option:--kconsumerd-cmd-sock='PATH'::
Set the command Unix socket path of the Linux kernel consumer daemon
`LTTNG_CONSUMERD32_BIN`::
32-bit consumer daemon binary path.
+
-The option:--consumerd32-path option overrides this variable.
+The option:--consumerd32-path option overrides this environment
+variable.
`LTTNG_CONSUMERD32_LIBDIR`::
32-bit consumer daemon library directory path.
+
-The option:--consumerd32-libdir option overrides this variable.
+The option:--consumerd32-libdir option overrides this environment
+variable.
`LTTNG_CONSUMERD64_BIN`::
64-bit consumer daemon binary path.
+
-The option:--consumerd64-path option overrides this variable.
+The option:--consumerd64-path option overrides this environment
+variable.
`LTTNG_CONSUMERD64_LIBDIR`::
64-bit consumer daemon library directory path.
+
-The option:--consumerd64-libdir option overrides this variable.
+The option:--consumerd64-libdir option overrides this environment
+variable.
`LTTNG_DEBUG_NOCLONE`::
Set to `1` to disable the use of man:clone(2)/man:fork(2).
+
-Setting this variable is considered insecure, but it's required to allow
-debuggers to work with `lttng-sessiond` on some operating systems.
+Setting this environment variable is considered insecure, but it's
+required to allow debuggers to work with `lttng-sessiond` on some
+operating systems.
`LTTNG_EXTRA_KMOD_PROBES`::
Extra LTTng kernel probe modules to load.
Fatal error
-LIMITATIONS
------------
-For an unprivileged Unix user running `lttng-sessiond`, the maximum
-number of file descriptors per process is usually 1024. This limits the
-number of traceable applications, since, for each instrumented
-application, there are two file descriptors per CPU as well as one
-socket for bidirectional communication.
-
-For the `root` user, the limit is usually 65,535.
-
-
include::common-footer.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7)
lttng-set-session(1)
====================
-:revdate: 21 April 2021
+:revdate: 29 April 2021
NAME
The `lttng set-session` command sets the current tracing session of your
Unix user to the tracing session named 'SESSION'.
-See man:lttng-create(1) to learn more about the current tracing session.
-
-The following man:lttng(1) commands select the current tracing session
-if you don't specify one:
-
-* man:lttng-add-context(1)
-* man:lttng-clear(1)
-* man:lttng-destroy(1)
-* man:lttng-disable-channel(1)
-* man:lttng-disable-event(1)
-* man:lttng-disable-rotation(1)
-* man:lttng-enable-channel(1)
-* man:lttng-enable-event(1)
-* man:lttng-enable-rotation(1)
-* man:lttng-regenerate(1)
-* man:lttng-rotate(1)
-* man:lttng-save(1)
-* man:lttng-snapshot(1)
-* man:lttng-start(1)
-* man:lttng-status(1)
-* man:lttng-stop(1)
-* man:lttng-track(1)
-* man:lttng-untrack(1)
-* man:lttng-view(1)
+See man:lttng-concepts(7) to learn more about the current tracing session.
The `set-session` command effectively updates the `$LTTNG_HOME/.lttngrc`
file.
-List the tracing sessions of your Unix user with the man:lttng-list(1)
-command.
+List the tracing 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.
include::common-cmd-options-head.txt[]
SEE ALSO
--------
+man:lttng(1),
+man:lttng-concepts(7),
man:lttng-create(1),
-man:lttng-destroy(1),
-man:lttng(1)
+man:lttng-destroy(1)
lttng-snapshot(1)
=================
-:revdate: 9 November 2018
+:revdate: 3 May 2021
NAME
----
-lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
+lttng-snapshot - Take a snapshot of an LTTng tracing session
SYNOPSIS
--------
-Add a snapshot output:
+Take a tracing session snapshot:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE']
+*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')
+ [option:--ctrl-url='URL' option:--data-url='URL' | 'URL']
-Remove a snapshot output:
+Add a snapshot output to a tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION']
- ('ID' | 'NAME')
+*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')
-List current snapshot outputs:
+Show the snapshot output of a tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION']
-Take a snapshot:
+Remove the snapshot output from a tracing session:
[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')
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1*
DESCRIPTION
-----------
-The `lttng snapshot` command manages the snapshot outputs and takes
-snapshots.
-
-A _snapshot_ is a dump of the current sub-buffers of all the channels
-of a given tracing session. When a snapshot is taken, the memory dump
-is sent to the registered snapshot outputs.
+The `lttng snapshot` command can take a snapshot of, add or remove a
+snapshot output, and show the snapshot output of:
-The tracing session should be created in _snapshot mode_ to make sure
-that taking snapshots is allowed. This is done at tracing session
-creation time using the man:lttng-create(1) command's
-nloption:--snapshot option.
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-Note that, when a snapshot is taken, the sub-buffers are not cleared.
-This means that different recorded snapshots may contain the same
-events.
-
-If you want, instead, to keep all the trace data, but divide it into
-archived chunks which are then free to process (just like snapshots),
-see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace
-chunk archives do not overlap like snapshots can.
-
-
-Snapshot outputs
-~~~~~~~~~~~~~~~~
-Snapshot outputs are the destinations of snapshot files when a
-snapshot is taken using the `record` action.
+Without the option:--session option::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
-As of this version, only one snapshot output is allowed.
+See man:lttng-concepts(7) to learn more about tracing sessions.
-A snapshot output can be added using the `add-output` action. The
-output destination URL is set using either the 'URL' positional
-argument, or both the option:--ctrl-url and option:--data-url options.
-See man:lttng-create(1) to learn more about the URL format.
+A _snapshot_ is a dump of the current sub-buffers of all the channels of
+the selected tracing session.
-A name can be assigned to an output when adding it using the
-option:--name option. This name is part of the names of the
-snapshot files written to this output.
+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
+<<output,Snapshot output>> section below to learn more.
-By default, the snapshot files can be as big as the sum of the
-sizes of all the sub-buffers or all the channels of the selected
-tracing session. The maximum total size of all the snapshot files can
-be configured using the option:--max-size option.
+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.
-Snapshot outputs can be listed using the `list-output` action.
+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.
-Snapshot outputs can be removed using the `del-output` action. The
-configured name can be used when removing an output, or an ID as
-listed by the `list-output` action.
+A `snapshot-session` trigger action can also take a tracing session
+snapshot (see man:lttng-add-trigger(1)).
+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.
-Taking a snapshot
-~~~~~~~~~~~~~~~~~
-Taking a snapshot of the current tracing session is as easy as:
+[NOTE]
+====
+Before you take a snapshot on a system with a high event throughput, the
+LTTng project recommends that you first run the man:lttng-stop(1)
+command. Otherwise, the snapshot could contain ``holes'', the result of
+the tracers overwriting unconsumed trace packets during the snapshot
+operation.
-[role="term"]
-----
-$ lttng snapshot record
-----
+After LTTng writes the snapshot trace data, you can restart the tracing
+session with the man:lttng-start(1) command.
+====
-This writes the snapshot files to the configured output. It is possible
-to use a custom, unregistered output at record time using the same
-options supported by the `add-output` action.
-NOTE: Before taking a snapshot on a system with a high event throughput,
-it is recommended to first run `lttng stop` (see
-man:lttng-stop(1)). Otherwise, the snapshot could contain "holes",
-the result of the tracers overwriting unconsumed trace packets during
-the record operation. After the snapshot is recorded, the tracers can be
-started again with `lttng start` (see man:lttng-start(1)).
+[[output]]
+Snapshot output
+~~~~~~~~~~~~~~~
+When you take a tracing 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::
+ The output defined by the 'URL' non-option argument or by the
+ arguments of the options.
++
+See man:lttng-create(1) for the format of 'URL'.
+
+Otherwise::
+ The snapshot output of the selected tracing 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.
++
+When you create a snapshot mode tracing 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:
++
+--
+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.
+
+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.
+--
++
+Show the current snapshot output of a tracing session with the
+`list-output` action.
++
+Remove the snapshot output of a tracing session with the
+`del-output` action.
+
+For both the `record` and `add-output` actions:
+
+* Assign a name to a snapshot output with the option:--name='NAME'
+ option.
++
+'NAME' becomes part of the snapshot trace file names which LTTng sends
+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
+ session.
++
+Set the maximum total size of all the snapshot trace files LTTng writes
+with the option:--max-size option.
include::common-cmd-options-head.txt[]
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Take a snapshot of the sub-buffers of the channels contained in
- the tracing session named 'SESSION' instead of the current
- tracing session.
+ Take a snapshot of the sub-buffers of the tracing session named
+ 'SESSION' instead of the current tracing session.
-Snapshot output
-~~~~~~~~~~~~~~~
+Output
+~~~~~~
+See the <<output,Snapshot output>> section above.
+
option:-C 'URL', option:--ctrl-url='URL'::
- Set control path URL to 'URL' (must use option:--data-url option
- also).
+ Set the control path URL to 'URL'.
++
+You must also use the option:--data-url option.
++
+See man:lttng-create(1) for the format of 'URL'.
option:-D 'URL', option:--data-url='URL'::
- Set data path URL to 'URL' (must use option:--ctrl-url option
- also).
+ Set the trace data path URL to 'URL'.
++
+You must also use the option:--ctrl-url option.
++
+See man:lttng-create(1) for the format of 'URL'.
option:-m 'SIZE', option:--max-size='SIZE'::
- Limit the total size of all the snapshot files written when
- recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB),
- and `G` (GiB) suffixes are supported.
+ Set the maximum total size of all the snapshot trace files LTTng
+ writes when taking a snapshot to 'SIZE' bytes.
++
+The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
+supported.
option:-n 'NAME', option:--name='NAME'::
Assign the name 'NAME' to the snapshot output.
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7),
+man:lttng-create(1)
lttng-start(1)
==============
-:revdate: 21 April 2021
+:revdate: 29 April 2021
NAME
The tracing session named 'SESSION'.
Without the 'SESSION' argument::
- The current tracing session (see man:lttng-create(1) and
- man:lttng-set-session(1) to learn more about the current tracing
- session).
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+
+See man:lttng-concepts(7) to learn more about tracing sessions.
The selected tracing session must be inactive (stopped). A tracing
session is inactive on creation (see man:lttng-create(1)).
-An active tracing session is an implicit recording event rule condition
-(see man:lttng-enable-event(1)). In other words, a recording event rule
-cannot match an event when its tracing session is inactive.
-
A `start-session` trigger action can also start a tracing session
(see man:lttng-add-trigger(1)).
--------
man:lttng(1),
man:lttng-add-trigger(1),
+man:lttng-concepts(7),
man:lttng-create(1),
man:lttng-enable-event(1),
man:lttng-stop(1)
lttng-status(1)
===============
-:revdate: 21 April 2021
+:revdate: 29 April 2021
NAME
DESCRIPTION
-----------
The `lttng status` command shows the status of the current tracing
-session (see man:lttng-create(1) and man:lttng-set-session(1) to learn
-more about the current tracing session).
+session (see man:lttng-concepts(7) to learn more about the current
+tracing session).
This command is equivalent to:
SEE ALSO
--------
man:lttng(1),
+man:lttng-concepts(7),
man:lttng-create(1),
man:lttng-list(1),
man:lttng-set-session(1)
lttng-stop(1)
=============
-:revdate: 21 April 2021
+:revdate: 29 April 2021
NAME
The tracing session named 'SESSION'.
Without the 'SESSION' argument::
- The current tracing session (see man:lttng-create(1) and
- man:lttng-set-session(1) to learn more about the current tracing
- session).
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+
+See man:lttng-concepts(7) to learn more about tracing sessions.
The selected tracing session must be active (started; see
man:lttng-start(1)). A tracing session is inactive on creation (see
man:lttng-create(1)).
-An active tracing session is an implicit recording event rule condition
-(see man:lttng-enable-event(1)). In other words, a recording event rule
-cannot match an event when its tracing session is inactive.
-
A `stop-session` trigger action can also stop a tracing session (see
man:lttng-add-trigger(1)).
--------
man:lttng(1),
man:lttng-add-trigger(1),
+man:lttng-concepts(7),
man:lttng-create(1),
man:lttng-enable-event(1),
man:lttng-rotate(1),
lttng-track(1)
==============
-:revdate: 4 March 2020
+:revdate: 1 May 2021
NAME
----
-lttng-track - Add one or more values to an LTTng process attribute tracker
+lttng-track - Allow specific processes to record LTTng events
SYNOPSIS
--------
-Add specific process attribute values to a Linux kernel domain tracker:
+Allow specific processes to record Linux kernel events:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION']
(option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
- option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... |
- option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )...
+ option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... |
+ option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)...
-Add all possible process attribute values to a Linux kernel domain tracker:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel
- option:--all (option:--pid | option:--vpid | option:--uid |
- option:--vuid | option:--gid | option:--vgid )...
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION']
+ option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)...
-Add specific process attribute values to a user space domain tracker:
+Allow specific processes to record user space events:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace
- (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
-
-Add all possible process attribute values to a user space domain tracker:
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION']
+ (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... |
+ option:--vgid=VGROUP[,VGROUP]...)...
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION']
option:--all (option:--vpid | option:--vgid | option:--vuid)...
DESCRIPTION
-----------
-The `lttng track` commands adds one or more values to a
-process attribute tracker.
+The `lttng track` command allows one or more processes to record LTTng
+events based on their attributes within:
-A process attribute tracker is an _inclusion set_ of process attributes.
-Tracked processes are allowed to emit events, provided those events are
-targeted by enabled recording event rules (see
-man:lttng-enable-event(1)).
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-Tracker values can be removed from an inclusion set with
-man:lttng-untrack(1).
+Without the option:--session option::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
-The available process attribute trackers are:
+See man:lttng-concepts(7) to learn more about tracing sessions and
+recording event rules.
-* Process ID (PID)
-* Virtual PID (VPID)
-* User ID (UID)
-* Virtual UID (VUID)
-* Group ID (GID)
-* Virtual GID (VGID)
+The `track` command adds values to _inclusion sets_ of process
+attributes. The available inclusion sets are, for a given tracing
+session:
+With the option:--kernel option::
++
+* Process ID (PID).
-A tracker follows one or more process attribute values; only the
-processes with a tracked value are allowed to emit events. By default,
-all possible values on the system are tracked: any process may emit
-enabled events, the equivalent of:
+* Virtual process ID (VPID).
++
+This is the PID as seen by the application.
-[role="term"]
-----
-$ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all
-$ lttng track --userspace --vpid --vuid --vgid --all
-----
+* Unix user ID (UID).
-With the PID tracker, for example, you can record all system calls of a
-given process:
+* Virtual Unix user ID (VUID).
++
+This is the UID as seen by the application.
+
+* Unix group ID (GID).
+
+* Virtual Unix group ID (VGID).
++
+This is the GID as seen by the application.
+
+With the option:--userspace option::
++
+* VPID
+* VUID
+* VGID
+
+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
+of{nbsp}__ER__.
+
+By default, on tracing 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
+process attribute values.
+
+If a given inclusion set{nbsp}__IS__ contains all the possible values
+(option:--all option), then using the `track` command to add one or more
+values{nbsp}__V__ to{nbsp}__IS__:
+
+. Removes all the values from{nbsp}__IS__.
++
+This effectively makes{nbsp}__IS__ empty.
+
+. Adds{nbsp}__V__ to{nbsp}__IS__.
+
+Example: with the PID inclusion set, you can record all the system calls
+of a given process:
[role="term"]
----
$ lttng start
----
-If all the PIDs are tracked (with the option:--pid and option:--all
-options), which is the default state of all domains when creating a
-tracing session), then using the track command with one or more
-specific PIDs has the effect of first removing all the PIDs from the
-inclusion set, then adding the specified PIDs.
+Remove values from an inclusion set with the man:lttng-untrack(1)
+command.
-Example
-~~~~~~~
-Assume the maximum system PID is 7 for this example.
+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.
-Initial inclusion set:
+Assume the maximum system PID is 7 for this example.
+. Initial inclusion set:
++
-------------------------------
[0] [1] [2] [3] [4] [5] [6] [7]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----
$ lttng track --kernel --pid=3,6,7
----
-
-inclusion set:
-
++
+Inclusion set is now:
++
-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----
$ lttng untrack --kernel --pid=7
----
-
-inclusion set:
-
++
+Inclusion set is now:
++
-------------------------------
[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----
$ lttng track --kernel --pid=1,5
----
-
-inclusion set:
-
++
+Inclusion set is now:
++
-------------------------------
[ ] [1] [ ] [3] [ ] [5] [6] [ ]
-------------------------------
-See the man:lttng-untrack(1) for more details about removing
-values from the inclusion set.
+Remove values from an inclusion set with the man:lttng-untrack(1)
+command.
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-k, option:--kernel::
- Track process attributes in the Linux kernel domain.
+ Add values to one or more Linux kernel inclusion sets.
option:-u, option:--userspace::
- Track process attributes in the user space domain.
-
+ Add values to one or more user space inclusion sets.
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Track process attributes in the tracing session named 'SESSION' instead of
- the current tracing session.
+ Add values to one or more inclusion sets of the tracing session
+ named 'SESSION' instead of the current tracing session.
-Tracking
-~~~~~~~~
-option:-a, option:--all::
- Used in conjunction with a single, empty option:--pid,
- option:--vpid, option:--uid, option:--vuid, option:--gid,
- or option:--vgid option: track _all_ possible process attribute
- values (add all values to the inclusion set).
-
+Inclusion set selection
+~~~~~~~~~~~~~~~~~~~~~~~
option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
- Track process ID values 'PID' (add them to the process ID inclusion
- set).
+ For each 'PID' argument, add 'PID' to the process ID inclusion set
+ of the selected tracing session and domain.
+
-'PID' is the process ID attribute of a process as seen from the _root
-PID namespace_ (see man:pid_namespaces(7)). It can only be used with
-the option:--kernel domain option.
+'PID' is the process ID attribute of a process as seen from the root
+PID namespace (see man:pid_namespaces(7)).
+
-The 'PID' argument must be omitted when also using the option:--all
-option.
+Only available with option:--kernel option.
option:--vpid[='VPID'[,'VPID']...]::
- Track virtual process ID values 'VPID' (add them to the virtual
- process ID inclusion set).
+ For each 'VPID' argument, add 'VPID' to the virtual process ID
+ inclusion set of the selected tracing 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)).
-+
-The 'VPID' argument must be omitted when also using the option:--all
-option.
+the PID namespace of the process (see man:pid_namespaces(7)).
option:--uid[='USER'[,'USER']...]::
- Track user ID process attribute values 'USER' (add them to the
- user ID inclusion set).
+ For each 'USER' argument, add 'USER' to the user ID inclusion set of
+ the selected tracing session and domain.
+
-'USER' is the real user ID (see man:getuid(3)) of a process as seen
-from the _root user namespace_ (see man:user_namespaces(7)). It can
-only be used with the option:--kernel domain option.
+'USER' is either:
+
-'USER' can also be a user name. The user name resolution is performed
-by the session daemon (see man:lttng-sessiond(8)) on addition to the
-user ID inclusion set.
+--
+* The real user ID (see man:getuid(3)) of a process as seen
+ from the root user namespace (see man:user_namespaces(7)).
+
+* A user name.
++
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the user name resolution on addition to the user ID inclusion set.
+--
+
-The 'USER' argument must be omitted when also using the option:--all
-option.
+Only available with option:--kernel option.
-option:--vuid[='USER'[,'USER']...]::
- Track virtual user ID process attribute values 'USER' (add them to
- the virtual user ID inclusion set).
+option:--vuid[='VUSER'[,'VUSER']...]::
+ For each 'VUSER' argument, add 'VUSER' to the virtual user ID
+ inclusion set of the selected tracing session and domain.
+
-'USER' is the real user ID (see man:getuid(3)) of a process as seen
-from the _user namespace_ of the process (see man:user_namespaces(7)).
+'VUSER' is either:
+
-'USER' can also be a user name. The user name resolution is performed
-by the session daemon (see man:lttng-sessiond(8)) on addition to the
-virtual user ID inclusion set.
+--
+* The real user ID (see man:getuid(3)) of a process as seen
+ from the user namespace (see man:user_namespaces(7)).
+
+* A user name.
+
-The 'USER' argument must be omitted when also using the option:--all
-option.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the user name resolution on addition to the virtual user ID inclusion
+set.
+--
option:--gid[='GROUP'[,'GROUP']...]::
- Track group ID process attribute values 'GROUP' (add them to the
- group ID inclusion set).
+ For each 'GROUP' argument, add 'GROUP' to the group ID
+ inclusion set of the selected tracing session and domain.
+
-'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
-from the _root user namespace_ (see man:user_namespaces(7)). It can
-only be used with the option:--kernel domain option.
+'GROUP' is either:
+
-'GROUP' can also be a group name. The group name resolution is
-performed by the session daemon (see man:lttng-sessiond(8)) on addition
-to the group ID inclusion set.
+--
+* The real group ID (see man:getgid(3)) of a process as seen from the
+ root user namespace (see man:user_namespaces(7)).
+
+* A group name.
++
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the group name resolution on addition to the group ID inclusion set.
+--
+
-The 'GROUP' argument must be omitted when also using the option:--all
-option.
+Only available with option:--kernel option.
-option:--vgid[='GROUP'[,'GROUP']...]::
- Track virtual group ID process attribute values 'GROUP'(add them to
- the virtual group ID inclusion set).
+option:--vgid[='VGROUP'[,'VGROUP']...]::
+ For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID
+ inclusion set of the selected tracing session and domain.
+
-'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
-from the _user namespace_ of the process (see man:user_namespaces(7)).
+'VGROUP' is either:
+
-'GROUP' can also be a group name. The group name resolution is performed
-by the session daemon (see man:lttng-sessiond(8)) on addition to the
-virtual group ID inclusion set.
+--
+* The real group ID (see man:getgid(3)) of a process as seen
+ from the user namespace (see man:user_namespaces(7)).
+
+* A group name.
+
-The 'GROUP' argument must be omitted when also using the option:--all
-option.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the group name resolution on addition to the virtual group ID inclusion
+set.
+--
+
+
+Inclusion set operation
+~~~~~~~~~~~~~~~~~~~~~~~
+option:-a, option:--all::
+ With one or more empty option:--pid, option:--vpid, option:--uid,
+ option:--vuid, option:--gid, and option:--vgid options: add *all*
+ the possible values to the selected inclusion sets.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
-man:lttng-untrack(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7),
+man:lttng-untrack(1)
lttng-untrack(1)
================
-:revdate: 4 March 2020
+:revdate: 1 May 2021
NAME
----
-lttng-untrack - Remove one or more values from an LTTng process attribute tracker
+lttng-untrack - Disallow specific processes to record LTTng events
SYNOPSIS
--------
-Remove specific process attribute values from a Linux kernel domain tracker:
+Disallow specific processes to record Linux kernel events:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
(option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
- option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... |
- option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )...
-
-Remove all possible process attribute values from a Linux kernel domain tracker:
+ option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... |
+ option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)...
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
- option:--all (option:--pid | option:--vpid | option:--uid |
- option:--vuid | option:--gid | option:--vgid )...
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
+ option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)...
-Remove specific process attribute values from a user space domain tracker:
+Disallow specific processes to record user space events:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
- (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
-
-Remove all possible process attribute values from a user space domain tracker:
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
+ (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... |
+ option:--vgid=VGROUP[,VGROUP]...)...
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
option:--all (option:--vpid | option:--vgid | option:--vuid)...
DESCRIPTION
-----------
-The `lttng untrack` commands removes one or more values from a
-process attribute tracker.
+The `lttng untrack` command disallows one or more processes to record
+LTTng events based on their attributes within:
+
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-See man:lttng-track(1) to learn more about LTTng trackers.
+Without the option:--session option::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
-The untrack command removes specific process attribute values from a
-tracker's inclusion set. The attributes to remove must have been
-precedently added by man:lttng-track(1). It is also possible to remove
-all the possible values of a process attribute from the inclusion set
-using the option:--all option.
+See man:lttng-concepts(7) to learn more about tracing sessions and
+recording event rules.
+
+The `untrack` command removes values from _inclusion sets_ of process
+attributes. See man:lttng-track(1) to learn more about inclusion sets.
Example
~~~~~~~
-One common operation is to create a tracing session
-(see man:lttng-create(1)), remove all the entries from the PID
-tracker inclusion set, start tracing, and then manually track PIDs
-while tracing is active.
+A common operation is to create a tracing session (see
+man:lttng-create(1)), remove all the entries from the PID tracker
+inclusion set, start tracing, and then manually track PIDs while the
+tracing session is active.
Assume the maximum system PID is 7 for this example.
-Command:
-
+. Command:
++
[role="term"]
----
$ lttng create
----
-
++
Initial inclusion set:
-
++
-------------------------------
[0] [1] [2] [3] [4] [5] [6] [7]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----
$ lttng untrack --kernel --pid --all
----
-
-inclusion set:
-
++
+Inclusion set:
++
-------------------------------
[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
-------------------------------
-Commands:
-
+. Commands:
++
[role="term"]
----
$ lttng enable-event --kernel ...
$ # ...
$ lttng track --kernel --pid=3,5
----
-
-inclusion set:
-
++
+Inclusion set:
++
-------------------------------
[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
-------------------------------
-Command:
-
+. Command:
++
[role="term"]
----
$ lttng track --kernel --pid=2
----
-
-inclusion set:
-
++
+Inclusion set:
++
-------------------------------
[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
-------------------------------
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-k, option:--kernel::
- Track process attributes in the Linux kernel domain.
+ Remove values from one or more Linux kernel inclusion sets.
option:-u, option:--userspace::
- Track process attributes in the user space domain.
+ Remove values from one or more user space inclusion sets.
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Untrack process attributes in the tracing session named 'SESSION'
- instead of the current tracing session.
+ Remove values from one or more inclusion sets of the tracing session
+ named 'SESSION' instead of the current tracing session.
-Untracking
-~~~~~~~~~~
-option:-a, option:--all::
- Used in conjunction with a single, empty option:--pid,
- option:--vpid, option:--uid, option:--vuid, option:--gid,
- or option:--vgid option: untrack _all_ possible process attribute
- values (remove all values from the inclusion set).
-
+Inclusion set selection
+~~~~~~~~~~~~~~~~~~~~~~~
option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
- Untrack process ID values 'PID' (remove them from the process ID
- inclusion set).
+ For each 'PID' argument, remove 'PID' from the process ID inclusion
+ set of the selected tracing session and domain.
+
-'PID' is the process ID attribute of a process as seen from the _root
-PID namespace_ (see man:pid_namespaces(7)). It can only be used with
-the option:--kernel domain option.
+'PID' is the process ID attribute of a process as seen from the root
+PID namespace (see man:pid_namespaces(7)).
+
-The 'PID' argument must be omitted when also using the option:--all
-option.
+Only available with option:--kernel option.
option:--vpid[='VPID'[,'VPID']...]::
- Untrack virtual process ID values 'VPID' (remove them from the
- virtual process ID inclusion set).
+ For each 'VPID' argument, remove 'VPID' from the virtual process ID
+ inclusion set of the selected tracing 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)).
-+
-The 'VPID' argument must be omitted when also using the option:--all
-option.
+the PID namespace of the process (see man:pid_namespaces(7)).
option:--uid[='USER'[,'USER']...]::
- Untrack user ID process attribute values 'USER' (remove them from
- the user ID inclusion set).
+ For each 'USER' argument, remove 'USER' from the user ID inclusion
+ set of the selected tracing session and domain.
++
+'USER' is either:
+
-'USER' is the real user ID (see man:getuid(3)) of a process as seen
-from the _root user namespace_ (see man:user_namespaces(7)). It can
-only be used with the option:--kernel domain option.
+--
+* The real user ID (see man:getuid(3)) of a process as seen
+ from the root user namespace (see man:user_namespaces(7)).
+
+* A user name.
+
-'USER' can also be a user name. No name resolution is performed;
-'USER' will be matched against the names in the inclusion set.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the user name resolution on removal from the user ID inclusion set.
+--
+
-The 'USER' argument must be omitted when also using the option:--all
-option.
+Only available with option:--kernel option.
-option:--vuid[='USER'[,'USER']...]::
- Untrack virtual user ID process attribute values 'USER' (remove
- them from the virtual user ID inclusion set).
+option:--vuid[='VUSER'[,'VUSER']...]::
+ For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
+ inclusion set of the selected tracing session and domain.
+
-'USER' is the real user ID (see man:getuid(3)) of a process as seen
-from the _user namespace_ of the process (see man:user_namespaces(7)).
+'VUSER' is either:
+
-'USER' can also be a user name. No name resolution is performed;
-'USER' will be matched against the names in the inclusion set.
+--
+* The real user ID (see man:getuid(3)) of a process as seen
+ from the user namespace (see man:user_namespaces(7)).
+
+* A user name.
+
-The 'USER' argument must be omitted when also using the option:--all
-option.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the user name resolution on removal from the virtual user ID inclusion
+set.
+--
option:--gid[='GROUP'[,'GROUP']...]::
- Untrack group ID process attribute values 'GROUP' (remove them
- from the group ID inclusion set).
+ For each 'GROUP' argument, remove 'GROUP' from the group ID
+ inclusion set of the selected tracing session and domain.
++
+'GROUP' is either:
+
-'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
-from the _root user namespace_ (see man:user_namespaces(7)). It can
-only be used with the option:--kernel domain option.
+--
+* The real group ID (see man:getgid(3)) of a process as seen from the
+ root user namespace (see man:user_namespaces(7)).
+
+* A group name.
+
-'GROUP' can also be a group name. No name resolution is performed;
-'GROUP' will be matched against the names in the inclusion set.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the group name resolution on removal from the group ID inclusion set.
+--
+
-The 'GROUP' argument must be omitted when also using the option:--all
-option.
+Only available with option:--kernel option.
-option:--vgid[='GROUP'[,'GROUP']...]::
- Untrack virtual group ID process attribute values 'GROUP'(remove
- them from the virtual group ID inclusion set).
+option:--vgid[='VGROUP'[,'VGROUP']...]::
+ For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
+ ID inclusion set of the selected tracing session and domain.
+
-'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
-from the _user namespace_ of the process (see man:user_namespaces(7)).
+'VGROUP' is either:
+
-'GROUP' can also be a group name. No name resolution is performed;
-'GROUP' will be matched against the names in the inclusion set.
+--
+* The real group ID (see man:getgid(3)) of a process as seen
+ from the user namespace (see man:user_namespaces(7)).
+
+* A group name.
+
-The 'GROUP' argument must be omitted when also using the option:--all
-option.
+The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
+the group name resolution on removal from the virtual group ID inclusion
+set.
+--
+
+
+Inclusion set operation
+~~~~~~~~~~~~~~~~~~~~~~~
+option:-a, option:--all::
+ With one or more empty option:--pid, option:--vpid, option:--uid,
+ option:--vuid, option:--gid, and option:--vgid options: clear the
+ selected inclusion sets.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
-man:lttng-track(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7),
+man:lttng-track(1)
lttng-view(1)
=============
-:revdate: 21 April 2021
+:revdate: 29 April 2021
NAME
The local file system directory 'DIR'.
Otherwise::
- The current tracing session (see man:lttng-create(1) and
- man:lttng-set-session(1) to learn more about the current tracing
- session).
+ The current tracing session (see man:concepts(1) to learn more about
+ the current tracing session).
With the option:--session option or without the option:--trace-path
option, the mode of the selected tracing session may :not: be network
lttng(1)
========
-:revdate: 16 October 2019
+:revdate: 3 May 2021
NAME
----
-lttng - LTTng 2 tracer control command-line tool
+lttng - Control LTTng tracing
SYNOPSIS
--------
[verse]
-*lttng* [option:--group='GROUP'] [option:--mi=xml] [option:--no-sessiond | option:--sessiond-path='PATH']
+*lttng* [option:--group='GROUP'] [option:--mi=**xml**] [option:--no-sessiond | option:--sessiond-path='PATH']
[option:--quiet | option:-verbose...] '<<commands,COMMAND>>' ['COMMAND OPTIONS']
listening LTTng session daemon (man:lttng-sessiond(8)). A session
daemon:
-* Manages tracing sessions (see man:lttng-create(1) to learn more
+* Manages tracing sessions (see man:lttng-concepts(7) to learn more
about tracing sessions).
* Controls the various components (like tracers and consumer daemons) of
NOTE: The LTTng project recommends that you start the session daemon at
boot time for stable and long-term tracing.
+See man:lttng-concepts(7) to learn more about the foundational concepts
+of LTTng.
+
+The `lttng` tool offers a subcommand-based command-line interface. The
+<<commands,COMMANDS>> section below lists the available commands.
+
Session daemon connection
~~~~~~~~~~~~~~~~~~~~~~~~~
`tracing`
LTTng-instrumented user applications automatically register to both the
-root session daemon and the user session daemon. This makes it possible
-for both session daemons to list the available traceable applications
-and known instrumentation points (see man:lttng-list(1)).
+root and user session daemons. This makes it possible for both session
+daemons to list the available instrumented applications and their
+instrumentation points (see man:lttng-list(1)).
OPTIONS
SEE ALSO
--------
-man:babeltrace2(1),
+man:lttng-concepts(7)
man:lttng-relayd(8),
man:lttng-sessiond(8)
projects / lttng-tools.git / commitdiff
