# man pages
/doc/man/*.1
/doc/man/*.3
+/doc/man/*.7
/doc/man/*.8
/doc/man/*.xml
/doc/man/*.html
_AC_DEFINE_AND_SUBST([DEFAULT_EVENT_NOTIFIER_ERROR_COUNT_MAP_SIZE], [4096])
# Command short descriptions
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to a channel])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_CONTEXT], [Add context fields to be recorded])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ADD_TRIGGER], [Add a trigger])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CLEAR], [Clear a tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Tear down tracing sessions])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_CHANNEL], [Disable tracing channels])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_EVENT], [Disable event rules])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_CREATE], [Create a tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DESTROY], [Destroy tracing sessions])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_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_ENABLE_CHANNEL], [Create or enable tracing channels])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_EVENT], [Create or enable event rules])
+_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_HELP], [Display help information about a command])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LIST], [List tracing sessions, domains, channels, and events])
+_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_TRIGGERS], [List triggers])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_LOAD], [Load tracing session configurations])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Manage an LTTng tracing session's data regeneration])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive a tracing session's current trace chunk])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REGENERATE], [Regenerate specific tracing session data])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_REMOVE_TRIGGER], [Remove a trigger])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ROTATE], [Archive the current trace chunk of a tracing session])
_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SAVE], [Save tracing session configurations])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set current tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Snapshot buffers of current tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start tracing])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Get the status of the current tracing session])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop tracing])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_DISABLE_ROTATION], [Unset a rotation schedule])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_ENABLE_ROTATION], [Set a rotation schedule])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Track specific system resources])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack specific system resources])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VERSION], [Show version information])
-_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_VIEW], [Start trace viewer])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SET_SESSION], [Set the current tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_SNAPSHOT], [Take a tracing session snapshot])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_START], [Start a tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STATUS], [Show the status of the current tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_STOP], [Stop a tracing session])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_TRACK], [Track process attrbutes])
+_AC_DEFINE_QUOTED_AND_SUBST([CMD_DESCR_UNTRACK], [Untrack process attributes])
+_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])
if test "x$prefix" = "xNONE"; then
prefix=$ac_default_prefix
lttng-add-trigger \
lttng-remove-trigger \
lttng-list-triggers
-
MAN3_NAMES =
+MAN7_NAMES = lttng-event-rule
MAN8_NAMES = lttng-sessiond lttng-relayd
MAN1_NO_ASCIIDOC_NAMES =
MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
+MAN7_NO_ASCIIDOC_NAMES =
MAN8_NO_ASCIIDOC_NAMES =
# AsciiDoc sources and outputs
MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))
+MAN7_TXT = $(call manaddsuffix,.7.txt,$(MAN7_NAMES))
MAN8_TXT = $(call manaddsuffix,.8.txt,$(MAN8_NAMES))
-MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN8_TXT)
+MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN7_TXT) $(MAN8_TXT)
MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT))
# common AsciiDoc source files
$(srcdir)/common-footer.txt \
$(srcdir)/common-cmd-footer.txt \
$(srcdir)/common-cmd-options-head.txt \
- $(srcdir)/common-cmd-help-options.txt
+ $(srcdir)/common-cmd-help-options.txt \
+ $(srcdir)/common-help-option.txt \
+ $(srcdir)/common-intro.txt
# config
ASCIIDOC_CONF = $(srcdir)/asciidoc.conf
# man pages destinations
MAN1 = $(addsuffix .1,$(MAN1_NAMES))
MAN3 = $(addsuffix .3,$(MAN3_NAMES))
+MAN7 = $(addsuffix .7,$(MAN7_NAMES))
MAN8 = $(addsuffix .8,$(MAN8_NAMES))
MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES))
MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES))
+MAN7_NO_ASCIIDOC = $(addsuffix .7,$(MAN7_NO_ASCIIDOC_NAMES))
MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES))
-MAN = $(MAN1) $(MAN3) $(MAN8)
+MAN = $(MAN1) $(MAN3) $(MAN7) $(MAN8)
# initially empty
CLEANFILES =
%.3: %.3.xml $(XSL_FILE)
$(XTO) $< 2>/dev/null
+%.7.xml: $(srcdir)/%.7.txt $(COMMON_DEPS)
+ $(ADOC_DOCBOOK) -o $@ $<
+
+%.7: %.7.xml $(XSL_FILE)
+ $(XTO) $< 2>/dev/null
+
%.8.xml: $(srcdir)/%.8.txt $(COMMON_DEPS)
$(ADOC_DOCBOOK) -o $@ $<
@echo $(ERR_MSG)
@false
+%.7: $(srcdir)/%.7.txt $(COMMON_DEPS)
+ @echo $(ERR_MSG)
+ @false
+
%.8: $(srcdir)/%.8.txt $(COMMON_DEPS)
@echo $(ERR_MSG)
@false
# those are always installed since they are directly written in troff
dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
dist_man3_MANS = $(MAN3_NO_ASCIIDOC)
+dist_man7_MANS = $(MAN7_NO_ASCIIDOC)
dist_man8_MANS = $(MAN8_NO_ASCIIDOC)
if MAN_PAGES_OPT
# building man pages: we can install and distribute them
dist_man1_MANS += $(MAN1)
dist_man3_MANS += $(MAN3)
+dist_man7_MANS += $(MAN7)
dist_man8_MANS += $(MAN8)
endif # MAN_PAGES_OPT
$(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in
# keep generated man pages that can be considered intermediate files
-.PRECIOUS: %.1 %.3 %.8
+.PRECIOUS: %.1 %.3 %.7 %.8
# command short descriptions
cmd_descr_add_context="@CMD_DESCR_ADD_CONTEXT@"
+cmd_descr_add_trigger="@CMD_DESCR_ADD_TRIGGER@"
cmd_descr_create="@CMD_DESCR_CREATE@"
cmd_descr_destroy="@CMD_DESCR_DESTROY@"
cmd_descr_disable_channel="@CMD_DESCR_DISABLE_CHANNEL@"
cmd_descr_enable_rotation="@CMD_DESCR_ENABLE_ROTATION@"
cmd_descr_help="@CMD_DESCR_HELP@"
cmd_descr_list="@CMD_DESCR_LIST@"
+cmd_descr_list_triggers="@CMD_DESCR_LIST_TRIGGERS@"
cmd_descr_load="@CMD_DESCR_LOAD@"
cmd_descr_regenerate="@CMD_DESCR_REGENERATE@"
+cmd_descr_remove_trigger="@CMD_DESCR_REMOVE_TRIGGER@"
cmd_descr_rotate="@CMD_DESCR_ROTATE@"
cmd_descr_save="@CMD_DESCR_SAVE@"
cmd_descr_set_session="@CMD_DESCR_SET_SESSION@"
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_HOME`::
- Overrides the `$HOME` environment variable. Useful when the user
- running the commands has a non-writable home directory.
+ Path to the LTTng home directory.
++
+Defaults to `$HOME`.
++
+Useful when the Unix user running the commands has a non-writable home
+directory.
`LTTNG_MAN_BIN_PATH`::
- Absolute path to the man pager to use for viewing help information
- about LTTng commands (using man:lttng-help(1) or
- `lttng COMMAND --help`).
+ Absolute path to the manual pager to use to read the LTTng
+ command-line help (with man:lttng-help(1) or with the
+ nloption:--help option) instead of `/usr/bin/man`.
`LTTNG_SESSION_CONFIG_XSD_PATH`::
- Path in which the `session.xsd` session configuration XML
- schema may be found.
+ Path to the directory containing the `session.xsd` tracing session
+ configuration XML schema.
`LTTNG_SESSIOND_PATH`::
- Full session daemon binary path.
+ Absolute path to the LTTng session daemon (see
+ man:lttng-sessiond(8)) binary.
+
-The genoption:--sessiond-path option has precedence over this
-environment variable.
-
-Note that the man:lttng-create(1) command can spawn an LTTng
-session daemon automatically if none is running. See
-man:lttng-sessiond(8) for the environment variables influencing
-the execution of the session daemon.
+The genoption:--sessiond-path general option overrides this environment
+variable.
++
+NOTE: The man:lttng-create(1) command can spawn an LTTng session daemon
+automatically if none is running. See man:lttng-sessiond(8) for the
+environment variables affecting the execution of the session daemon.
FILES
-----
`$LTTNG_HOME/.lttngrc`::
- User LTTng runtime configuration.
+ Unix user's LTTng runtime configuration.
+
-This is where the per-user current tracing session is stored between
-executions of man:lttng(1). The current tracing session can be set
-with man:lttng-set-session(1). See man:lttng-create(1) for
-more information about tracing sessions.
+This is where LTTng stores the name of the Unix user's current tracing
+session between executions of man:lttng(1). man:lttng-create(1) and
+man:lttng-set-session(1) set the current tracing session.
`$LTTNG_HOME/lttng-traces`::
- Default output directory of LTTng traces. This can be overridden
- with the nloption:--output option of the man:lttng-create(1)
- command.
+ Default output directory of LTTng traces in local and snapshot
+ modes.
++
+Override this path with the nloption:--output option of the
+man:lttng-create(1) command.
`$LTTNG_HOME/.lttng`::
- User LTTng runtime and configuration directory.
+ Unix user's LTTng runtime and configuration directory.
`$LTTNG_HOME/.lttng/sessions`::
- Default location of saved user tracing sessions (see
- man:lttng-save(1) and man:lttng-load(1)).
+ Default directory containing the Unix user's saved tracing session
+ configurations (see man:lttng-save(1) and man:lttng-load(1)).
+{system_sessions_dir}+::
- System-wide location of saved tracing sessions
- (see man:lttng-save(1) and man:lttng-load(1)).
+ Directory containing the system-wide saved tracing session
+ configurations (see man:lttng-save(1) and man:lttng-load(1)).
-NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
+NOTE: `$LTTNG_HOME` defaults to the value of the `HOME` environment
+variable.
EXIT STATUS
Program information
~~~~~~~~~~~~~~~~~~~
-option:-h, option:--help::
- Show command help.
-+
-This option, like man:lttng-help(1), attempts to launch
-`/usr/bin/man` to view the command's man page. The path to the man pager
-can be overridden by the `LTTNG_MAN_BIN_PATH` environment variable.
-
-option:--list-options::
- List available command options.
+include::common-help-option.txt[]
OPTIONS
-------
-linkgenoptions:(General options) are described in man:lttng(1).
+See man:lttng(1) for 'linkgenoptions:(GENERAL OPTIONS)'.
--- /dev/null
+option:-h, option:--help::
+ Show help.
++
+This option attempts to launch `/usr/bin/man` to view this manual page.
+Override the manual pager path with the `LTTNG_MAN_BIN_PATH` environment
+variable.
+
+option:--list-options::
+ List available command options and quit.
--- /dev/null
+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.
+
+LTTng consists of Linux kernel modules (for Linux kernel tracing) and
+dynamically loaded libraries (for user application and library tracing).
lttng-add-context(1)
====================
-:revdate: 5 Februrary 2018
+:revdate: 8 April 2021
NAME
----
-lttng-add-context - Add context fields to an LTTng channel
+lttng-add-context - Add context fields to be recorded by LTTng
SYNOPSIS
--------
-Add context fields to a channel:
+Add context fields to be recorded to the LTTng event records of
+one or more channels:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
[option:--session='SESSION'] [option:--channel='CHANNEL']
option:--type='TYPE' [option:--type='TYPE']...
-List the available context fields:
+List the available context field types:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list
DESCRIPTION
-----------
-The `lttng add-context` command adds one or more context fields to a
-channel.
-
-Channels are created with the man:lttng-enable-channel(1) command.
-
-When context fields are added to a channel, all the events emitted
-within this channel contain the dynamic values of those context fields.
-
-If the option:--session option is omitted, the current tracing session
-is used. If the option:--channel option is omitted, the context fields
-are added to all the selected tracing session's channels.
-
-Many context fields can be added to a channel at once by repeating the
-option:--type option.
-
-perf counters are available as per-CPU (`perf:cpu:` prefix) as well as
-per-thread (`perf:thread:` prefix) counters. Currently, per-CPU counters
-can only be used in the Linux kernel tracing domain, while per-thread
-counters can only be used in the user space tracing domain.
-
-It is also possible to enable PMU counters by raw ID using the
-`perf:cpu:raw:rN:NAME` (Linux kernel tracing domain) or
-`perf:thread:raw:rN:NAME` (user space tracing domain), with:
-
-`N`::
- A hexadecimal event descriptor which is the same format as used
- by man:perf-record(1): a concatenation of the event number and umask
- value provided by the processor's manufacturer. The possible values
- for this field are processor-specific.
-
-`NAME`::
+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.
+
+See man:lttng-enable-channel(1) to learn more about LTTng channels.
+
+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.
+
+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).
+
+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.
+
+perf counter context fields are available:
+
+Per-CPU::
+ Prefix: `perf:cpu:`.
++
+Only available for Linux kernel (option:--kernel option) channels.
+
+Per-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:
+
+'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.
+
+'NAME'::
Custom name to easily recognize the counter.
-Application-specific context fields can be added to a channel using the
-following syntax:
+Add an application-specific context field with the following syntax:
[verse]
$app.'PROVIDER':__TYPE__
-with:
-
'PROVIDER'::
Provider name.
'TYPE'::
Context type name.
-NOTE: Make sure to **single-quote** the type when running the command
-from a shell, as `$` is a special character for variable substitution in
-most shells.
+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.
-Use the option:--list option without other arguments to list the
-available context field names.
+List the available context field types with the option:--list option and
+without other arguments.
+
+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.
-See the <<limitations,LIMITATIONS>> section below for a list of
-limitations to consider.
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-j, option:--jul::
- Add context to channel in the `java.util.logging` (JUL) domain.
+ Add context fields to be recorded to the event records of one or
+ more channels of the `java.util.logging` (JUL) tracing domain.
option:-k, option:--kernel::
- Add context to channel in the Linux kernel domain.
+ Add context fields to be recorded to the event records of one or
+ more channels of the Linux kernel tracing domain.
option:-l, option:--log4j::
- Add context to channel in the Apache log4j domain.
+ Add context fields to be recorded to the event records of one or
+ more channels of the Apache log4j tracing domain.
option:-u, option:--userspace::
- Add context to channel in the user space domain.
+ Add context fields to be recorded to the event records of one or
+ more channels of the user space tracing domain.
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
- Add context fields to a channel named 'CHANNEL' instead of adding
- them to all the channels.
+ Add context fields to be recorded to the event records of a channel
+ named 'CHANNEL' instead of all the channels of the selected
+ tracing session.
option:-s 'SESSION', option:--session='SESSION'::
- Add context fields to a channel in the tracing session named 'SESSION'
- instead of the current tracing session.
+ Add context fields to be recorded to the event records of one or
+ more channels of the tracing session named 'SESSION' instead of the
+ current tracing session.
-Context
-~~~~~~~
+Context field type
+~~~~~~~~~~~~~~~~~~
option:--list::
- List the available context fields. Use this option alone.
+ List the available context field types.
++
+You may :not: use this option with the option:--channel,
+option:--session, or option:--type options.
option:-t 'TYPE', option:--type='TYPE'::
- Add context field named 'TYPE'. This option can be repeated as
- many times as needed on the command-line.
+ Add a context field having the type 'TYPE' to be recorded.
++
+Repeat this option to add more than one context field.
include::common-cmd-help-options.txt[]
-[[limitations]]
-LIMITATIONS
------------
-As of this version of LTTng, it is not possible to add context fields to
-a channel once its tracing session has been started (see man:lttng-start(1))
-at least once.
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-enable-channel(1),
+man:lttng-set-session(1)
lttng-add-trigger(1)
-=====================
-:revdate: 27 May 2020
+====================
+:revdate: 23 April 2021
NAME
----
-lttng-add-trigger - Create LTTng triggers
+lttng-add-trigger - Add an LTTng trigger
SYNOPSIS
--------
-
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
- --condition CONDITION-NAME CONDITION-ARGS
- --action ACTION-NAME ACTION-ARGS
- [--action ACTION-NAME ACTION-ARGS]...
-
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-id='UID']
+ option:--condition='CONDTYPE' ['CONDARGS']
+ option:--action='ACTTYPE' ['ACTARGS'] [option:--action='ACTTYPE' ['ACTARGS']]...
DESCRIPTION
-----------
+The `lttng add-trigger` command creates and adds an LTTng _trigger_ to
+the 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.
-The `lttng add-trigger` command is used to create triggers. A
-trigger is an association between a *condition* and one or more
-*actions*. When the condition associated to a trigger is met, the
-actions associated to that trigger are executed. The tracing does not
-have to be active for the conditions to be met, and triggers are
-independent from tracing sessions.
+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.
-The syntax by which conditions and actions are specified is described
-below.
+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
+option:--owner-id option.
-[[conditions]]
-Conditions
-~~~~~~~~~~
+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.
-Conditions are specified with the `--condition` option, followed by a
-condition name, and possibly some more arguments, depending on the
-specific condition. There must be exactly one condition given in the
-`lttng add-trigger` invocation.
+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.
-The available conditions are:
+Remove an existing trigger with the man:lttng-remove-trigger(1) command.
-Event rule: `event-rule-matches [event rule arguments]`::
- This type of condition is met when the tracer encounters an event
- matching the given event rule. The arguments describing the event
- rule are the same as those describing the event rules of the
- man:lttng-enable-event(1) command, with these exceptions:
- - It is not possible to use filter operands that use values from
- the context.
+[[cond-spec]]
+Condition specifier
+~~~~~~~~~~~~~~~~~~~
+Synopsis:
+
+[verse]
+option:--condition='CONDTYPE' ['CONDARGS']
+A condition specifier is the option:--condition option, which specifies
+the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE',
+with zero or more arguments 'CONDARGS'.
+
+The available condition types are:
+
+[[er-matches-cond-spec]]`event-rule-matches`::
+ Synopsis:
++
+[verse]
+option:--condition=event-rule-matches [nloption:--capture='CDESCR']... 'ERSPEC'
+{nbsp}
+
-Fields to capture can be specified with the option:--capture option, followed by
-a capture expression. Zero or more captures can be configured. See the
-<<capture-expr, Capture expression>> section below for more information.
+An `event-rule-matches` condition is considered satisfied when the event
+rule specified with 'ERSPEC' matches an event.
++
+See man:lttng-event-rule(7) to learn how to specify an event rule
+('ERSPEC' part).
++
+Capture event record and context fields with one or more
+nloption:--capture options (see the <<capture-descr,Capture descriptor>>
+section below to learn more). When an `event-rule-matches` condition
+with capture descriptors is satisfied, the captured field values are
+available in the evaluation object of the condition using the
+liblttng-ctl C{nbsp}API.
++
+IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the
+`add-trigger` command from a shell, as capture descriptors can include
+characters having a special meaning for most shells.
-[[actions]]
-Actions
-~~~~~~~
-Actions are specified with the `--action` option, followed by an action
-name, and possibly some more arguments, depending on the specific
-action. There must be at least one action given in the
-`lttng add-trigger` invocation.
+[[capture-descr]]
+Capture descriptor
+~~~~~~~~~~~~~~~~~~
+A capture descriptor is a textual expression which describes how to read
+an event record or context field.
-The available actions are:
+The argument of a nloption:--capture option, when using an
+<<er-matches-cond-spec,``event rule matches'' condition specifier>>
+(`event-rule-matches`), is a capture descriptor.
-Notify: *notify*::
- This action causes the LTTng session daemon to send a notification,
- through its notification mechanism (see man:lttng-sessiond(8)).
- Some details about the condition evaluation are sent along with the
- notification.
+A capture descriptor expression is one of:
-Start session: *start-session* session-name::
- This action causes the LTTng session daemon to start tracing for the
- session with the given name. If no session with the given name exist
- at the time the condition is met, nothing is done.
+'NAME'::
+ An event record field named 'NAME'.
++
+The supported event record field types are:
++
+--
+* Integer
+* Enumeration (integral value)
+* Floating point number
+* Static array of integers
+* Dynamic array (``sequence'') of integers
+* Text string
+--
++
+Examples: `my_field`, `target_cpu`, `ip`.
-Stop session: *stop-session* session-name::
- This action causes the LTTng session daemon to stop tracing for the
- session with the given name. If no session with the given name exist
- at the time the condition is met, nothing is done.
+++$ctx.++__NAME__::
+ A statically-known context field named 'NAME'.
++
+List the available statically-known context field names with
+man:lttng-add-context(1).
++
+Examples: `$ctx.prio`, `$ctx.preemptible`,
+`$ctx.perf:cpu:stalled-cycles-frontend`.
+
+++$app.++__PROVIDER__++.++__NAME__::
+ An application-specific context field named 'NAME' from the
+ provider 'PROVIDER'.
++
+See man:lttng-add-context(1) to learn more about application-specific
+context fields.
++
+Example: `$app.server:cur_user`.
-Rotate session: *rotate-session* session-name::
- This action causes the LTTng session daemon to rotate the session
- with the given name. See man:lttng-rotate(1) for more information
- about the session rotation concept. If no session with the given
- name exist at the time the condition is met, nothing is done.
+__EXPR__++[++__INDEX__++]++::
+ The element at index 'INDEX' of the array field (static or dynamic)
+ identified by the expression 'EXPR'.
++
+'INDEX' must be a constant, positive integral value.
++
+Examples: `ip[3]`, `user_ids[15]`.
-Snapshot session: *snapshot-session* session-name::
- This action causes the LTTng session daemon to take a snapshot of the
- session with the given name. See man:lttng-snapshot(1) for more
- information about the session snapshot concept. If no session with
- the given name exist at the time the condition is met, nothing is
- done.
+If, when an event rule matches, a given capture descriptor doesn't
+identify an existing event or context field, then the captured value is
+reported as being unavailable. This applies to:
+* A nonexistent event record field name.
+* A nonexistent statically-known context field name.
+* A nonexistent application-specific context field name.
+* An out-of-bounds array field index.
-[[capture-expr]]
-Capture expression
-~~~~~~~~~~~~~~~~~~
-A capture expression can be specified with the option:--capture option when
-creating a new event-rule-matches condition. If the capture expression
-corresponds with an event's field when tracing, the runtime dynamic value
-corresponding to the capture expression is captured.
+[[action-spec]]
+Action specifier
+~~~~~~~~~~~~~~~~
+Synopsis:
-NOTE: Make sure to **single-quote** the capture expression when running
-the command from a shell, as capture expressions typically include
-characters having a special meaning for most shells.
+[verse]
+option:--action='ACTTYPE' ['ACTARGS']
+
+An action specifier is the option:--action option, which specifies
+the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero
+or more arguments 'ACTARGS'.
+
+The available action types are:
+
+Notify::
+ Synopsis:
++
+[verse]
+option:--action=notify [nloption:--rate-policy='POLICY']
+{nbsp}
++
+Sends a notification through the notification
+mechanism of the session daemon (see man:lttng-session(8)).
++
+The session daemon sends details about the condition evaluation along
+with the notification.
++
+As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program
+to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers).
++
+See below for the nloption:--rate-policy option.
-* Supported field types:
- - integer,
- - unsigned integer,
- - floating point value,
- - fixed-size array of integers,
- - variable-size array of integers (sequence),
- - enumeration,
- - text string,
- - element of any allowing previous type.
+Start a tracing session::
+ Synopsis:
++
+[verse]
+option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
++
+Starts the tracing session named 'SESSION' like man:lttng-start(1)
+would.
++
+If no tracing session has the name 'SESSION' when LTTng is ready to
+execute the action, LTTng does nothing.
++
+See below for the nloption:--rate-policy option.
-* The dynamic value of an event field is captured by using its name as a C
- identifier.
+Stop a tracing session::
+ Synopsis:
+
-The square bracket notation is available, like in the C
-language, to access array/sequence field.
-Only a constant, positive integer number can be used within square
-brackets. If the index is out of bounds, the capture expression
-evaluates to `unavailable`.
+[verse]
+option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
+
-An enumeration field's value is an integer.
+Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
+
-When the capture's field does not exist, the capture expression
-evaluates to `unavailable`.
+If no tracing session has the name 'SESSION' when LTTng is ready to
+execute the action, LTTng does nothing.
+
-Examples: `my_field`, `target_cpu`, `seq[7]`
+See below for the nloption:--rate-policy option.
-* The dynamic value of a statically-known context field is captured by
- prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of
- available contexts.
+Rotate a tracing session::
+ Synopsis:
++
+[verse]
+option:--action=rotate-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
+
-When the expression's statically-known context field does not exist,
-the capture expression evaluates to `unavailable`.
+Archives the current trace chunk of the tracing session named 'SESSION'
+like man:lttng-rotate(1) would.
+
-Examples: `$ctx.prio`, `$ctx.preemptible`,
-`$ctx.perf:cpu:stalled-cycles-frontend`.
+If no tracing session has the name 'SESSION' when LTTng is ready to
+execute the action, LTTng does nothing.
+
-NOTE: The statically-known context field does NOT need to be added using the
-man:lttng-add-context(1) command. The statically-known context fields are
-always available in the context of triggers.
+See below for the nloption:--rate-policy option.
-* The dynamic value of an application-specific context field is captured by
- prefixing its name with `$app.` (follows the format used to add such a context
- field with the man:lttng-add-context(1) command).
+Take a tracing session snapshot::
+ Synopsis:
+
-When the expression's application-specific context field does not exist,
-the capture expression evaluates to `unavailable`.
+[verse]
+option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
+
-Example: `$app.server:cur_user`.
+Takes a snapshot of the tracing session named 'SESSION' like
+man:lttng-snapshot(1) would.
++
+When the condition of the trigger is satisfied, the tracing session
+named 'SESSION', if any, must be a snapshot-mode tracing session
+(see man:lttng-create(1)).
++
+If no tracing session has the name 'SESSION' when LTTng is ready to
+execute the action, LTTng does nothing.
++
+See below for the nloption:--rate-policy option.
+
+Common action options (as of LTTng{nbsp}{lttng_version}):
+
+nloption:--rate-policy='POLICY'::
+ Set the rate policy of the action to 'POLICY'.
++
+A trigger which ``fires'' (its condition is satisfied) leads to an
+execution request for each of its actions, in order. An execution
+request of a given action{nbsp}__A__ first increments the execution
+request count{nbsp}__C__ of{nbsp}__A__. An execution request can then
+become an actual execution when{nbsp}__C__ satisfies the rate policy
+of{nbsp}__A__.
++
+The default action rate policy is `every:1` (always execute{nbsp}__A__).
+Use this option to specify another rate policy.
+
-NOTE: The application-specific context field does NOT need to be added using the
-man:lttng-add-context(1) command. The application-specific context fields fields
-are always available in the context of triggers.
+'POLICY' is one of:
++
+--
+++once-after:++__COUNT__::
+ Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'.
++
+In other words, execute{nbsp}__A__ a single time after 'COUNT' execution
+requests.
+
+++every:++__COUNT__::
+ Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'.
++
+In other words, execute{nbsp}__A__ every 'COUNT' execution requests.
+--
++
+As of LTTng{nbsp}{lttng_version}, you can use this option with any
+action type, but new action types in the future may not support it.
OPTIONS
-------
+Identification
+~~~~~~~~~~~~~~
+option:--name='NAME'::
+ Set the unique name of the trigger to add to 'NAME' instead of the
+ `add-trigger` command automatically assigning one.
+
+option:--owner-id='UID'::
+ Add the trigger as the Unix user having the user ID 'UID'.
++
+You may only use this option if your Unix user is `root`.
-option:--condition::
- Define the condition for the trigger. See the
- <<conditions,CONDITIONS>> section for more details.
-
-option:--action::
- Define an action for the trigger. See the <<actions,ACTIONS>>
- section for more details.
-option:--id='ID'::
- Set the id of the trigger to 'ID'. If omitted, an id will
- automatically be assigned to the trigger by the session daemon.
+Specifier
+~~~~~~~~~
+option:--condition='CONDTYPE'::
+ Introductory option for a condition specifier of type 'CONDTYPE'.
+
-If a trigger with the specified 'ID' already exists, the trigger
-creation will fail.
+See the <<cond-spec,Condition specifier>> section above to learn more.
-option:--fire-every 'N'::
- Execute the trigger's actions every 'N' times the condition is met.
+option:--action='ACTTYPE'::
+ Introductory option for an action specifier of type 'ACTTYPE'.
++
+See the <<action-spec,Action specifier>> section above to learn more.
-option:--fire-once-after 'N'::
- Execute the trigger's actions once after 'N' times the condition is
- met, then never after that.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:lttng(1),
man:lttng-list-triggers(1),
-man:lttng-remove-trigger(1),
-man:lttng(1)
+man:lttng-remove-trigger(1)
lttng-clear(1)
-===============
-:revdate: 2 April 2020
+==============
+:revdate: 8 April 2021
NAME
----
DESCRIPTION
-----------
The `lttng clear` command clears one or more tracing sessions, that is,
-it deletes the contents of their tracing buffers and all their local and
-streamed trace data.
+it deletes the contents of their tracing buffers and of all their local
+and streamed trace data.
-If no options are specified, the current tracing session is cleared
-(see man:lttng-create(1) for more information about the current
-tracing session).
+The `clear` command clears:
-If 'SESSION' is specified, the existing tracing session named 'SESSION'
-is cleared.
+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.
-With the option:--all option, *all* the tracing sessions, as listed in
-the output of `lttng list` (see man:lttng-list(1)), are cleared.
+With the 'SESSION' argument::
+ The existing 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)).
If a tracing session is configured in snapshot mode (see the
-man:lttng-create(1) command's nloption:--snapshot option), only the
-tracing buffers are cleared.
+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)), only its tracing buffers and its current trace
-chunk are cleared; its archived trace chunks are :not: cleared.
+man:lttng-rotate(1)), 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
`LTTNG_RELAYD_DISALLOW_CLEAR` environment variable of
man:lttng-relayd(8) can disable remote clearing operations. If LTTng
-sends tracing data over the network for 'SESSION' (or for any tracing
-session with the option:--all option) to a relay daemon configured as
-such, `lttng clear` fails.
+sends tracing data over the network for the selected tracing session(s)
+to an LTTng relay daemon configured as such, the `clear` command fails.
include::common-cmd-options-head.txt[]
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-a, option:--all::
- Clear all the tracing sessions instead of the current tracing
- session or the tracing session named 'SESSION'.
+ 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'.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:lttng(1),
man:lttng-create(1),
-man:lttng-rotate(1),
-man:lttng-set-session(1),
man:lttng-relayd(8),
-man:lttng(1)
+man:lttng-rotate(1),
+man:lttng-set-session(1)
lttng-crash(1)
==============
-:revdate: 2 April 2020
+:revdate: 8 April 2021
NAME
----
-lttng-crash - Recover and view LTTng 2 trace buffers in the event of a crash
+lttng-crash - Recover and read LTTng trace buffers in the event of a crash
SYNOPSIS
--------
[verse]
-*lttng-crash* [option:--extract='PATH' | option:--viewer='VIEWER'] [option:-v | option:-vv | option:-vvv] 'SHMDIR'
+*lttng-crash* [option:--extract='DIR' | option:--viewer='READER'] [option:-verbose]... 'SHMDIR'
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).
-
-The `lttng-crash` command-line tool is used to recover and view
-LTTng trace buffers in the event of a system crash.
+The `lttng-crash` command-line tool recovers LTTng trace buffers in the
+event of a system crash.
`lttng-crash` reads files within the directory 'SHMDIR' and does one
of:
Launches a trace reader (see the option:--viewer option) to view the
recovered traces.
-With the option:--extract option::
- Extracts them as uncorrupted LTTng traces on the file system.
+With the option:--extract='DIR' option::
+ Extracts the files as uncorrupted LTTng traces to the 'DIR'
+ directory.
'SHMDIR' is the directory specified as the argument of the
nloption:--shm-path option of the man:lttng-create(1) command used to
OPTIONS
-------
-option:-x 'PATH', option:--extract='PATH'::
- Extract recovered traces to path 'PATH'; do not execute the trace
- viewer.
+option:-x 'DIR', option:--extract='DIR'::
+ Extract recovered traces to the directory 'DIR'; do :not: execute
+ any trace reader.
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`).
-
-option:-e 'VIEWER', option:--viewer='VIEWER'::
- Use trace viewer 'VIEWER' to view the trace buffers. 'VIEWER' is the
- absolute path to the viewer command to use, and it can contain
- command arguments as well. The trace directory paths are passed to
- the 'VIEWER' command as its last arguments.
+Specify this option up to three times to get more levels of verbosity.
+
+option:-e 'READER', option:--viewer='READER'::
+ Use the trace reader 'READER' to read the trace buffers.
++
+'READER' is the absolute path to the reader command to use, and it can
+contain command arguments as well. `lttng-crash` passes the trace
+directory paths to the 'READER' command as its last arguments.
+
Without this option, `lttng crash` uses man:babeltrace2(1) if it's
available. Otherwise, it tries to use man:babeltrace(1).
Program information
~~~~~~~~~~~~~~~~~~~
-option:-h, option:--help::
- Show help.
+include::common-help-option.txt[]
option:-V, option:--version::
- Show version.
+ Show version and quit.
EXIT STATUS
SEE ALSO
--------
+man:babeltrace2(1),
man:lttng(1),
-man:lttng-sessiond(8),
+man:lttng-create(1),
man:lttng-relayd(8),
-man:lttng-ust(3),
-man:babeltrace2(1)
+man:lttng-sessiond(8),
+man:lttng-ust(3)
lttng-create(1)
===============
-:revdate: 18 January 2018
+:revdate: 8 April 2021
NAME
SYNOPSIS
--------
-Local mode:
+Create a local mode tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH']
- [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
+ [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR']
-Network streaming mode:
+Create a network streaming mode tracing session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
(option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
-Snapshot mode:
+Create a snapshot mode tracing session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot
- [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
+ [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
-Live mode:
+Create a live mode tracing session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
- [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
+ [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
DESCRIPTION
-----------
-The `lttng create` command creates a new tracing session.
-
-A tracing session is a named container of channels, which in turn
-contain event rules. It is domain-agnostic, in that channels and event
-rules can be enabled for the user space tracer and/or the Linux
-kernel tracer.
-
-On execution, an `.lttngrc` file is created, if it does not exist, in the
-user's home directory. This file contains the name of the current tracing
-session. When creating a new tracing session with `lttng create`, the
-current tracing session is set to this new tracing session. The
-man:lttng-set-session(1) command can be used to set the current
-tracing session without manually editing the `.lttngrc` file.
-
-If 'SESSION' is omitted, a session name is automatically created having
-this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
-character `/`.
-
-The option:--shm-path option can be used to specify the path to the
-shared memory holding the ring buffers. Specifying a location on an
-NVRAM file system makes it possible to retrieve the latest recorded
-trace data when the system reboots after a crash. To view the events
-of ring buffer files after a system crash, use the
-man:lttng-crash(1) utility.
-
-Tracing sessions are destroyed using the man:lttng-destroy(1)
+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.
+
+* 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)).
+
+Without the 'SESSION' argument, LTTng automatically generates a tracing
+session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
+'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may
+:not: contain the character `/`.
+
+Specify the path of the directory containing the shared memory files
+holding the channel ring buffers with the option:--shm-path option.
+Specifying a location on an NVRAM file system makes it possible to
+recover the latest recorded trace data when the system reboots after a
+crash with the man:lttng-crash(1) utility.
+
+By default, the `create` command automatically spawns a session daemon
+for your Unix user if none is currently running. Override the path of
+the session daemon binary to spawn with the general
+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.
+Start and stop a tracing session with the man:lttng-start(1) and
+man:lttng-stop(1) commands.
-Creation modes
-~~~~~~~~~~~~~~
-There are four tracing session modes:
+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
+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:
[[local-mode]]Local mode::
- Traces the local system and writes the trace to the local
- file system. The option:--output option specifies the trace path.
- Using option:--set-url=file://'PATH' is the equivalent of using
- option:--output='PATH'. The file system output can be disabled using
- the option:--no-output option.
+ 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'.
+
-If none of the options mentioned above are used, then the trace is
-written locally in the `$LTTNG_HOME/lttng-traces` directory
-(`$LTTNG_HOME` defaults to `$HOME`).
+Disable the file system output with the
+option:--no-output option.
++
+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`).
[[network-streaming-mode]]Network streaming mode::
- Traces the local system and sends the trace over the network to
- a listening relay daemon (see man:lttng-relayd(8)).
- The option:--set-url, or option:--ctrl-url and option:--data-url
- options set the trace output destination (see the
- <<url-format,URL format>> section below).
-
-[[snapshot-mode]]Snapshot mode::
- Traces the local system without writing the trace to the local file
- system (implicit option:--no-output option). Channels are automatically
- configured to be snapshot-ready on creation (see
- man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
- command is used to take snapshots of the current ring buffers.
- The option:--set-url, or option:--ctrl-url and option:--data-url
- options set the default snapshot output destination.
-
-[[live-mode]]Live mode::
- Traces the local system, sending trace data to an LTTng relay daemon
- over the network (see man:lttng-relayd(8)). The
- option:--set-url, or option:--ctrl-url and option:--data-url options
- set the trace output destination. The live output URLs cannot use
- the `file://` protocol (see the <<url-format,URL format>>
- section below).
+ Send the trace data over the network to a listening relay daemon
+ (see man:lttng-relayd(8)).
++
+Set the trace 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).
+
+[[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.
++
+LTTng automatically configures the channels of such a tracing session to
+be snapshot-ready on creation (see man:lttng-enable-channel(1)).
++
+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)).
+--
++
+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).
+
+[[live-mode]]Live mode (option:--live option)::
+ Send the trace data over the network to a listening relay daemon
+ (see man:lttng-relayd(8)) for live reading.
++
+Set the trace output destination with the option:--set-url='URL' option,
+or with the option:--ctrl-url='URL' and option:--data-url='URL' options
+(see the <<url-format,URL format>> section below). 'URL' may :not: start
+with `file://`.
[[url-format]]
URL format
~~~~~~~~~~
-The option:--set-url, option:--ctrl-url, and option:--data-url options'
-arguments are URLs.
+The argument of the option:--set-url, option:--ctrl-url, and
+option:--data-url options is an URL.
-The format of those URLs is one of:
+There are two available URL formats.
+Local format::
++
[verse]
-file://'TRACEPATH'
-'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
-
-The `file://` protocol targets the *local file system* and can only
-be used as the option:--set-url option's argument when the session is
-created in <<local-mode,local>> or <<snapshot-mode,snapshot>> mode.
-
-'TRACEPATH'::
- Absolute path to trace files on the local file system.
-
-The other version is available when the session is created in
-<<network-streaming-mode,network streaming>>,
-<<snapshot-mode,snapshot>>, or <<live-mode,live>> mode.
+file://'TRACEDIR'
+{nbsp}
++
+The `file://` protocol targets the *local file system*: you may only use
+such an URL with the option:--set-url option when you create the tracing
+session in local or snapshot mode (see the <<modes,Tracing session
+modes>> section above).
++
+'TRACEDIR':::
+ Absolute path to the directory containing the trace data on the
+ local file system.
-'NETPROTO'::
+Network format::
++
+[verse]
+'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
+{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).
++
+'NETPROTO':::
Network protocol, amongst:
+
--
`net`::
- TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
- are respectively {default_network_control_port} and
- {default_network_data_port}.
+ TCP over IPv4.
++
+The default values of 'CTRLPORT' and 'DATAPORT'
+are respectively {default_network_control_port} and
+{default_network_data_port}.
`net6`::
- TCP over IPv6: same default ports as the `net` protocol.
+ TCP over IPv6.
++
+The default values of 'CTRLPORT' and 'DATAPORT'
+are respectively {default_network_control_port} and
+{default_network_data_port}.
`tcp`::
- Same as the `net` protocol; can only be used with the
- option:--ctrl-url and option:--data-url options together.
+ Same as the `net` protocol.
++
+You may only use this with the option:--ctrl-url and option:--data-url
+options together.
`tcp6`::
- Same as the `net6` protocol; can only be used with the
- option:--ctrl-url and option:--data-url options together.
+ Same as the `net6` protocol.
++
+You can only be use this with the option:--ctrl-url and
+option:--data-url options together.
--
++
+('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]).
-('HOST' | 'IPADDR')::
- Hostname or IP address (IPv6 address *must* be enclosed in brackets
- (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
-
-'CTRLPORT'::
- Control port.
+'CTRLPORT':::
+ Control TCP port.
-'DATAPORT'::
- Data port.
+'DATAPORT':::
+ Data TCP port.
-'TRACEPATH'::
- Path of trace files on the remote file system. This path is relative
- to the base output directory set on the relay daemon side;
- see man:lttng-relayd(8).
+'TRACEDIR':::
+ Path of the directory containing the trace data on the remote file
+ system.
++
+This path is relative to the base output directory of the LTTng relay
+daemon (see the nloption:--output option of man:lttng-relayd(8)).
include::common-cmd-options-head.txt[]
Mode selection
~~~~~~~~~~~~~~
+See the <<modes,Tracing session modes>> section above.
+
+At most one of:
+
option:--live[='DELAYUS']::
- Create the session in <<live-mode,live mode>>.
+ Create the tracing session in live mode.
+
-The optional 'DELAYUS' parameter, given in microseconds, is the
-maximum time the user can wait for the data to be flushed. This mode
-can be set with a network URL (options option:--set-url, or
-option:--ctrl-url and option:--data-url) and must have a relay
-daemon listening (see man:lttng-relayd(8)).
+The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
+for the data to be flushed (sent to the connected LTTng relay daemon).
+The default value of 'DELAYUS' is {default_lttng_live_timer}.
+
-By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
-is set to `net://127.0.0.1`.
+Set the URL of the relay daemon to connect to with the option:--set-url
+option, or with the option:--ctrl-url and option:--data-url options,
+instead of using `net://127.0.0.1`.
++
+The session daemon must be able to connect to a listening relay daemon
+(see man:lttng-relayd(8)).
option:--snapshot::
- Create the session in <<snapshot-mode,snapshot mode>>.
- This is the equivalent of using the option:--no-output option and
- creating all the channels of this new tracing session in overwrite
- mode with an `mmap` output type.
+ 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)).
Output
~~~~~~
option:--no-output::
- In <<local-mode,local mode>>, do not output any trace data.
+ In local mode (see the <<modes,Tracing session modes>> section
+ above), do :not: write any trace data.
++
+You may :not: use this option with the option:--output option.
-option:-o 'PATH', option:--output='PATH'::
- In <<local-mode,local mode>>, set trace output path to 'PATH'.
+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.
-option:--shm-path='PATH'::
- Create shared memory holding buffers at 'PATH'.
+option:--shm-path='DIR'::
+ Set the path of the directory containing the shared memory files
+ holding the channel ring buffers to 'DIR' on the local file sytem.
URL
~~~
-See the <<url-format,URL format>> section above for more information
-about the syntax of the following options' '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:--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.
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.
option:-U 'URL', option:--set-url='URL'::
- Set URL destination of the trace data to 'URL'. It is persistent for
- the session lifetime. This option sets both data
- (option:--data-url option) and control (option:--ctrl-url option)
- URLs at the same time.
+ 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.
+
-In <<local-mode,local>> mode, 'URL' must start with `file://` followed
-by the destination path on the local file system.
+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.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:lttng(1),
man:lttng-destroy(1),
+man:lttng-enable-channel(1),
+man:lttng-relayd(8),
+man:lttng-rotate(1),
+man:lttng-sessiond(8),
man:lttng-set-session(1),
-man:lttng(1)
+man:lttng-start(1),
+man:lttng-stop(1),
+man:lttng-track(1)
lttng-destroy(1)
================
-:revdate: 18 January 2018
+:revdate: 12 April 2021
NAME
----
-lttng-destroy - Destroy an LTTng tracing session
+lttng-destroy - Destroy LTTng tracing sessions
SYNOPSIS
DESCRIPTION
-----------
-The `lttng destroy` command destroys one or more tracing sessions.
+The `lttng destroy` command destroys one or more tracing sessions
+previously created with the man:lttng-create(1) command.
-If no options are specified, the current tracing session is destroyed
-(see man:lttng-create(1) for more information about the current
-tracing session).
+``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.
-If 'SESSION' is specified, the existing tracing session named 'SESSION'
-is destroyed. `lttng list` outputs all the existing tracing sessions
-(see man:lttng-list(1)).
+Use the `destroy` command to destroy:
-If the option:--all option is used, *all* the tracing sessions, as listed
-in the output of `lttng list`, are destroyed.
+With the 'SESSION' argument::
+ The tracing session named 'SESSION'.
-Destroying a tracing session stops any tracing running within the
-latter. By default, the implicit man:lttng-stop(1) command invoked by
-the `lttng destroy` command ensures that the tracing session's trace
-data is valid before returning. With the option:--no-wait option, the
-man:lttng-stop(1) command finishes immediately, hence a local trace
-might not be valid when the command is done. In this case, there is no
-way to know when the trace becomes valid.
+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)).
-Destroying a tracing session does not destroy the recorded trace data,
-if any; it frees resources acquired by the session daemon and tracer
-side, making sure to flush all trace data.
+Otherwise::
+ The current tracing session (see man:lttng-create(1) and
+ man:lttng-set-session(1) to learn more about the current tracing
+ session).
++
+In that case, the current tracing session becomes nonexistent.
-If at least one rotation occurred during the chosen tracing session's
-lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), and
-without the option:--no-wait option, all the tracing session's output
-directory's subdirectories are considered trace chunk archives once the
-command returns: it is safe to read them, modify them, move them, or
-remove them.
+The `destroy` command stops any tracing activity within the selected
+tracing session(s). By default, the command runs the 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.
+
+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.
+
+* 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.
+
+Then all the subdirectories of the output directory of{nbsp}__TS__
+(local or remote) are considered trace chunk archives once the `destroy`
+command exits. In other words, it's safe to read them, modify them, move
+them, or remove then.
include::common-cmd-options-head.txt[]
option:-a, option:--all::
- Destroy all tracing sessions.
+ Destroy all the tracing sessions of your Unix user, as listed in the
+ output of man:lttng-list(1).
option:-n, option:--no-wait::
- Do not ensure that the chosen tracing session's trace data is valid
- before returning to the prompt.
+ Do :not: ensure that the trace data of the tracing session(s) to
+ destroy is valid before exiting.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:lttng(1),
man:lttng-create(1),
-man:lttng-set-session(1),
-man:lttng(1)
+man:lttng-list(1),
+man:lttng-set-session(1)
lttng-disable-channel(1)
========================
-:revdate: 28 November 2016
+:revdate: 21 April 2021
NAME
----
DESCRIPTION
-----------
The `lttng disable-channel` command disables one or more channels
-previously enabled by the man:lttng-enable-channel(1) command.
+previously enabled with the man:lttng-enable-channel(1) command.
-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 disabled using `lttng disable-channel` can
-be specified using the option:--session option. If the option:--session
-option is omitted, the current tracing session is targeted.
+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).
-Note that re-enabling a disabled channel once its tracing session
-has been active at least once is currently not supported.
+The `disable-channel` command disables one channel per 'CHANNEL'
+argument.
+
+As of LTTng{nbsp}{lttng_version}, you may :not: enable a disabled
+channel once its tracing session has ben started (see
+man:lttng-start(1)) at least once.
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-k, option:--kernel::
- Disable channel in the Linux kernel domain.
+ Disable one or more Linux kernel channels.
option:-u, option:--userspace::
- Disable channel in the user space domain.
+ Disable one or more user space channels.
Target
~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Disable channels in the tracing session named 'SESSION'
+ Disable one or more channels of the tracing session named 'SESSION'
instead of the current tracing session.
SEE ALSO
--------
-man:lttng-disable-channel(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-enable-channel(1)
lttng-disable-event(1)
======================
-:revdate: 28 November 2016
+:revdate: 21 April 2021
NAME
----
-lttng-disable-event - Disable LTTng event rules
+lttng-disable-event - Disable LTTng recording event rules
SYNOPSIS
--------
+Disable one or more recording event rules matching Linux kernel
+events:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *disable-event* option:--kernel
+ [option:--tracepoint | option:--syscall | option:--probe | option:--function]
+ (option:--all-events | 'NAME'[,'NAME']...)
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
+
+Disable one or more recording event rules matching user space
+tracepoint or Java/Python logging events:
+
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *disable-event*
- (option:--kernel [option:--probe | option:--function | option:--syscall] |
- option:--userspace | option:--jul | option:--log4j | option:--python)
+ (option:--userspace | option:--jul | option:--log4j | option:--python) [option:--tracepoint]
+ (option:--all-events | 'NAME'[,'NAME']...)
[option:--session='SESSION'] [option:--channel='CHANNEL']
- (option:--all-events | 'EVENT'[,'EVENT']...)
+
DESCRIPTION
-----------
-The `lttng disable-event` command disables one or more event rules
-previously enabled by the man:lttng-enable-event(1) command.
+The `lttng disable-event` command disables one or more enabled recording
+event rules previously created with the man:lttng-enable-event(1)
+command.
-Event rules are always assigned to a channel when they are created. If
-the option:--channel option is omitted, the default channel named
-`channel0` is used.
+As of LTTng{nbsp}{lttng_version}, the `disable-event` command can only
+find recording event rules to disable by their instrumentation point
+type and event name conditions. Therefore, you cannot disable recording
+event rules having a specific instrumentation point log level condition,
+for example.
-If the option:--session option is omitted, the chosen channel is picked
-from the current tracing session.
+List the existing recording event rules of a given tracing session
+and/or channel with the man:lttng-list(1) command.
-If the option:--all-events option is used, all the existing event rules
-of the chosen domain are disabled. Otherwise, at least one event rule
-to disable named 'EVENT' must be specified.
+Without the option:--all-events option, the `disable-event` command
+disables one recording event rule per 'NAME' argument. 'NAME' is the
+exact event name condition pattern of the recording event rule to
+disable, as listed in the output of `lttng list` (see
+man:lttng-list(1)).
-With the option:--kernel option, the event source type can be specified
-using one of the option:--tracepoint, option:--probe,
-option:--function, or option:--syscall options. See
-man:lttng-enable-event(1) for more details about event source
-types.
+Without the option:--channel option, the `disable-event` command selects
+the channel named `channel0`.
-Events can be disabled while tracing is active
-(use man:lttng-start(1) to make a tracing session active).
+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)).
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-j, option:--jul::
- Disable event rules in the `java.util.logging` (JUL) domain.
+ Disable recording event rules in the `java.util.logging` (JUL)
+ domain.
option:-k, option:--kernel::
- Disable event rules in the Linux kernel domain.
+ Disable recording event rules in the Linux kernel domain.
option:-l, option:--log4j::
- Disable event rules in the Apache log4j domain.
+ Disable recording event rules in the Apache log4j domain.
option:-p, option:--python::
- Disable event rules in the Python domain.
+ Disable recording event rules in the Python domain.
option:-u, option:--userspace::
- Disable event rules in the user space domain.
+ Disable recording event rules in the user space tracing domain.
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
- Disable event rules in the channel named 'CHANNEL' instead
- of the default channel name `channel0`.
+ Disable recording event rules attached to the channel named
+ 'CHANNEL' instead of `channel0`.
option:-s 'SESSION', option:--session='SESSION'::
- Disable event rules in the tracing session named 'SESSION'
+ Disable recording event rules in the tracing session named 'SESSION'
instead of the current tracing session.
-Event source type
-~~~~~~~~~~~~~~~~~
-One of:
+Instrumentation point type condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+At most one of:
option:--function::
- Linux kernel kretprobe. Only available with the option:--kernel
- domain option.
+ Only disable recording event rules which match Linux kretprobe
+ events.
++
+Only available with the option:--kernel option.
option:--probe::
- Linux kernel kprobe. Only available with the option:--kernel
- domain option.
+ Only disable recording event rules which match Linux kprobe events.
++
+Only available with the option:--kernel option.
option:--syscall::
- Linux kernel system call. Only available with the option:--kernel
- domain option.
+ Only disable recording event rules which match Linux system call
+ events.
++
+Only available with the option:--kernel option.
option:--tracepoint::
- Linux kernel or application tracepoint. Only available
- with the option:--kernel domain option (default Linux kernel
- domain event source type).
-
-
-Disabling
-~~~~~~~~~
+ Only disable recording event rules which match:
++
+--
+With the option:--kernel or option:--userspace option:::
+ LTTng tracepoint events.
+With the option:--jul, option:--log4j, or option:--python option:::
+ Logging events.
+--
++
+As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
+point type condition option, but this may change in the future.
+
+
+Event name condition
+~~~~~~~~~~~~~~~~~~~~
option:-a, option:--all-events::
- Disable all enabled event rules in the chosen tracing session,
- tracing domain, and channel.
+ Disable recording event rules regardless of their event name
+ condition is.
+
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:lttng(1),
man:lttng-enable-event(1),
-man:lttng(1)
+man:lttng-list(1)
lttng-disable-rotation(1)
=========================
-:revdate: 8 November 2018
+:revdate: 21 April 2021
NAME
----
-lttng-disable-rotation - Unset a tracing session's rotation schedule
+lttng-disable-rotation - Unset a tracing session rotation schedule
SYNOPSIS
DESCRIPTION
-----------
-The `lttng disable-rotation` command unsets a rotation schedule for the
-current tracing session, or for the tracing session named 'SESSION' if
-provided, previously set with the man:lttng-enable-rotation(1) command.
+The `lttng disable-rotation` command unsets a rotation schedule,
+previously set with the man:lttng-enable-rotation(1) command, for:
+
+With the option:--session='SESSION' option::
+ 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).
include::common-cmd-options-head.txt[]
option of the man:lttng-enable-rotation(1) command.
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
- Unset a rotation schedule in the tracing session named 'SESSION'
+ Unset a rotation schedule for the tracing session named 'SESSION'
instead of the current tracing session.
SEE ALSO
--------
+man:lttng(1),
man:lttng-enable-rotation(1),
-man:lttng(1)
+man:lttng-rotate(1)
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. Event,
-rules, when created using man:lttng-enable-event(1), are always
+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.
lttng-enable-event(1)
=====================
-:revdate: 4 April 2019
+:revdate: 13 April 2021
NAME
----
-lttng-enable-event - Create or enable LTTng event rules
+lttng-enable-event - Create or enable LTTng recording event rules
SYNOPSIS
--------
-Create or enable Linux kernel event rules:
+Create or enable one or more recording event rules to match Linux kernel
+tracepoint or system call events:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
- [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall |
- option:--userspace-probe='SOURCE']
- [option:--filter='EXPR'] [option:--session='SESSION']
- [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall]
+ (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
-Create or enable an "all" Linux kernel event rule:
+Create or enable a recording event rule to match Linux kernel events
+created from a dynamic instrumentation point:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
+ (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
[option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
-Create or enable application/library event rules:
+Create or enable one or more recording event rules to match
+user space tracepoint events:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
- (option:--userspace | option:--jul | option:--log4j | option:--python)
- [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
- [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
- [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...)
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint]
+ (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...]
+ [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
+Create or enable one or more recording event rules to match
+Java/Python logging events:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python)
+ [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...)
+ [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
DESCRIPTION
-----------
-The `lttng enable-event` command can create a new event rule, or enable
-one or more existing and disabled ones.
-
-An event rule created by `lttng enable-event` is a set of conditions
-that must be satisfied in order for an actual event to be emitted by an
-LTTng tracer when the execution of an application or a library or the
-Linux kernel reaches an event source (tracepoint, system call, dynamic
-probe). Event sources can be listed with the man:lttng-list(1) command.
-
-The man:lttng-disable-event(1) command can be used to disable
-existing event rules.
-
-Event rules are always assigned to a channel when they are created. If
-the option:--channel option is omitted, a default channel named
-`channel0` is used (and created automatically if it does not exist for
-the specified domain in the selected tracing session).
-
-If the option:--session option is omitted, the chosen channel is picked
-from the current tracing session.
-
-Events can be enabled while tracing is active
-(use man:lttng-start(1) to make a tracing session active).
-
-
-Event source types
-~~~~~~~~~~~~~~~~~~
-Five types of event sources are available in the Linux kernel tracing
-domain (option:--kernel option):
-
-Tracepoint (option:--tracepoint option; default)::
- A Linux kernel tracepoint, that is, a static instrumentation point
- placed in the kernel source code. Standard tracepoints are designed
- and placed in the source code by developers and record useful
- payload fields.
-
-Dynamic kernel probe (option:--probe option)::
- A Linux kernel kprobe, that is, an instrumentation point placed
- dynamically in the compiled kernel code. Dynamic probe events do not
- record any payload field.
-
-Dynamic user space probe (option:--userspace-probe option)::
- A Linux kernel uprobe, that is, an instrumentation point placed
- dynamically in the compiled user space application/library through
- the kernel. Dynamic user space probe events do not record any
- payload field.
-+
-See the <<userspace-probe,Dynamic user space probes>> section for more
-information.
-
-Function probe (option:--function option)::
- A Linux kernel kretprobe, that is, two instrumentation points placed
- dynamically where a function is entered and where it returns in the
- compiled kernel code. Function probe events do not record any
- payload field.
-
-System call (option:--syscall option)::
- A Linux kernel system call. Two instrumentation points are
- statically placed where a system call function is entered and where
- it returns in the compiled kernel code. System call event sources
- record useful payload fields.
-
-The application tracing domains (option:--userspace, option:--jul,
-option:--log4j, or option:--python options) only support tracepoints.
-In the cases of the JUL, Apache log4j, and Python domains, the event
-names correspond to _logger_ names.
-
-
-Understanding event rule conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When creating an event rule with `lttng enable-event`, conditions are
-specified using options. The logical conjunction (logical AND) of all
-those conditions must be true when an event source is reached by an
-application or by the Linux kernel in order for an actual event
-to be emitted by an LTTng tracer.
-
-Any condition that is not explicitly specified on creation is considered
-a _don't care_.
-
-For example, consider the following commands:
+The `lttng enable-event` command does one of:
+
+* Create one or more recording event rules.
+
+* Enable one or more existing, 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_.
+
+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 --loglevel=TRACE_INFO
----
-Here, two event rules are created. The first one has a single condition:
-the tracepoint name must match `hello:world`. The second one has two
-conditions:
-
-* The tracepoint name must match `hello:world`, _and_
-* The tracepoint's defined log level must be at least as severe as
- the `TRACE_INFO` level.
-
-In this case, the second event rule is pointless because the first one
-is more general: it does not care about the tracepoint's log level.
-If an event source matching both event rules is reached by the
-application's execution, only one event is emitted.
-
-The available conditions for the Linux kernel domain are:
-
-* Tracepoint/system call name ('EVENT' argument with option:--tracepoint
- or option:--syscall options) or dynamic probe/function name/address
- (option:--probe, option:--userspace-probe, and option:--function
- option's argument) which must match event source's equivalent.
-+
-You can use `*` characters at any place in the tracepoint or system
-call name as wildcards to match zero or more characters. To use a
-literal `*` character, use :escwc:.
-
-* Filter expression (option:--filter option) executed against the
- dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-expr,Filter expression>> section
- below for more information.
-
-The available conditions for the application domains are:
-
-* Tracepoint name ('EVENT' with option:--tracepoint option) which must
- match event source's equivalent.
-+
-You can use `*` characters at any place in the tracepoint name as
-wildcards to match zero or more characters. To use a literal `*`
-character, use :escwc:. When you create an event rule with a tracepoint
-name containing a wildcard, you can exclude specific tracepoint names
-from the match with the option:--exclude option.
-
-* Filter expression (option:--filter option) executed against the
- dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-expr,Filter expression>> section
- below for more information.
-* Event's log level that must be at least as severe as a given
- log level (option:--loglevel option) or match exactly a given log
- level (option:--loglevel-only option).
-
-When using `lttng enable-event` with a set of conditions that does not
-currently exist for the chosen tracing session, domain, and channel,
-a new event rule is created. Otherwise, the existing event rule is
-enabled if it is currently disabled
-(see man:lttng-disable-event(1)).
-
-The option:--all option can be used alongside the option:--tracepoint
-or option:--syscall options. When this option is used, no 'EVENT'
-argument must be specified. This option defines a single event rule
-matching _all_ the possible events of a given tracing domain for the
-chosen channel and tracing session. It is the equivalent of an 'EVENT'
-argument named `*` (wildcard).
-
-
-[[filter-expr]]
-Filter expression
-~~~~~~~~~~~~~~~~~
-A filter expression can be specified with the option:--filter option
-when creating a new event rule. If the filter expression evaluates
-to true when executed against the dynamic values of an event's fields
-when tracing, the filtering condition passes.
+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).
+
+[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.
+====
+
+List the existing recording event rules of a given tracing session
+and/or channel with the man:lttng-list(1) command.
+
+Disable an existing, enabled recording event rule with the
+man:lttng-disable-event(1) command.
+
+
+Recording event rule overview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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:
+
+Explicit conditions::
+ You set the following conditions when you create or
+ enable{nbsp}__ER__ with the `enable-event` command:
++
+--
+* The instrumentation point type from which LTTng creates{nbsp}__E__
+ has a specific type.
++
+See the <<inst-point-type-cond,Instrumentation point type condition>>
+section below.
+
+* A pattern matches the name of{nbsp}__E__ while another pattern
+ doesn't.
++
+See the <<event-name-cond,Event name condition>> section below.
+
+* 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.
++
+See the <<inst-point-log-level-cond,Instrumentation point log level condition>>
+section below.
+
+* The fields of the payload of{nbsp}__E__ and the current context fields
+ satisfy a filter expression.
++
+See the <<filter-cond,Event payload and context filter condition>>
+section below.
+--
+
+Implicit conditions::
++
+--
+* _ER_ itself is enabled.
++
+A recording event rule is enabled on creation.
++
+Enable an existing, 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.
+
+* The tracing session of{nbsp}__ER__ is active (started).
++
+A tracing session is inactive (stopped) on creation.
++
+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.
++
+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.
+--
+
+The dedicated command-line options of most conditions are optional: if
+you don't specify the option, the associated condition is always
+satisfied.
+
+
+[[inst-point-type-cond]]
+Instrumentation point type condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the instrumentation point type condition
+of a recording event rule if the instrumentation point from which LTTng
+creates{nbsp}__E__ is:
+
+For the Linux kernel tracing domain (option:--kernel option)::
+ With the option:--tracepoint option or without any other instrumentation point type option:::
+ An LTTng kernel tracepoint, that is, a statically defined point
+ in the source code of the kernel image or of a kernel module
+ with LTTng kernel tracer macros.
++
+As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
+point type of the Linux kernel tracing domain, but this may change in
+the future.
++
+List the available Linux kernel tracepoints with `lttng list --kernel`.
+See man:lttng-list(1) to learn more.
+
+ With the option:--syscall option:::
+ The entry and exit 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.
+
+ With the option:--probe option:::
+ A Linux kprobe, that is, a single probe dynamically placed in
+ the compiled kernel code.
++
+The argument of the option:--probe option is the location of the
+kprobe to insert, either a symbol or a
+memory address, while 'RECORDNAME' is the name of the record
+of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
++
+The payload of a Linux kprobe event is empty.
+
+ With the option:--userspace-probe option:::
+ A Linux user space probe, that is, a single probe dynamically
+ placed at the entry of a compiled user space application/library
+ function through the kernel.
++
+The argument of the option:--userspace-probe option is the location
+of the user space probe to insert, one of:
++
+--
+* A path and symbol (ELF method).
+* A path, provider name, and probe name (SystemTap User-level Statically
+ Defined Tracing (USDT) method; a DTrace-style marker).
++
+As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
+are :not: reference-counted.
+--
++
+'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
+<<er-name,Event record name>> section below).
++
+The payload of a Linux user space probe event is empty.
+
+ With the option:--function option:::
+ A Linux kretprobe, that is, two probes dynamically placed at the
+ entry and exit of a function in the compiled kernel code.
++
+The argument of the option:--function option is the location of the
+Linux kretprobe to insert, either a symbol or
+a memory address, while 'RECORDNAME' is the name of the record
+of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
++
+The payload of a Linux kretprobe event is empty.
+
+For the user space tracing domain (option:--userspace option)::
+ With or without the option:--tracepoint option:::
+ An LTTng user space tracepoint, that is, a statically defined
+ point in the source code of a C/$$C++$$ application/library with
+ LTTng user space tracer macros.
++
+As of LTTng{nbsp}{lttng_version}, this is the default and sole
+instrumentation point type of the user space tracing domain, but this
+may change in the future.
++
+List the available user space tracepoints with `lttng list --userspace`.
+See man:lttng-list(1) to learn more.
+
+For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains::
+ With or without the option:--tracepoint option:::
+ A logging statement.
++
+As of LTTng{nbsp}{lttng_version}, this is the default and sole
+instrumentation point type of the `java.util.logging`, Apache log4j, and
+Python tracing domains, but this may change in the future.
++
+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.
-NOTE: Make sure to **single-quote** the filter expression when running
-the command from a shell, as filter expressions typically include
-characters having a special meaning for most shells.
-The filter expression syntax is similar to C language conditional
-expressions (expressions that can be evaluated by an `if` statement),
-albeit with a few differences:
+[[event-name-cond]]
+Event name condition
+~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the event name condition of a recording
+event rule{nbsp}__ER__ if the two following statements are true:
-* C integer and floating point number constants are supported, as well
- as literal strings between double quotes (`"`). You can use `*`
- characters at any place in a literal string as wildcards to match zero
- or more characters. To use a literal `*` character, use :escwc:.
+* You specify the option:--all option or, depending on the
+ instrumentation type condition (see the
+ <<inst-point-type-cond,Instrumentation point type condition>> section
+ above) of{nbsp}__ER__, 'NAME' matches:
++
+--
+LTTng tracepoint::
+ The full name of the tracepoint from which LTTng creates{nbsp}__E__.
+
-Examples: `32`, `-0x17`, `0755`, `12.34`,
-+"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`.
+Note that the full name of a user space tracepoint is
+__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
+name and __NAME__ is the tracepoint name.
+
+Logging statement::
+ The name of the Java or Python logger from which LTTng
+ creates{nbsp}__E__.
-* The dynamic value of an event field is read by using its name as a C
- identifier.
+Linux system call::
+ The name of the system call, without any `sys_` prefix, from which
+ LTTng creates{nbsp}__E__.
+--
+
+* You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]...
+ option or, depending on the instrumentation type condition
+ of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of
+ the user space tracepoint from which LTTng creates{nbsp}__E__.
+
-The dot and square bracket notations are available, like in the C
-language, to access nested structure and array/sequence fields.
-Only a constant, positive integer number can be used within square
-brackets. If the index is out of bounds, the whole filter expression
-evaluates to false (the event is discarded).
+The option:--exclude option is only available with the option:--userspace
+option.
+
+This condition is only meaningful for the LTTng tracepoint, logging
+statement, and Linux system call instrumentation point types: it's
+always satisfied for the other types.
+
+In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
+character means ``match anything''. To match a literal `*` character,
+use :escwc:. To match a literal `,` character, use
+:esccomma:.
+
+IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
+contain the `*` character and when you run the `enable-event` command
+from a shell.
+
+With the LTTng tracepoint, logging statement, and Linux system call
+instrumentation point types, the `enable-event` command creates or
+enables one independent recording event rule per 'NAME' argument
+(non-option, comma-separated). With the option:--all option, the
+`enable-event` command creates or enables a single recording event rule.
+
+
+[[inst-point-log-level-cond]]
+Instrumentation point log level condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the instrumentation point log level
+condition of a recording event rule if either:
+
+* The option:--loglevel and option:--loglevel-only options are
+ missing.
+
+* The log level of the LTTng user space tracepoint or logging statement
+ which creates{nbsp}__E__ is:
+ With the option:--loglevel='LOGLEVEL' option::
+ At least as severe as 'LOGLEVEL'.
+
+ With the option:--loglevel-only='LOGLEVEL' option::
+ Exactly 'LOGLEVEL'.
+
+This condition is only meaningful for the LTTng user space tracepoint
+and logging statement instrumentation point types: it's always satisfied
+for other types.
+
+The available values of 'LOGLEVEL' are, depending on the tracing domain,
+from the most to the least severe:
+
+User space (option:--userspace option)::
+ Shortcuts such as `system` are allowed.
+
-An enumeration field's value is an integer.
+* `TRACE_EMERG` (0)
+* `TRACE_ALERT` (1)
+* `TRACE_CRIT` (2)
+* `TRACE_ERR` (3)
+* `TRACE_WARNING` (4)
+* `TRACE_NOTICE` (5)
+* `TRACE_INFO` (6)
+* `TRACE_DEBUG_SYSTEM` (7)
+* `TRACE_DEBUG_PROGRAM` (8)
+* `TRACE_DEBUG_PROCESS` (9)
+* `TRACE_DEBUG_MODULE` (10)
+* `TRACE_DEBUG_UNIT` (11)
+* `TRACE_DEBUG_FUNCTION` (12)
+* `TRACE_DEBUG_LINE` (13)
+* `TRACE_DEBUG` (14)
+
+`java.util.logging` (option:--jul option)::
+ Shortcuts such as `severe` are allowed.
+
-When the expression's field does not exist, the whole filter expression
-evaluates to false.
+* `JUL_OFF` (`INT32_MAX`)
+* `JUL_SEVERE` (1000)
+* `JUL_WARNING` (900)
+* `JUL_INFO` (800)
+* `JUL_CONFIG` (700)
+* `JUL_FINE` (500)
+* `JUL_FINER` (400)
+* `JUL_FINEST` (300)
+* `JUL_ALL` (`INT32_MIN`)
+
+Apache log4j (option:--log4j option)::
+ Shortcuts such as `severe` are allowed.
++
+* `LOG4J_OFF` (`INT32_MAX`)
+* `LOG4J_FATAL` (50000)
+* `LOG4J_ERROR` (40000)
+* `LOG4J_WARN` (30000)
+* `LOG4J_INFO` (20000)
+* `LOG4J_DEBUG` (10000)
+* `LOG4J_TRACE` (5000)
+* `LOG4J_ALL` (`INT32_MIN`)
+
+Python (option:--python option)::
+ Shortcuts such as `critical` are allowed.
++
+* `PYTHON_CRITICAL` (50)
+* `PYTHON_ERROR` (40)
+* `PYTHON_WARNING` (30)
+* `PYTHON_INFO` (20)
+* `PYTHON_DEBUG` (10)
+* `PYTHON_NOTSET` (0)
+
+
+[[filter-cond]]
+Event payload and context filter condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the event payload and context filter
+condition of a recording event rule if the option:--filter='EXPR'
+option is missing or if 'EXPR' is _true_.
+
+'EXPR' can contain references to the payload fields of{nbsp}__E__ and
+to the current context fields.
+
+IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
+`enable-event` command from a shell, as filter expressions typically
+include characters having a special meaning for most shells.
+
+The expected syntax of 'EXPR' is similar to the syntax of a
+C{nbsp}language conditional expression (an expression which an `if`
+statement can evaluate), but there are a few differences:
+
+* A _NAME_ expression identifies an event payload field named
+ _NAME_ (a C{nbsp}identifier).
++
+Use the C{nbsp}language dot and square bracket notations to access
+nested structure and array/sequence fields. You can only use a constant,
+positive integer number within square brackets. If the index is out of
+bounds, 'EXPR' is _false_.
++
+The value of an enumeration field is an integer.
++
+When a field expression doesn't exist, 'EXPR' is _false_.
+
Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
-* The dynamic value of a statically-known context field is read by
- prefixing its name with `$ctx.`. Statically-known context fields are
- context fields added to channels without the `$app.` prefix using the
- man:lttng-add-context(1) command.
+* A ++$ctx.++__TYPE__ expression identifies the statically-known context
+ field having the type _TYPE_ (a C{nbsp}identifier).
++
+List the available statically-known context field names with the
+man:lttng-add-context(1) command.
+
-When the expression's statically-known context field does not exist,
-the whole filter expression evaluates to false.
+When a field expression doesn't exist, 'EXPR' is _false_.
+
Examples: `$ctx.prio`, `$ctx.preemptible`,
`$ctx.perf:cpu:stalled-cycles-frontend`.
-* The dynamic value of an application-specific context field is read by
- prefixing its name with `$app.` (follows the format used to add such a
- context field with the man:lttng-add-context(1) command).
+* A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
+ application-specific context field having the type _TYPE_ (a
+ C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
+
-When the expression's application-specific context field does not exist,
-the whole filter expression evaluates to false.
+When a field expression doesn't exist, 'EXPR' is _false_.
+
Example: `$app.server:cur_user`.
-The following precedence table shows the operators which are supported
-in a filter expression. In this table, the highest precedence is 1.
-Parentheses are supported to bypass the default order.
-
-IMPORTANT: Unlike the C language, the `lttng enable-event` filter
-expression syntax's bitwise AND and OR operators (`&` and `|`) take
-precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and
-`!=`). This means the filter expression `2 & 2 == 2` is true while the
-equivalent C expression is false.
+* Compare strings, either string fields or string literals
+ (double-quoted), with the `==` and `!=` operators.
++
+When comparing to a string literal, the `*` character means ``match
+anything''. To match a literal `*` character, use :escwc:.
++
+Examples: `my_field == "user34"`, `my_field == my_other_field`,
+`my_field == "192.168.*"`.
+* The precedence table of the operators which are supported in 'EXPR'
+ is as follows. In this table, the highest precedence is{nbsp}1:
++
[options="header"]
|===
|Precedence |Operator |Description |Associativity
|8 |`&&` |Logical AND |Left-to-right
|9 |`\|\|` |Logical OR |Left-to-right
|===
-
++
+Parentheses are supported to bypass the default order.
++
+IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
+(`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
+`<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
+is _true_ while the equivalent C{nbsp}expression is _false_.
++
The arithmetic operators are :not: supported.
-
-All integer constants and fields are first casted to signed 64-bit
++
+LTTng first casts all integer constants and fields to signed 64-bit
integers. The representation of negative integers is two's complement.
This means that, for example, the signed 8-bit integer field 0xff (-1)
becomes 0xffffffffffffffff (still -1) once casted.
-
-Before a bitwise operator is applied, all its operands are casted to
-unsigned 64-bit integers, and the result is casted back to a signed
-64-bit integer. For the bitwise NOT operator, it is the equivalent of
-this C expression:
-
++
+Before a bitwise operator is applied, LTTng casts all its operands to
+unsigned 64-bit integers, and then casts the result back to a signed
+64-bit integer. For the bitwise NOT operator, it's the equivalent of
+this C{nbsp}expression:
++
[source,c]
----
(int64_t) ~((uint64_t) val)
----
-
-For the binary bitwise operators, it is the equivalent of those C
-expressions:
-
++
+For the binary bitwise operators, it's the equivalent of those
+C{nbsp}expressions:
++
[source,c]
----
(int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
(int64_t) ((uint64_t) lhs | (uint64_t) rhs)
----
-
++
If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
-not in the [0,{nbsp}63] range, the whole filter expression evaluates to
-false.
+not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
-NOTE: Although it is possible to filter the process ID of an event when
-the `pid` context has been added to its channel using, for example,
-`$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
-which is much more efficient (see man:lttng-track(1)).
+[NOTE]
+====
+Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
+disallow processes to record LTTng events based on their attributes
+instead of using equivalent statically-known context fields in 'EXPR'
+like `$ctx.pid`.
-Filter expression examples:
+The former method is much more efficient.
+====
+
+'EXPR' examples:
----------------------------
msg_id == 23 && size >= 2048
------------------------------------------------
-[[log-levels]]
-Log levels
-~~~~~~~~~~
-Tracepoints and log statements in applications have an attached log
-level. Application event rules can contain a _log level_ condition.
-
-With the option:--loglevel option, the event source's log level must
-be at least as severe as the option's argument. With the
-option:--loglevel-only option, the event source's log level must match
-the option's argument.
-
-The available log levels are:
+[[er-name]]
+Event record name
+~~~~~~~~~~~~~~~~~
+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__:
-User space domain (option:--userspace option)::
- Shortcuts such as `system` are allowed.
+LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
+ Full name of the tracepoint from which LTTng creates{nbsp}__E__.
+
-* `TRACE_EMERG` (0)
-* `TRACE_ALERT` (1)
-* `TRACE_CRIT` (2)
-* `TRACE_ERR` (3)
-* `TRACE_WARNING` (4)
-* `TRACE_NOTICE` (5)
-* `TRACE_INFO` (6)
-* `TRACE_DEBUG_SYSTEM` (7)
-* `TRACE_DEBUG_PROGRAM` (8)
-* `TRACE_DEBUG_PROCESS` (9)
-* `TRACE_DEBUG_MODULE` (10)
-* `TRACE_DEBUG_UNIT` (11)
-* `TRACE_DEBUG_FUNCTION` (12)
-* `TRACE_DEBUG_LINE` (13)
-* `TRACE_DEBUG` (14)
+Note that the full name of a user space tracepoint is
+__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
+name and __NAME__ is the tracepoint name.
-`java.util.logging` domain (option:--jul option)::
- Shortcuts such as `severe` are allowed.
+`java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
+ `lttng_jul:event`
+
-* `JUL_OFF` (`INT32_MAX`)
-* `JUL_SEVERE` (1000)
-* `JUL_WARNING` (900)
-* `JUL_INFO` (800)
-* `JUL_CONFIG` (700)
-* `JUL_FINE` (500)
-* `JUL_FINER` (400)
-* `JUL_FINEST` (300)
-* `JUL_ALL` (`INT32_MIN`)
+Such an event record has a string field `logger_name` which contains the
+name of the `java.util.logging` logger from which LTTng
+creates{nbsp}__E__.
-Apache log4j domain (option:--log4j option)::
- Shortcuts such as `severe` are allowed.
+Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
+ `lttng_log4j:event`
+
-* `LOG4J_OFF` (`INT32_MAX`)
-* `LOG4J_FATAL` (50000)
-* `LOG4J_ERROR` (40000)
-* `LOG4J_WARN` (30000)
-* `LOG4J_INFO` (20000)
-* `LOG4J_DEBUG` (10000)
-* `LOG4J_TRACE` (5000)
-* `LOG4J_ALL` (`INT32_MIN`)
+Such an event record has a string field `logger_name` which contains the
+name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
-Python domain (option:--python option)::
- Shortcuts such as `critical` are allowed.
+Python logging statement (option:--python and option:--tracepoint options)::
+ `lttng_python:event`
+
-* `PYTHON_CRITICAL` (50)
-* `PYTHON_ERROR` (40)
-* `PYTHON_WARNING` (30)
-* `PYTHON_INFO` (20)
-* `PYTHON_DEBUG` (10)
-* `PYTHON_NOTSET` (0)
+Such an event record has a string field `logger_name` which contains the
+name of the Python logger from which LTTng creates{nbsp}__E__.
+
+Linux system call (option:--kernel and option:--syscall options)::
+ Entry:::
+ ++syscall_entry_++__NAME__, where _NAME_ is the name of the
+ system call from which LTTng creates{nbsp}__E__, without any
+ `sys_` prefix.
+
+ Exit:::
+ ++syscall_exit_++__NAME__, where _NAME_ is the name of the
+ system call from which LTTng creates{nbsp}__E__, without any
+ `sys_` prefix.
+
+Linux kprobe (option:--kernel and option:--probe options)::
+Linux user space probe (option:--kernel and option:--userspace-probe options)::
+ 'RECORDNAME' (first non-option argument).
+Linux kretprobe (option:--kernel and option:--function options)::
+ Entry:::
+ __RECORDNAME__++_entry++
-[[userspace-probe]]
-Dynamic user space probes
-~~~~~~~~~~~~~~~~~~~~~~~~~
-With the option:--userspace-probe option, you can instrument function
-entries of any user space binary (application or library) using either
-an available symbol name or a SystemTap User-level Statically Defined
-Tracing (USDT, a DTrace-style marker) probe's provider and probe names.
-As of this version, only USDT probes that are :not: surrounded by a
-reference counter (semaphore) are supported.
+ Exit:::
+ __RECORDNAME__++_exit++
-The option:--userspace-probe option must be specified with the
-option:--kernel option because it uses Linux's uprobe feature to
-dynamically instrument a user space application or library.
-As of this version, dynamic probe events do not record any payload
-field.
+[[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.
+
+You may enable a disabled recording event rule regardless of the
+activity (started or stopped) of its tracing session (see
+man:lttng-start(1) and man:lttng-stop(1)).
+
+To enable a disabled recording event rule, run the `enable-event`
+command with the exact same options and arguments that you used to
+create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
+must be the exact same string as the one you used on creation.
include::common-cmd-options-head.txt[]
-Domain
-~~~~~~
+Tracing domain
+~~~~~~~~~~~~~~
One of:
option:-j, option:--jul::
- Create or enable event rules in the `java.util.logging`
- (JUL) domain.
+ Create or enable recording event rules in the `java.util.logging`
+ (JUL) tracing domain.
option:-k, option:--kernel::
- Create or enable event rules in the Linux kernel domain.
+ Create or enable recording event rules in the Linux kernel tracing
+ domain.
option:-l, option:--log4j::
- Create or enable event rules in the Apache log4j domain.
+ Create or enable recording event rules in the Apache log4j tracing
+ domain.
option:-p, option:--python::
- Create or enable event rules in the Python domain.
+ Create or enable recording event rules in the Python tracing domain.
option:-u, option:--userspace::
- Create or enable event rules in the user space domain.
+ Create or enable recording event rules in the user space tracing
+ domain.
-Target
-~~~~~~
+Recording target
+~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
- Create or enable event rules in the channel named 'CHANNEL' instead
- of the default channel name `channel0`.
+ Create or enable recording event rules attached to the channel named
+ 'CHANNEL' instead of `channel0`.
option:-s 'SESSION', option:--session='SESSION'::
- Create or enable event rules in the tracing session named 'SESSION'
- instead of the current tracing session.
+ Create or enable recording event rules in the tracing session named
+ 'SESSION' instead of the current tracing session.
-Event source type
-~~~~~~~~~~~~~~~~~
-One of:
+Instrumentation point type condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See the <<inst-point-type-cond,Instrumentation point type condition>>
+section above.
-option:--function='SOURCE'::
- Dynamic kernel return probe (kretprobe). Only available with the
- option:--kernel domain option. 'SOURCE' is one of:
+At most one of:
+
+option:--function='LOC'::
+ Only match Linux kretprobe events.
++
+Only available with the option:--kernel option.
++
+'LOC' is one of:
+
-* Function address (`0x` prefix supported)
-* Function symbol name
-* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+--
+* A function address (`0x` hexadecimal prefix supported).
+* A function symbol name.
+* A function symbol name and an offset
+ (__SYMBOL__++pass:[+]++__OFFSET__ format).
+--
++
+You must specify the event record name with 'RECORDNAME'. See the
+<<er-name,Event record name>> section above to learn more.
-option:--probe='SOURCE'::
- Dynamic kernel probe (kprobe). Only available with the
- option:--kernel domain option. 'SOURCE' is one of:
+option:--probe='LOC'::
+ Only match Linux kprobe events.
++
+Only available with the option:--kernel option.
++
+'LOC' is one of:
++
+--
+* An address (`0x` hexadecimal prefix supported).
+* A symbol name.
+* A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
+--
+
-* Address (`0x` prefix supported)
-* Symbol name
-* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+You must specify the event record name with 'RECORDNAME'. See the
+<<er-name,Event record name>> section above to learn more.
-option:--userspace-probe='SOURCE'::
- Dynamic user space probe (uprobe). Only available with the
- option:--kernel domain option. See the
- <<userspace-probe,Dynamic user space probes>> section.
+option:--userspace-probe='LOC'::
+ Only match Linux user space probe events.
+
-'SOURCE' is one of:
+Only available with the option:--kernel option.
++
+'LOC' is one of:
+
--
\[++elf:++]__PATH__++:++__SYMBOL__::
- Dynamically instrument an available symbol within a user space
- application or library.
+ Probe an available symbol within a user space application or
+ library.
+
--
'PATH'::
Application or library path.
+
-This can be:
+One of:
+
* An absolute path.
* A relative path.
-* An application's name as found in the directories listed in the
+* The name of an application as found in the directories listed in the
`PATH` environment variable.
'SYMBOL'::
Symbol name of the function of which to instrument the entry.
+
-This can be any defined code symbol listed by the man:nm(1) command
-(including with its nloption:--dynamic option which lists dynamic
-symbols).
+'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
+command, including with its nloption:--dynamic option, which lists
+dynamic symbols.
--
+
-As of this version, not specifying `elf:` is equivalent to specifying
-it.
+As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
+specifying it, but this default may change in the future.
+
Examples:
+
* `--userspace-probe=/usr/lib/libc.so.6:malloc`
* `--userspace-probe=./myapp:createUser`
-* `--userspace-probe=httpd:ap_run_open_htaccess`
+* `--userspace-probe=elf:httpd:ap_run_open_htaccess`
++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
- Dynamically instrument a USDT probe within a user space application
- or library.
+ Use a SystemTap User-level Statically Defined Tracing (USDT) probe
+ within a user space application or library.
+
--
'PATH'::
+
* An absolute path.
* A relative path.
-* An application's name as found in the directories listed in the
+* The name of an application as found in the directories listed in the
`PATH` environment variable.
-__PROVIDER__++:++__NAME__::
+'PROVIDER'::
+'NAME'::
USDT provider and probe names.
+
For example, with the following USDT probe:
The provider/probe name pair is `server:accept_request`.
--
+
-Example:
-+
-* `--userspace-probe=sdt:./build/server:server:accept_request`
+Example: `--userspace-probe=sdt:./build/server:server:accept_request`
--
++
+You must specify the event record name with 'RECORDNAME'. See the
+<<er-name,Event record name>> section above to learn more.
option:--syscall::
- Linux kernel system call. Only available with the option:--kernel
- domain option.
+ Only match Linux system call events.
++
+Only available with the option:--kernel option.
option:--tracepoint::
- Linux kernel or application tracepoint (default).
+ Only match:
++
+With the option:--kernel or option:--userspace option:::
+ LTTng tracepoint events.
+With the option:--jul, option:--log4j, or option:--python option:::
+ Logging events.
+With the option:--kernel, not specifying any of the instrumentation
+point type options is equivalent to specifying the option:--tracepoint
+option, but this default may change in the future.
-Log level
-~~~~~~~~~
-One of:
+With the option:--userspace, option:--jul, option:--log4j, and
+option:--python options, not specifying the option:--tracepoint option
+is equivalent to specifying it, but this default may change in the
+future.
+
+
+Event name condition
+~~~~~~~~~~~~~~~~~~~~
+See the <<event-name-cond,Event name condition>> section above.
+
+option:-a, option:--all::
+ Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
+ name) set to `*` (match anything).
++
+You may :not: use this option with a 'NAME' argument.
+
+option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
+ Only match events of which none of the 'XNAME' arguments
+ matches the full name of the LTTng user space tracepoint.
++
+Only available with the option:--userspace option.
++
+'XNAME' is a globbing pattern: the `*` character means ``match
+anything''. To match a literal `*` character, use :escwc:. To match
+a literal `,` character, use :esccomma:.
+
+
+Instrumentation point log level condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See the <<inst-point-log-level-cond,Instrumentation point log level
+condition>> section above.
+
+At most one of:
option:--loglevel='LOGLEVEL'::
- Add log level condition to the event rule: the event source's
- defined log level must be at least as severe as 'LOGLEVEL'.
- See the <<log-levels,Log levels>> section above for the available
- log levels. Only available with application domains.
+ Only match events of which the log level of the LTTng tracepoint or
+ logging statement is at least as severe as 'LOGLEVEL'.
option:--loglevel-only='LOGLEVEL'::
- Add log level condition to the event rule: the event source's
- defined log level must match 'LOGLEVEL'. See the
- <<log-levels,Log levels>> section above for the available log
- levels. Only available with application domains.
-
-
-Filtering and exclusion
-~~~~~~~~~~~~~~~~~~~~~~~
-option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
- Exclude events named 'EVENT' from the event rule. This option
- can be used when the command's 'EVENT' argument contains at least
- one wildcard star (`*`) to exclude specific names. 'EVENT' can also
- contain wildcard stars. To use a
- literal `,` character, use :esccomma:.
- Only available with the option:--userspace domain.
+ Only match events of which the log level of the LTTng tracepoint or
+ logging statement is exactly 'LOGLEVEL'.
-option:-f 'EXPR', option:--filter='EXPR'::
- Add filter expression condition to the event rule. Expression 'EXPR'
- must evaluate to true when executed against the dynamic values of
- event fields. See the <<filter-expr,Filter expression>>
- section above for more information.
+The instrumentation point log level options above are :not: available
+with the option:--kernel option.
-Shortcuts
-~~~~~~~~~
-option:-a, option:--all::
- Equivalent to an 'EVENT' argument named `*` (wildcard) when also
- using the option:--tracepoint (default) or option:--syscall option.
+Event payload and context filter condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See the <<filter-cond,Event payload and context filter condition>>
+section above.
+
+option:-f 'EXPR', option:--filter='EXPR'::
+ Only match events of which 'EXPR', which can contain references to
+ event payload and current context fields, is _true_.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:lttng(1),
man:lttng-disable-event(1),
-man:lttng(1)
+man:lttng-enable-channel(1),
+man:lttng-list(1),
+man:lttng-start(1),
+man:lttng-track(1)
lttng-enable-rotation(1)
========================
-:revdate: 13 November 2018
+:revdate: 21 April 2021
NAME
----
-lttng-enable-rotation - Set a tracing session's rotation schedule
+lttng-enable-rotation - Set a tracing session rotation schedule
SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION']
- (option:--timer='PERIOD' | option:--size='SIZE' | option:--timer='PERIOD' option:--size='SIZE')
+ (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE')
DESCRIPTION
-----------
-The `lttng enable-rotation` command sets a rotation schedule for the
-current tracing session, or for the tracing session named 'SESSION' if
-provided. See man:lttng-rotate(1) for more information about the
-concepts of a tracing session _rotation_ and a _trace chunk_.
+The `lttng enable-rotation` command sets a tracing session rotation
+schedule for:
-With the option:--timer option, the rotation schedule is set so that an
-automatic rotation occurs at least every 'PERIOD' (microseconds without
-a unit suffix).
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-With the option:--size option, the rotation schedule is set
-so that an automatic rotation occurs every time the total size of the
-flushed part of the current trace chunk is at least 'SIZE' (bytes
-without a unit suffix).
+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).
-For both option:--timer and option:--size options, LTTng checks the
-schedule condition periodically using the monitor timers of the tracing
-session's channels (see the nloption:--monitor-timer option of the
-man:lttng-enable-channel(1) command). This means that:
+See man:lttng-rotate(1) for more information about the concepts of a
+tracing session _rotation_ and a _trace chunk_.
-* With the option:--timer option, the automatic rotation can occur when
- the elapsed time since the last automatic rotation is slightly greater
- than 'PERIOD'. The exact precision is governed by the monitor timer's
- precision, which relies on the precision of the platform's
- implementation of POSIX timers.
+With the option:--timer='PERIODUS' option, the `enable-rotation` command
+sets a rotation schedule so that LTTng performs an automatic rotation at
+least every 'PERIODUS'.
-* With the option:--size option, the automatic rotation can occur when
- the size of the flushed part of the current trace chunk is greater
- than 'SIZE'.
+With the option:--size='SIZE' option, the `enable-rotation` command sets
+a rotation schedule so that LTTng performs an automatic rotation every
+time the total size of the flushed part of the current trace chunk is at
+least 'SIZE'.
-You can combine the option:--timer and option:--size options.
+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:
+
+* With the option:--timer='PERIODUS' option, LTTng can perform an
+ automatic rotation when the elapsed time since the last automatic
+ rotation is slightly greater than 'PERIODUS'.
++
+The exact precision depends on the precision of the monitor timer, which
+relies on the precision of the platform implementation of POSIX timers.
+
+* With the option:--size='SIZE' option, LTTng can perform an automatic
+ rotation when the size of the flushed part of the current trace chunk
+ is greater than 'SIZE'.
+
+You may combine the option:--timer and option:--size options.
The naming convention of a trace chunk archive which an automatic
-rotation creates is the same as with the immediate rotation command,
-man:lttng-rotate(1).
+rotation operation creates is the same as with the immediate rotation
+command, man:lttng-rotate(1).
+
+Unset a tracing session rotation schedule with the
+man:lttng-disable-rotation(1) command.
+
+[IMPORTANT]
+====
+The `enable-rotation` command only works when:
+
+* The selected tracing session was created in normal mode or in network
+ streaming mode (see man:lttng-create(1)).
-You can unset a rotation schedule with the man:lttng-disable-rotation(1)
-command.
+* 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)).
-See <<limitations,LIMITATIONS>> for important limitations regarding
-this command.
+For a given tracing session, LTTng only performs an automatic rotation
+when no other rotation is currently happening.
+====
include::common-cmd-options-head.txt[]
Rotation schedule condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:--size='SIZE'::
- Set a rotation schedule so that an automatic rotation occurs every
- time the total size of the flushed part of the current trace chunk
- is at least 'SIZE' bytes. The `k` (kiB), `M` (MiB), and `G` (GiB)
- suffixes are supported.
-
-option:--timer='PERIOD'::
- Set a rotation schedule so that an automatic rotation occurs at
- least every 'PERIOD' microseconds. The `ms` (milliseconds), `s`
- (seconds), `m` (minutes), and `h` (hours) suffixes are supported.
-
-
-Target
-~~~~~~
+ Set a rotation schedule so that LTTng performs an automatic rotation
+ every time the total size of the flushed part of the current trace
+ chunk is at least 'SIZE' bytes.
++
+The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
+supported.
+
+option:--timer='PERIODUS'::
+ Set a rotation schedule so that LTTng performs an automatic rotation at
+ least every 'PERIODUS' microseconds.
++
+The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
+and `h`{nbsp}(hours) suffixes are supported.
+
+
+Recording target
+~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
Set a rotation schedule for the tracing session named 'SESSION'
instead of the current tracing session.
include::common-cmd-help-options.txt[]
-[[limitations]]
-LIMITATIONS
------------
-The `lttng enable-rotation` command only works when:
-
-* The tracing session is 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 in man:lttng-enable-channel(1)).
-
-For a given tracing session, LTTng only performs an automatic rotation
-when no other rotation is currently happening.
-
-
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng-rotate(1),
+man:lttng(1),
+man:lttng-create(1),
man:lttng-disable-rotation(1),
-man:lttng(1)
+man:lttng-rotate(1)
--- /dev/null
+lttng-event-rule(7)
+===================
+:revdate: 19 April 2021
+
+
+NAME
+----
+lttng-event-rule - Common LTTng event rule specification
+
+
+SYNOPSIS
+--------
+Specify an event rule to match Linux kernel tracepoint or system call
+events:
+
+[verse]
+option:--domain=kernel option:--type=(tracepoint | syscall[:entry|:exit|: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'
+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']...
+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']
+pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
+
+
+DESCRIPTION
+-----------
+This manual page shows how to specify an LTTng event rule on the command
+line.
+
+As of LTTng{nbsp}{lttng_version}, the command-line options documented
+here only apply to the `event-rule-matches` trigger condition specifier
+(see man:lttng-add-trigger(1)).
+
+[NOTE]
+====
+This manual page only describes the common event rule options. The
+man:lttng(1) commands which require an event rule specification may
+accept or require other options and arguments, depending on the context.
+
+For example, the man:lttng-add-trigger(1) command also accepts
+nloption:--capture options with the `event-rule-matches` trigger
+condition.
+====
+
+
+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
+~~~~~~~~~~~~~~~~~~~
+For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
+conditions of an event rule, that is:
+
+* The instrumentation point from which LTTng creates{nbsp}__E__ has a
+ specific type.
++
+See the <<inst-point-type-cond,Instrumentation point type condition>>
+section below.
+
+* A pattern matches the name of{nbsp}__E__ while another pattern
+ doesn't.
++
+See the <<event-name-cond,Event name condition>> section below.
+
+* 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.
++
+See the <<inst-point-log-level-cond,Instrumentation point log level
+condition>> section below.
+
+* The fields of the payload of{nbsp}__E__ and the current context fields
+ satisfy a filter expression.
++
+See the <<filter-cond,Event payload and context filter condition>>
+section below.
+
+The dedicated command-line options of most conditions are optional: if
+you don't specify the option, the associated condition is always
+satisfied.
+
+
+[[inst-point-type-cond]]
+Instrumentation point type condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the instrumentation point type condition
+of an event rule if the instrumentation point from which LTTng
+creates{nbsp}__E__ is:
+
+For the Linux kernel tracing domain (option:--domain=++kernel++ option)::
+ With the option:--type=++tracepoint++ option or without any option:--type option:::
+ An LTTng kernel tracepoint, that is, a statically defined point
+ in the source code of the kernel image or of a kernel module
+ with LTTng kernel tracer macros.
++
+As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
+point type of the Linux kernel tracing domain, but this may change in
+the future.
++
+List the available Linux kernel tracepoints with `lttng list --kernel`.
+See man:lttng-list(1) to learn more.
+
+ With the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, or option:--type=++syscall:entry+exit++ option:::
+ The entry, exit, or entry and exit 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.
+
+ With the option:--type=++kprobe++ option:::
+ A Linux kprobe, that is, a single probe dynamically placed in
+ the compiled kernel code.
++
+You must specify the kprobe location with the option:--location option.
++
+The payload of a Linux kprobe event is empty.
+
+ With the option:--type=++uprobe++ option:::
+ A Linux user space probe, that is, a single probe dynamically
+ placed at the entry of a compiled user space application/library
+ function through the kernel.
++
+LTTng{nbsp}{lttng_version} supports the ELF and SystemTap User-level
+Statically Defined Tracing (USDT; a DTrace-style marker) probing
+methods. LTTng only supports USDT probes which are :not:
+reference-counted.
++
+You must specify the user space probe location with the
+option:--location option.
++
+The payload of a Linux user space probe event is empty.
+
+For the user space tracing domain (option:--domain=++user++ option)::
+ With or without the option:--type=++tracepoint++ option:::
+ An LTTng user space tracepoint, that is, a statically defined point
+ in the source code of a C/$$C++$$ application/library
+ with LTTng user space tracer macros.
++
+As of LTTng{nbsp}{lttng_version}, this is the default and sole
+instrumentation point type of the user space tracing domain, but this
+may change in the future.
++
+List the available user space tracepoints with `lttng list --userspace`.
+See man:lttng-list(1) to learn more.
+
+For the `java.util.logging` (option:--domain=++jul++ option), Apache log4j (option:--domain=++log4j++ option), and Python (option:--domain=++python++ option) tracing domains::
+ With or without the option:--type=++logging++ option:::
+ A logging statement.
++
+As of LTTng{nbsp}{lttng_version}, this is the default and sole
+instrumentation point type of the `java.util.logging`, Apache log4j, and
+Python tracing domains, but this may change in the future.
++
+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.
+
+
+[[event-name-cond]]
+Event name condition
+~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the event name condition of an event
+rule{nbsp}__ER__ if the two following statements are true:
+
+* You don't specify the option:--name='NAME' option or, depending on the
+ instrumentation type condition (see the
+ <<inst-point-type-cond,Instrumentation point type condition>> section
+ above) of{nbsp}__ER__, 'NAME' matches:
++
+--
+LTTng tracepoint::
+ The full name of the tracepoint from which LTTng creates{nbsp}__E__.
++
+Note that the full name of a user space tracepoint is
+__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
+name and __NAME__ is the tracepoint name.
+
+Logging statement::
+ The name of the Java or Python logger from which LTTng
+ creates{nbsp}__E__.
+
+Linux system call::
+ The name of the system call, without any `sys_` prefix, from which
+ LTTng creates{nbsp}__E__.
+--
+
+* You don't specify any option:--exclude-name='XNAME' option or
+ none of the 'XNAME' arguments matches the full name of the user space
+ tracepoint from which LTTng creates{nbsp}__E__.
++
+The option:--exclude-name option is only available with the
+option:--domain=++user++ option.
+
+This condition is only meaningful for the LTTng tracepoint, logging
+statement, and Linux system call instrumentation point types: it's
+always satisfied for the other types.
+
+In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
+character means ``match anything''. To match a literal `*` character,
+use :escwc:.
+
+IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
+contain the `*` character and when you run an man:lttng(1) command from
+a shell.
+
+As of LTTng{nbsp}{lttng_version}, not specifying the option:--name
+option is equivalent to specifying option:--name=++\'*\'++, but this
+default may change in the future.
+
+
+[[inst-point-log-level-cond]]
+Instrumentation point log level condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the instrumentation point log level
+condition of an event rule if either:
+
+* You specify the option:--log-level=++..++ option or you don't specify
+ the option:--log-level option.
++
+Defaulting to option:--log-level=++..++ when you don't specify the
+option:--log-level option is specific to LTTng{nbsp}{lttng_version} and
+may change in the future.
+
+* The log level of the LTTng user space tracepoint or logging statement
+ from which LTTng creates{nbsp}__E__ is:
+ With the option:--log-level=__LOGLEVEL__++..++ option::
+ At least as severe as 'LOGLEVEL'.
+
+ With the option:--log-level=__LOGLEVEL__ option::
+ Exactly 'LOGLEVEL'.
+
+As of LTTng{nbsp}{lttng_version}, the ++..++__LOGLEVEL__ and
+__LOGLEVEL__++..++__LOGLEVEL__ formats are :not: supported.
+
+This condition is only meaningful for the LTTng user space tracepoint
+and logging statement instrumentation point types: it's always satisfied
+for other types.
+
+The available values of 'LOGLEVEL' are, depending on the tracing domain,
+from the most to the least severe:
+
+User space (option:--domain=++user++ option)::
+ Shortcuts such as `system` are allowed.
++
+* `TRACE_EMERG` (0)
+* `TRACE_ALERT` (1)
+* `TRACE_CRIT` (2)
+* `TRACE_ERR` (3)
+* `TRACE_WARNING` (4)
+* `TRACE_NOTICE` (5)
+* `TRACE_INFO` (6)
+* `TRACE_DEBUG_SYSTEM` (7)
+* `TRACE_DEBUG_PROGRAM` (8)
+* `TRACE_DEBUG_PROCESS` (9)
+* `TRACE_DEBUG_MODULE` (10)
+* `TRACE_DEBUG_UNIT` (11)
+* `TRACE_DEBUG_FUNCTION` (12)
+* `TRACE_DEBUG_LINE` (13)
+* `TRACE_DEBUG` (14)
+
+`java.util.logging` (option:--domain=++jul++ option)::
+ Shortcuts such as `severe` are allowed.
++
+* `JUL_OFF` (`INT32_MAX`)
+* `JUL_SEVERE` (1000)
+* `JUL_WARNING` (900)
+* `JUL_INFO` (800)
+* `JUL_CONFIG` (700)
+* `JUL_FINE` (500)
+* `JUL_FINER` (400)
+* `JUL_FINEST` (300)
+* `JUL_ALL` (`INT32_MIN`)
+
+Apache log4j (option:--domain=++log4j++ option)::
+ Shortcuts such as `severe` are allowed.
++
+* `LOG4J_OFF` (`INT32_MAX`)
+* `LOG4J_FATAL` (50000)
+* `LOG4J_ERROR` (40000)
+* `LOG4J_WARN` (30000)
+* `LOG4J_INFO` (20000)
+* `LOG4J_DEBUG` (10000)
+* `LOG4J_TRACE` (5000)
+* `LOG4J_ALL` (`INT32_MIN`)
+
+Python (option:--domain=++python++ option)::
+ Shortcuts such as `critical` are allowed.
++
+* `PYTHON_CRITICAL` (50)
+* `PYTHON_ERROR` (40)
+* `PYTHON_WARNING` (30)
+* `PYTHON_INFO` (20)
+* `PYTHON_DEBUG` (10)
+* `PYTHON_NOTSET` (0)
+
+
+[[filter-cond]]
+Event payload and context filter condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An event{nbsp}__E__ satisfies the event payload and context filter
+condition of an event rule if the option:--filter='EXPR' option is
+missing or if 'EXPR' is _true_.
+
+'EXPR' can contain references to the payload fields of{nbsp}__E__ and
+to the current context fields.
+
+IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an
+man:lttng(1) command from a shell, as filter expressions typically
+include characters having a special meaning for most shells.
+
+The expected syntax of 'EXPR' is similar to the syntax of a
+C{nbsp}language conditional expression (an expression which an `if`
+statement can evaluate), but there are a few differences:
+
+* A _NAME_ expression identifies an event payload field named
+ _NAME_ (a C{nbsp}identifier).
++
+Use the C{nbsp}language dot and square bracket notations to access
+nested structure and array/sequence fields. You can only use a constant,
+positive integer number within square brackets. If the index is out of
+bounds, 'EXPR' is _false_.
++
+The value of an enumeration field is an integer.
++
+When a field expression doesn't exist, 'EXPR' is _false_.
++
+Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
+
+* A ++$ctx.++__TYPE__ expression identifies the statically-known context
+ field having the type _TYPE_ (a C{nbsp}identifier).
++
+List the available statically-known context field names with the
+man:lttng-add-context(1) command.
++
+When a field expression doesn't exist, 'EXPR' is _false_.
++
+Examples: `$ctx.prio`, `$ctx.preemptible`,
+`$ctx.perf:cpu:stalled-cycles-frontend`.
+
+* A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
+ application-specific context field having the type _TYPE_ (a
+ C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
++
+When a field expression doesn't exist, 'EXPR' is _false_.
++
+Example: `$app.server:cur_user`.
+
+* Compare strings, either string fields or string literals
+ (double-quoted), with the `==` and `!=` operators.
++
+When comparing to a string literal, the `*` character means ``match
+anything''. To match a literal `*` character, use :escwc:.
++
+Examples: `my_field == "user34"`, `my_field == my_other_field`,
+`my_field == "192.168.*"`.
+
+* The precedence table of the operators which are supported in 'EXPR'
+ is as follows. In this table, the highest precedence is{nbsp}1:
++
+[options="header"]
+|===
+|Precedence |Operator |Description |Associativity
+|1 |`-` |Unary minus |Right-to-left
+|1 |`+` |Unary plus |Right-to-left
+|1 |`!` |Logical NOT |Right-to-left
+|1 |`~` |Bitwise NOT |Right-to-left
+|2 |`<<` |Bitwise left shift |Left-to-right
+|2 |`>>` |Bitwise right shift |Left-to-right
+|3 |`&` |Bitwise AND |Left-to-right
+|4 |`^` |Bitwise XOR |Left-to-right
+|5 |`\|` |Bitwise OR |Left-to-right
+|6 |`<` |Less than |Left-to-right
+|6 |`<=` |Less than or equal to |Left-to-right
+|6 |`>` |Greater than |Left-to-right
+|6 |`>=` |Greater than or equal to |Left-to-right
+|7 |`==` |Equal to |Left-to-right
+|7 |`!=` |Not equal to |Left-to-right
+|8 |`&&` |Logical AND |Left-to-right
+|9 |`\|\|` |Logical OR |Left-to-right
+|===
++
+Parentheses are supported to bypass the default order.
++
+IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
+(`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
+`<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
+is _true_ while the equivalent C{nbsp}expression is _false_.
++
+The arithmetic operators are :not: supported.
++
+LTTng first casts all integer constants and fields to signed 64-bit
+integers. The representation of negative integers is two's complement.
+This means that, for example, the signed 8-bit integer field 0xff (-1)
+becomes 0xffffffffffffffff (still -1) once casted.
++
+Before a bitwise operator is applied, LTTng casts all its operands to
+unsigned 64-bit integers, and then casts the result back to a signed
+64-bit integer. For the bitwise NOT operator, it's the equivalent of
+this C{nbsp}expression:
++
+[source,c]
+----
+(int64_t) ~((uint64_t) val)
+----
++
+For the binary bitwise operators, it's the equivalent of those
+C{nbsp}expressions:
++
+[source,c]
+----
+(int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
+(int64_t) ((uint64_t) lhs << (uint64_t) rhs)
+(int64_t) ((uint64_t) lhs & (uint64_t) rhs)
+(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
+(int64_t) ((uint64_t) lhs | (uint64_t) rhs)
+----
++
+If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
+not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
+
+'EXPR' examples:
+
+----------------------------
+msg_id == 23 && size >= 2048
+----------------------------
+
+-------------------------------------------------
+$ctx.procname == "lttng*" && (!flag || poel < 34)
+-------------------------------------------------
+
+---------------------------------------------------------
+$app.my_provider:my_context == 17.34e9 || some_enum >= 14
+---------------------------------------------------------
+
+---------------------------------------
+$ctx.cpu_id == 2 && filename != "*.log"
+---------------------------------------
+
+------------------------------------------------
+eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
+------------------------------------------------
+
+
+Migration from a recording event rule specification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Since LTTng{nbsp}2.13, what this manual page documents is the standard,
+common way to specify an LTTng event rule.
+
+With the man:lttng-enable-event(1) command, you also specify an event
+rule, but with deprecated options and arguments.
+
+The following table shows how to translate from the
+man:lttng-enable-event(1) options and arguments to the common event
+rule specification options:
+
+[options="header"]
+|===
+|Recording event rule option(s)/argument(s) |Common event rule option(s)
+
+|nloption:--kernel |option:--domain=++kernel++
+|nloption:--userspace |option:--domain=++user++
+|nloption:--jul |option:--domain=++jul++
+|nloption:--log4j |option:--domain=++log4j++
+|nloption:--python |option:--domain=++python++
+|nloption:--tracepoint (with nloption:--kernel/nloption:--userspace) |option:--type=++tracepoint++ or no option:--type option
+|nloption:--tracepoint (with nloption:--jul/nloption:--log4j/nloption:--python) |option:--type=++logging++ or no option:--type option
+|nloption:--syscall |option:--type=++syscall++ or option:--type=++syscall:entry+exit++
+|nloption:--probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++kprobe++, option:--location='LOC', and option:--event-name='RECORDNAME'
+|nloption:--userspace-probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++uprobe++, option:--location='LOC', and option:--event-name='RECORDNAME'
+|nloption:--function='LOC' and 'RECORDNAME' (non-option) |Not available as of LTTng{nbsp}{lttng_version}
+|'NAME' (non-option) |option:--name='NAME'
+|nloption:--all |option:--name=++\'*\'++ or no option:--name option
+|nloption:--exclude=__XNAME__[++,++__XNAME__]... |option:--exclude-name='XNAME' for each 'XNAME'
+|nloption:--loglevel='LOGLEVEL' |option:--log-level=__LOGLEVEL__++..++
+|nloption:--loglevel-only='LOGLEVEL' |option:--log-level=__LOGLEVEL__
+|nloption:--filter='EXPR' |option:--filter='EXPR'
+|===
+
+
+OPTIONS
+-------
+Tracing domain
+~~~~~~~~~~~~~~
+option:-d 'DOMAIN', option:--domain='DOMAIN'::
+ Only match events which LTTng creates in the tracing domain
+ 'DOMAIN'.
++
+'DOMAIN' is one of:
++
+--
+`kernel`:::
+ Linux kernel
+`user`:::
+`userspace`:::
+ User space tracing
+`jul`:::
+ `java.util.logging`
+`log4j`:::
+ Apache log4j
+`python`:::
+ Python
+--
++
+This option is mandatory.
+
+
+Instrumentation point type condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See the <<inst-point-type-cond,Instrumentation point type condition>>
+section above.
+
+option:-E 'NAME', option:--event-name='NAME'::
+ With the option:--type=++kprobe++ or option:--type=++uprobe++
+ option, set the name of the emitted events to 'NAME' instead of the
+ 'LOC' argument of the option:--location='LOC' option.
++
+Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may
+change in the future.
+
+option:-L 'LOC', option:--location='LOC'::
+ With the option:--type=++kprobe++ option:::
+ Set the location of the Linux kprobe to insert to 'LOC'.
++
+'LOC' is one of:
++
+* An address (`0x` hexadecimal prefix supported).
+* A symbol name.
+* A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
+
+ With the option:--type=++uprobe++ option:::
+ Set the location of the user space probe to insert to 'LOC'.
++
+'LOC' is one of:
++
+\[++elf:++]__PATH__++:++__SYMBOL__::::
+ An available symbol within a user space application or library.
++
+--
+'PATH'::
+ Application or library path.
++
+One of:
++
+* An absolute path.
+* A relative path.
+* The name of an application as found in the directories listed in the
+ `PATH` environment variable.
+
+'SYMBOL'::
+ Symbol name of the function of which to instrument the entry.
++
+'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
+command, including with its nloption:--dynamic option, which lists
+dynamic symbols.
+--
++
+As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
+specifying it, but this default may change in the future.
++
+Examples:
++
+* `/usr/lib/libc.so.6:malloc`
+* `./myapp:createUser`
+* `elf:httpd:ap_run_open_htaccess`
+
+++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::::
+ A SystemTap User-level Statically Defined Tracing (USDT) probe
+ within a user space application or library.
++
+--
+'PATH'::
+ Application or library path.
++
+This can be:
++
+* An absolute path.
+* A relative path.
+* The name of an application as found in the directories listed in the
+ `PATH` environment variable.
+
+'PROVIDER'::
+'NAME'::
+ USDT provider and probe names.
++
+For example, with the following USDT probe:
++
+[source,c]
+----
+DTRACE_PROBE2("server", "accept_request",
+ request_id, ip_addr);
+----
++
+The provider/probe name pair is `server:accept_request`.
+--
++
+Example: `sdt:./build/server:server:accept_request`
+
+option:-t 'TYPE', option:--type='TYPE'::
+ Only match events which LTTng creates from an instrumentation point
+ having the type 'TYPE'.
++
+'TYPE' is one of:
++
+--
+`tracepoint`::
+ LTTng tracepoint.
++
+Only available with the option:--domain=++kernel++ and
+option:--domain=++user++ options.
++
+As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
+point type of the Linux kernel and user space tracing domains, but this
+may change in the future.
+
+`logging`::
+ Logging statement.
++
+Only available with the option:--domain=++jul++,
+option:--domain=++log4j++, and option:--domain=++python++ options.
++
+As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
+point type of the `java.util.logging`, Apache log4j, and Python tracing
+domains, but this may change in the future.
+
+`syscall`::
+ As of LTTng{nbsp}{lttng_version}, equivalent to
+ `syscall:entry+exit`, but this default may change in the future.
++
+Only available with the option:--domain=++kernel++ option.
+
+`syscall:entry`::
+ Linux system call entry.
++
+Only available with the option:--domain=++kernel++ option.
+
+`syscall:exit`::
+ Linux system call exit.
++
+Only available with the option:--domain=++kernel++ option.
+
+`syscall:entry+exit`::
+ Linux system call entry and exit (two distinct instrumentation
+ points).
++
+Only available with the option:--domain=++kernel++ option.
+
+`kprobe`::
+ Linux kprobe.
++
+Only available with the option:--domain=++kernel++ option.
++
+You must specify the location of the kprobe to insert with the
+option:--location option.
++
+You may specify the name of the emitted events with the
+option:--event-name option.
+
+`uprobe` or `userspace-probe`::
+ Linux user space probe.
++
+Only available with the option:--domain=++kernel++ option.
++
+You must specify the location of the user space probe to insert with the
+option:--location option.
++
+You may specify the name of the emitted events with the
+option:--event-name option.
+--
+
+
+Event name condition
+~~~~~~~~~~~~~~~~~~~~
+See the <<event-name-cond,Event name condition>> section above.
+
+option:-n 'NAME', option:--name='NAME'::
+ Only match events of which 'NAME' matches:
++
+--
+With the option:--domain=++kernel++ or option:--domain=++user++ option, with the option:--type=++tracepoint++ option or without the option:--type option:::
+ The full name of the LTTng tracepoint.
+
+With the option:--domain=++jul++, option:--domain=++log4j++, or option:--domain=++python++ option:::
+ The Java or Python logger name.
+
+With the option:--domain=++kernel++ option and one of the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, and option:--type=++syscall:entry+exit++ options:::
+ The name of the system call, without any `sys_` prefix.
+--
++
+This option is :not: available with the option:--type=++kprobe++ and
+option:--type=++uprobe++ options.
++
+As of LTTng{nbsp}{lttng_version}, not specifying this option is
+equivalent to specifying option:--name=++\'*\'++ (when it applies), but
+this default may change in the future.
+
+option:-x 'XNAME', option:--exclude='XNAME'::
+ Only match events of which 'XNAME' does :not: match the full name of
+ the LTTng user space tracepoint.
++
+Only available with the option:--domain=++user++ option.
+
+'NAME' and 'XNAME' are globbing patterns: the `*` character means
+``match anything''. To match a literal `*` character, use :escwc:.
+
+
+Instrumentation point log level condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See the <<inst-point-log-level-cond,Instrumentation point log level
+condition>> section above.
+
+option:-l 'LOGLEVELSPEC', option:--log-level='LOGLEVELSPEC'::
+ Only match events of which the log level of the LTTng tracepoint or
+ logging statement is, depending on the format of 'LOGLEVELSPEC':
++
+--
+__LOGLEVEL__++..++::
+ At least as severe as 'LOGLEVEL'.
+
+'LOGLEVEL'::
+ Exactly 'LOGLEVEL'.
+
+++..++::
+ Anything.
+--
++
+This option is :not: available with the option:--domain=++kernel++
+option.
++
+As of LTTng{nbsp}{lttng_version}, not specifying this option is
+equivalent to specifying option:--log-level=++..++ (when it applies),
+but this default may change in the future.
+
+
+Event payload and context filter condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See the <<filter-cond,Event payload and context filter condition>>
+section above.
+
+option:-f 'EXPR', option:--filter='EXPR'::
+ Only match events of which 'EXPR', which can contain references to
+ event payload and current context fields, is _true_.
+
+
+SEE ALSO
+--------
+man:lttng(1),
+man:lttng-add-trigger(1)
lttng-help(1)
=============
-:revdate: 14 March 2017
+:revdate: 21 April 2021
NAME
----
-lttng-help - Display help information about an LTTng command
+lttng-help - Show the help of an LTTng command
SYNOPSIS
DESCRIPTION
-----------
-The `lttng help` command displays help information about an LTTng
-command.
+The `lttng help` command shows the help of:
-This command is the equivalent of:
+With the 'COMMAND' argument::
+ The ++lttng{nbsp}++__COMMAND__ command.
-[role="term"]
-----
-$ lttng COMMAND --help
-----
+Without the 'COMMAND' argument::
+ The man:lttng(1) command itself.
-where `COMMAND` is the name of the command about which to get help. If
-'COMMAND' is omitted, `lttng help` shows general help about the
-man:lttng(1) command.
+The `help` command is equivalent to:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] ['COMMAND'] --help
-The `lttng help` command attempts to launch `/usr/bin/man` to view
-the command's man page. The path to the man pager can be overridden
-by the `LTTNG_MAN_BIN_PATH` environment variable.
+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_MAN_BIN_PATH` environment variable.
include::common-cmd-options-head.txt[]
lttng-list-triggers(1)
======================
-:revdate: 20 January 2020
+:revdate: 3 March 2021
NAME
SYNOPSIS
--------
-
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list-triggers*
DESCRIPTION
-----------
+The `lttng list-triggers` command lists the available LTTng triggers
+of your Unix user and their properties.
-The `lttng list-triggers` command list the existing triggers.
+See man:lttng-add-trigger(1) to learn more about triggers.
OPTIONS
-------
-
include::common-cmd-help-options.txt[]
-
include::common-cmd-footer.txt[]
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION'
-List tracing session's channels and event rules:
+List tracing session's channels and recording event rules:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION'
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 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.
+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.
include::common-cmd-options-head.txt[]
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 event rules, the context added to channels, the tracing activity,
-and more.
+and recording event rules, the context added to channels, the tracing
+activity, and more.
Once one or more tracing session configurations are loaded, they appear
exactly as they were saved from the user's point of view.
Base output directory: `$LTTNG_HOME/lttng-traces` or the
argument of the option:--output option.
+
-NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
+NOTE: `$LTTNG_HOME` defaults to `$HOME`.
'HOSTNAME'::
Peer's hostname.
Default base output directory of LTTng traces. This can be
overridden with the option:--output option.
-NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
+NOTE: `$LTTNG_HOME` defaults to `$HOME`.
EXIT STATUS
lttng-remove-trigger(1)
-========================
-:revdate: 20 January 2020
+=======================
+:revdate: 5 March 2021
NAME
----
-lttng-remove-trigger - Remove LTTng triggers
+lttng-remove-trigger - Remove an LTTng trigger
SYNOPSIS
--------
-
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *remove-trigger* 'ID'
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *remove-trigger* [option:--owner-id='UID'] 'NAME'
DESCRIPTION
-----------
+The `lttng remove-trigger` command removes the trigger named 'NAME'.
+
+See man:lttng-add-trigger(1) to learn more about LTTng triggers.
-The `lttng remove-trigger` command removes the trigger with the given
-'ID'.
+List the available triggers and their name 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
+user with the option:--owner-id option.
OPTIONS
-------
+Identification
+~~~~~~~~~~~~~~
+option:--owner-id='UID'::
+ Remove the trigger named 'NAME' of the Unix user having the user ID
+ 'UID'.
++
+You may only use this option if your Unix user is `root`.
+
include::common-cmd-help-options.txt[]
SEE ALSO
--------
man:lttng-add-trigger(1),
-man:lttng-list-trigger(1),
+man:lttng-list-triggers(1),
man:lttng(1)
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 event rules, the context added to channels, the tracing activity,
-and more. `lttng save` does not save tracing data, only the tracing
-session parameters.
+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.
If 'SESSION' is omitted, all the existing tracing session configurations
are saved (equivalent to using the option:--all option). Otherwise,
lttng-sessiond(8)
=================
-:revdate: 17 September 2018
+:revdate: 21 April 2021
NAME
----
-lttng-sessiond - LTTng 2 tracing session daemon
+lttng-sessiond - LTTng session daemon
SYNOPSIS
[option:--ustconsumerd64-cmd-sock='PATH']
[option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
[option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
- [option:--event-notifier-error-buffer-size-kernel='SIZE']
- [option:--event-notifier-error-buffer-size-userspace='SIZE']
- [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]
+ [option:--event-notifier-error-buffer-size-kernel='SLOTS']
+ [option:--event-notifier-error-buffer-size-userspace='SLOTS']
+ [option:--quiet | [option:--verbose]... [option:--verbose-consumer]]
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 session daemon, `lttng-sessiond`, is a program which:
-The _LTTng session daemon_ is a tracing registry which allows the user
-to interact with multiple tracers (kernel and user space) within the
-same container, a _tracing session_. Traces can be gathered from the
-Linux kernel and/or from instrumented applications (see
-man:lttng-ust(3)). You can aggregate and read the events of LTTng
-traces using man:babeltrace2(1).
+* Manages tracing sessions (see man:lttng-create(1) to learn more about
+ tracing sessions).
-To trace the Linux kernel, the session daemon needs to be running as
-`root`. LTTng uses a _tracing group_ to allow specific users to interact
-with the root session daemon. The default tracing group name is
-`tracing`. You can use the option:--group option to set the tracing
-group name to use.
+* Controls the various components (like tracers and consumer daemons) of
+ LTTng.
-Session daemons can coexist. You can have a session daemon running as
-user Alice that can be used to trace her applications alongside a root
-session daemon or a session daemon running as user Bob.
+* Sends asynchronous notifications to user applications.
-The LTTng session daemon manages trace data consumer daemons by spawning
-them when necessary. You do not need to manage the consumer daemons
-manually.
+A session daemon receives commands from the man:lttng(1) command-line
+tool, as well as from any user application linked with the LTTng control
+library (`liblttng-ctl`).
-NOTE: It is highly recommended to start the session daemon at boot time
-for stable and long-term tracing.
+Each Unix user may have its own independent running session daemon.
+However, the man:lttng(1) tool must connect to the session daemon of the
+`root` user (the root session daemon) to control Linux kernel tracing.
+When you start `lttng-sessiond` as the `root` Unix user, a non-root Unix
+user can connect to it if it's part of the Unix tracing group. By
+default, the name of the tracing group is `tracing`. Override the
+tracing group name with the option:--group option.
-Automatic loading of tracing session configurations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When the session daemon starts, it automatically loads session
-configuration files.
+See the ``Session daemon connection'' section of man:lttng(1) to learn
+how a user application connects to a session daemon.
-The following directories are searched, non-recursively, in this order
-for configuration files to load on launch:
+A session daemon manages trace data consumer daemons, spawning them when
+necessary. You do :not: need to manage the consumer daemons yourself.
-. `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`)
-. +{system_sessions_auto_dir}+
+By default, `lttng-sessiond` doesn't start as a daemon. Make it a daemon
+with the option:--daemonize or option:--background option. With those
+options, `lttng-sessiond` ensures the daemon is ready to receive client
+commands before it exits.
-Note that both the directory containing the tracing session
-configurations _and_ the session daemon binary _must_ share the same UID
-for the configurations to be automatically loaded.
+NOTE: The LTTng project recommends that you start the session daemon at
+boot time for stable and long-term tracing.
-The option:--load option overrides the default directories _and_ the UID
-check. The session daemon simply checks if the path is accessible and
-tries to load every tracing session configuration in it. When this
-option is specified, the default directories are :not: searched for
-configuration files. When the option is not specified, _both_ default
-directories are searched for configuration files.
-If the option:--load option's argument is a directory, then all the
-tracing session configurations found in all the files in this directory
-are loaded. If the argument is a file, then all the tracing session
-configurations found in this file are loaded.
+[[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).
+
+ The selected command-line option is a switch:::
+ `true`::::
+ `yes`::::
+ `on`::::
+ Enable the option.
+
+ `false`::::
+ `no`::::
+ `off`::::
+ Disable the option.
+
+INI configuration file example:
+
+[source,ini]
+----
+[sessiond]
+daemonize=yes
+extra-kmod-probes=my-driver,other-module
+----
+
+
+[[load]]
+Tracing session configuration loading
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When the session daemon starts, it loads tracing session configurations
+from:
+Without the option:--load option::
+ In this order:
++
+--
+. All the files in `$LTTNG_HOME/.lttng/sessions/auto`.
++
+`$LTTNG_HOME` defaults to `$HOME`.
+
+. All the files in +{system_sessions_auto_dir}+.
+--
++
+`lttng-sessiond` only loads tracing configuration files from the
+directories above if its UID and their UID are the same.
+With the option:--load='PATH' option::
+ 'PATH' is a directory:::
+ All the files in 'PATH'.
+
+ 'PATH' is a file:::
+ The file 'PATH'.
+
+
+[[options]]
OPTIONS
-------
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-sessiond` ensures the daemon is ready to
+receive client commands before it exits.
++
+Use the option:--daemonize option instead to close the file descriptors.
option:-f 'PATH', option:--config='PATH'::
- Load session 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-sessiond` ensures the daemon is ready to
+receive client commands before it exits.
++
+Use the option:--background option instead to keep the file descriptors
+open.
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-sessiond`.
++
+Members of the Unix tracing group may connect to the root session daemon
+and, therefore, control LTTng kernel tracing.
option:-l 'PATH', option:--load='PATH'::
- Automatically load tracing session configurations from 'PATH',
- either a directory or a file, instead of loading them from the
- default search directories.
+ Load tracing session configurations from 'PATH', either a directory
+ or a file, instead of loading them from the default search
+ directories.
++
+See the <<load,Tracing session configuration loading>> section above.
option:-S, option:--sig-parent::
- Send `SIGUSR1` to parent process to notify readiness.
+ Send the `USR1` signal to the parent process to notify readiness.
+
-NOTE: This is used by man:lttng(1) to get notified when the
-session daemon is ready to accept commands. When building a third party
-tool on liblttng-ctl, this option can be very handy to synchronize the
-control tool and the session daemon.
-
-option:--event-notifier-error-buffer-size-kernel='SIZE'::
- Set the size of the kernel event notifier error counter buffers to 'SIZE.
-
-option:--event-notifier-error-buffer-size-userspace='SIZE'::
- Set the size of the userspace event notifier error counter buffers to
- 'SIZE.
+You can also use the option:--daemonize or option:--background option,
+in which case `lttng-sessiond` ensures the daemon is ready to receive
+client commands before it exits.
Linux kernel tracing
~~~~~~~~~~~~~~~~~~~~
+At most one of:
+
option:--extra-kmod-probes='PROBE'[,'PROBE']...::
- Load specific LTTng Linux kernel modules when kernel tracing
- is enabled (option:--no-kernel option is :not: specified), in
- addition to loading the default list of LTTng kernel modules.
-+
-Only the name of the probe needs to be specified, without the
-`lttng-probe-` prefix and without the kernel module extension suffix.
-For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
-module.
+ 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.
option:--kmod-probes='PROBE'[,'PROBE']...::
- Only load specific LTTng Linux kernel modules when kernel tracing
- is enabled (option:--no-kernel option is :not: specified).
-+
-Only the name of the probe needs to be specified, without the
-`lttng-probe-` prefix and without the kernel module extension suffix.
-For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
-module.
+ 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.
option:--no-kernel::
Disable Linux kernel tracing.
Paths and ports
~~~~~~~~~~~~~~~
option:--agent-tcp-port='PORT'::
- Listen on TCP port 'PORT' for agent application registrations
- (default: a port within the range
+ Listen on TCP port 'PORT' for agent application registration
+ instead of a port within the range
[{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
option:-a 'PATH', option:--apps-sock='PATH'::
- Set application Unix socket path to 'PATH'.
+ Set the application Unix socket path to 'PATH'.
option:-c 'PATH', option:--client-sock='PATH'::
- Set client Unix socket path to 'PATH'.
+ Set the client Unix socket path to 'PATH'.
option:--consumerd32-libdir='PATH'::
- Set 32-bit consumer daemon library directory to 'PATH'.
+ Set the 32-bit consumer daemon library directory to 'PATH'.
option:--consumerd32-path='PATH'::
- Set 32-bit consumer daemon binary path to 'PATH'.
+ Set the 32-bit consumer daemon binary path to 'PATH'.
option:--consumerd64-libdir='PATH'::
- Set 64-bit consumer daemon library directory to 'PATH'.
+ Set the 64-bit consumer daemon library directory to 'PATH'.
option:--consumerd64-path='PATH'::
- Set 64-bit consumer daemon binary path to 'PATH'.
+ Set the 64-bit consumer daemon binary path to 'PATH'.
option:--kconsumerd-cmd-sock='PATH'::
- Set Linux kernel consumer daemon's command Unix socket path
+ Set the command Unix socket path of the Linux kernel consumer daemon
to 'PATH'.
option:--kconsumerd-err-sock='PATH'::
- Set Linux kernel consumer daemon's error Unix socket path
+ Set the error Unix socket path of the Linux kernel consumer daemon
to 'PATH'.
option:--ustconsumerd32-cmd-sock='PATH'::
- Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
+ Set the Unix socket path of the 32-bit consumer daemon command to
+ 'PATH'.
option:--ustconsumerd64-cmd-sock='PATH'::
- Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
+ Set the Unix socket path of the 64-bit consumer daemon command to
+ 'PATH'.
option:--ustconsumerd32-err-sock='PATH'::
- Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
+ Set the Unix socket path of the 32-bit consumer daemon error to
+ 'PATH'.
option:--ustconsumerd64-err-sock='PATH'::
- Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
+ Set the Unix socket path of the 64-bit consumer daemon error to
+ 'PATH'.
+
+
+Buffer size of event notifier error counters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+option:--event-notifier-error-buffer-size-kernel='SLOTS'::
+ Set the size of the kernel event notifier error counter buffers to
+ 'SLOTS'{nbsp}slots.
+
+option:--event-notifier-error-buffer-size-userspace='SLOTS'::
+ Set the size of the user space event notifier error counter buffers
+ to 'SLOTS'{nbsp}slots.
+
+As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
+may change in the future.
Verbosity
~~~~~~~~~
option:-q, option:--quiet::
Suppress all messages, including warnings and errors.
++
+You may :not: use this option with the option:--verbose and
+option:--verbose-consumer options.
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.
++
+You may :not: use this option with the option:--quiet option.
option:--verbose-consumer::
- Increase verbosity of consumer daemons spawned by this session
- daemon.
+ Increase the verbosity of the consumer daemons which this session
+ daemon spawns.
++
+You may :not: use this option with the option:--quiet option.
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
---------------------
-Note that command-line options override their equivalent environment
-variable.
-
`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_APP_SOCKET_TIMEOUT`::
- Application socket's timeout (seconds) when sending/receiving
- commands. After this period of time, the application is unregistered
- by the session daemon. A value of 0 or -1 means an infinite timeout.
- Default value: {default_app_socket_rw_timeout}.
+ Timeout (in seconds) of the application socket when
+ sending/receiving commands.
++
+After this period of time, `lttng-sessiond` unregisters the application.
++
+Set to `0` or `-1` to set an infinite timeout.
++
+Default: +{default_app_socket_rw_timeout}+.
`LTTNG_CONSUMERD32_BIN`::
32-bit consumer daemon binary path.
The option:--consumerd32-path option overrides this variable.
`LTTNG_CONSUMERD32_LIBDIR`::
- 32-bit consumer daemon library path.
+ 32-bit consumer daemon library directory path.
+
The option:--consumerd32-libdir option overrides this variable.
The option:--consumerd64-path option overrides this variable.
`LTTNG_CONSUMERD64_LIBDIR`::
- 64-bit consumer daemon library path.
+ 64-bit consumer daemon library directory path.
+
The option:--consumerd64-libdir option overrides this variable.
`LTTNG_DEBUG_NOCLONE`::
- Set to 1 to disable the use of `clone()`/`fork()`. Setting this
- variable is considered insecure, but it is required to allow
- debuggers to work with the session daemon on some operating systems.
+ 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.
`LTTNG_EXTRA_KMOD_PROBES`::
- Load specific LTTng Linux kernel modules when kernel tracing
- is enabled (option:--no-kernel option is :not: specified), in
- addition to loading the default list of LTTng kernel modules.
+ Extra LTTng kernel probe modules to load.
+
-The option:--extra-kmod-probes option overrides this variable.
+See the option:--extra-kmod-probes option which overrides this
+environment variable.
`LTTNG_KMOD_PROBES`::
- Only load specific LTTng Linux kernel modules when kernel tracing
- is enabled (option:--no-kernel option is :not: specified).
+ Exclusive LTTng kernel probe modules to load.
+
-The option:--kmod-probes option overrides this variable.
+See the option:--kmod-probes option which overrides this environment
+variable.
`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 use the timeout of the operating system (default).
`LTTNG_SESSION_CONFIG_XSD_PATH`::
Tracing session configuration XML schema definition (XSD) path.
FILES
-----
`$LTTNG_HOME/.lttng`::
- User LTTng runtime and configuration directory.
+ Unix user's LTTng runtime and configuration directory.
`$LTTNG_HOME/lttng-traces`::
- Default output directory of LTTng traces. This can be overridden
- with the nloption:--output option of the man:lttng-create(1)
- command.
+ Default output directory of LTTng traces in local and snapshot
+ modes.
++
+Override this path with the nloption:--output option of the
+man:lttng-create(1) command.
`$LTTNG_HOME/.lttng/sessions/auto`::
- Directory from which user tracing configuration files are
- automatically loaded when the session daemon starts (see
- man:lttng-save(1) and man:lttng-load(1) for saving
- and loading tracing sessions).
+ Directory from which `lttng-sessiond` loads Unix user tracing
+ session configurations when starting.
++
+See the <<load,Tracing session configuration loading>> section above to
+learn more.
+{system_sessions_auto_dir}+::
- Directory from which system-wide tracing configuration files are
- automatically loaded when the session daemon starts (see
- man:lttng-save(1) and man:lttng-load(1) for saving
- and loading tracing sessions).
+ Directory from which `lttng-sessiond` loads system-wide tracing
+ session configurations when starting.
++
+See the <<load,Tracing session configuration loading>> section above to
+learn more.
`$LTTNG_HOME/.lttng/lttng.conf`::
- Default location of the session daemon configuration file (see the
- option:--config option).
+ Unix user's LTTng daemon INI configuration file.
++
+See the <<cfg,Daemon configuration>> section above to learn more.
+{system_lttng_conf}+::
- System-wide location of the session daemon configuration file (see
- the option:--config option).
+ System-wide LTTng daemon INI configuration file.
++
+See the <<cfg,Daemon configuration>> section above to learn more.
-NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
+NOTE: `$LTTNG_HOME` defaults to `$HOME`.
EXIT STATUS
LIMITATIONS
-----------
-For an unprivileged 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
-is two file descriptors per CPU and one more socket for bidirectional
-communication.
+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 bumped to 65535. A future version will
-deal with this limitation.
+For the `root` user, the limit is usually 65,535.
include::common-footer.txt[]
SEE ALSO
--------
-man:lttng(1),
-man:lttng-relayd(8),
-man:lttng-crash(1),
-man:lttng-ust(3),
-man:babeltrace2(1)
+man:lttng(1)
lttng-set-session(1)
====================
-:revdate: 7 April 2016
+:revdate: 21 April 2021
NAME
DESCRIPTION
-----------
-The `lttng set-session` command sets the current tracing session.
-
-'SESSION' is the name of an existing tracing session. `lttng list`
-outputs all the existing tracing sessions (see man:lttng-list(1)).
-
-The current tracing session is used by default when a session can be
-specified in other commands. See man:lttng-create(1) for more
-information about the current tracing session.
+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)
+
+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.
include::common-cmd-options-head.txt[]
lttng-start(1)
==============
-:revdate: 7 April 2016
+:revdate: 21 April 2021
NAME
----
-lttng-start - Start LTTng tracers
+lttng-start - Start an LTTng tracing session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng start` command starts the various LTTng tracers for a
-given inactive tracing session.
+The `lttng start` command starts a tracing session, that is, it
+activates the LTTng tracers for:
-Starting the LTTng tracers has the effect that all enabled event rules
-within enabled channels can make their target event sources _emit_ trace
-events. Whether they are recorded to the local file system, sent over
-the network, or not recorded at all depends on the specific
-configuration of the tracing session in which tracing is started. See
-man:lttng-create(1) for different session modes.
+With the 'SESSION' argument::
+ The tracing session named 'SESSION'.
-A tracing session with running tracers is said to be _active_. Active
-tracing sessions can return to the inactive state using the
-man:lttng-stop(1) command.
+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).
-If 'SESSION' is omitted, the LTTng tracers are started for the current
-tracing session (see man:lttng-create(1) for more information
-about the current tracing session). Otherwise, they are started for the
-existing tracing session named 'SESSION'. `lttng list`
-outputs all the existing tracing sessions (see man:lttng-list(1)).
+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)).
+
+Stop an active tracing session with the man:lttng-stop(1) command.
include::common-cmd-options-head.txt[]
SEE ALSO
--------
-man:lttng-stop(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-add-trigger(1),
+man:lttng-create(1),
+man:lttng-enable-event(1),
+man:lttng-stop(1)
lttng-status(1)
===============
-:revdate: 14 March 2017
+:revdate: 21 April 2021
NAME
----
-lttng-status - Get the current LTTng tracing session's status
+lttng-status - Show the status of the current LTTng tracing session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng status` command shows the status of the current
-tracing session.
+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).
-This command is the exact equivalent of:
+This command is equivalent to:
-[role="term"]
-----
-$ lttng list CURSESSION
-----
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* 'CURSESSION'
where `CURSESSION` is the name of the current tracing session.
-Use man:lttng-set-session(1) to set the current tracing session.
include::common-cmd-options-head.txt[]
SEE ALSO
--------
-man:lttng-set-session(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-create(1),
+man:lttng-list(1),
+man:lttng-set-session(1)
lttng-stop(1)
=============
-:revdate: 18 January 2018
+:revdate: 21 April 2021
NAME
----
-lttng-stop - Stop LTTng tracers
+lttng-stop - Stop an LTTng tracing session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng stop` command stops the various LTTng tracers for a given
-active tracing session.
-
-Stopping the LTTng tracers has the effect that all enabled event rules
-within enabled channels cannot make event sources _emit_ trace events
-anymore.
-
-A tracing session with no running tracers is said to be _inactive_.
-Inactive tracing sessions can be set active using the
-man:lttng-start(1) command.
-
-If 'SESSION' is omitted, the LTTng tracers are stopped for the current
-tracing session (see man:lttng-create(1) for more information
-about the current tracing session). Otherwise, they are stopped for the
-existing tracing session named 'SESSION'. `lttng list`
-outputs all the existing tracing sessions (see man:lttng-list(1)).
-
-By default, the `lttng stop` command ensures that the tracing session's
-trace data is valid before returning to the prompt. With the
-option:--no-wait option, the command finishes immediately, hence a local
-trace might not be valid when the command is done. In this case, there
-is no way to know when the trace becomes valid.
-
-If at least one rotation occurred during the chosen tracing session's
-lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), the
-`lttng stop` command renames the current trace chunk subdirectory and
-prints the renamed path. Although it is safe to read the content of this
-renamed subdirectory while the tracing session remains inactive (until
-the next man:lttng-start(1)), it is :not: a trace chunk archive: you
-need to destroy the tracing session with man:lttng-destroy(1) or make
-a rotation with man:lttng-rotate(1) to archive it.
+The `lttng stop` command stops a tracing session, that is, it
+deactivates the LTTng tracers for:
+
+With the 'SESSION' argument::
+ 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 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)).
+
+Start an inactive tracing session with the man:lttng-start(1) command.
+
+By default, the `stop` command ensures that the trace data of the
+selected tracing session is valid before it exits. Make the command exit
+immediately with the option:--no-wait option. In this case, however, the
+traces(s) might not be valid when the command exits, and there's no way
+to know when it/they becomes valid.
+
+If LTTng archived the current trace chunk (see man:lttng-rotate(1) and
+man:lttng-enable-rotation(1)) of the selected tracing session at least
+once during its lifetime, the `stop` command renames the current trace
+chunk subdirectory and prints the renamed path. Although it's safe to
+read the content of this renamed subdirectory while the tracing session
+remains inactive, it's :not: a trace chunk archive: you need to destroy
+the tracing session with man:lttng-destroy(1) or perform a rotation with
+man:lttng-rotate(1) to archive it.
include::common-cmd-options-head.txt[]
option:-n, option:--no-wait::
- Do not ensure that the chosen tracing session's trace data is valid
- before returning to the prompt.
+ Do :not: ensure that the trace data of the selected tracing session
+ is valid before exiting.
include::common-cmd-help-options.txt[]
SEE ALSO
--------
-man:lttng-start(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-add-trigger(1),
+man:lttng-create(1),
+man:lttng-enable-event(1),
+man:lttng-rotate(1),
+man:lttng-start(1)
The `lttng track` commands adds one or more values to a
process attribute tracker.
-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 event rules (see
+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)).
Tracker values can be removed from an inclusion set with
lttng-version(1)
================
-:revdate: 1 May 2018
+:revdate: 21 April 2021
NAME
DESCRIPTION
-----------
-The `lttng version` command outputs the version of LTTng-tools.
+The `lttng version` command shows the version of LTTng-tools, the LTTng
+project which provides the man:lttng(1) command and other tracing
+control programs and libraries.
-The output of `lttng version` is broken down into the following parts:
+The output of the `version` command shows:
-* Major, minor, and patch numbers
-* Git commit information, if available
-* Release name with its description
-* LTTng project's website URL
-* License information
+* The major, minor, and patch version numbers.
+* The Git commit information, if available.
+* The release name and its description.
+* The URL of the LTTng project website.
+* The license information.
include::common-cmd-options-head.txt[]
lttng-view(1)
=============
-:revdate: 28 November 2016
+:revdate: 21 April 2021
NAME
----
-lttng-view - View the traces of an LTTng tracing session
+lttng-view - Launch an LTTng trace reader
SYNOPSIS
--------
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *view* [option:--viewer='CMD'] [option:--trace-path='PATH' | 'SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *view* [option:--viewer='READER']
+ ['SESSION' | option:--trace-path='DIR']
DESCRIPTION
-----------
-The `lttng view` command launches an external trace viewer to view the
-current trace of a tracing session.
+The `lttng view` command launches an external trace reader to read the
+current traces of:
-If 'SESSION' is omitted, the viewer is launched for the current tracing
-session (see man:lttng-create(1) for more information
-about the current tracing session). Otherwise, it is launched for the
-existing tracing session named 'SESSION'. `lttng list`
-outputs all the existing tracing sessions (see man:lttng-list(1)).
+With the option:--session='SESSION' option::
+ The tracing session named 'SESSION'.
-By default, the man:babeltrace2(1) trace viewer is launched. If it is
-not found on the system, the man:babeltrace(1) trace viewer is
-used.
-Another trace viewer command can be specified using the
-option:--viewer option.
+With the option:--trace-path='DIR' option::
+ The local file system directory 'DIR'.
-By default, the trace path of the chosen tracing session is given
-as the first positional argument to the trace viewer. This path can
-be overridden using the option:--trace-path option.
+Otherwise::
+ 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 option or without the option:--trace-path
+option, the mode of the selected tracing session may :not: be network
+streaming or live.
+
+By default, the `view` command attempts to launch man:babeltrace2(1) or,
+if it's not available, man:babeltrace(1). Override which trace reader to
+launch with the option:--viewer option.
include::common-cmd-options-head.txt[]
-option:-t 'PATH', option:--trace-path='PATH'::
- View trace at path 'PATH' instead of using the chosen tracing
- session's trace path.
+option:-t 'DIR', option:--trace-path='DIR'::
+ Pass 'DIR' as the last argument of the trace reader command instead
+ of the output directory of the selected tracing session.
-option:-e 'CMD', option:--viewer='CMD'::
- Use 'CMD' as the trace viewer.
+option:-e 'READER', option:--viewer='READER'::
+ Use the trace reader 'READER' to read the traces.
++
+'READER' is the absolute path to the reader command to use, and it can
+contain command arguments as well. The `view` command passes the trace
+directory path to read to the 'READER' command as its last argument.
++
+Without this option, the `view` command uses man:babeltrace2(1) if it's
+available. Otherwise, it tries to use man:babeltrace(1).
include::common-cmd-help-options.txt[]
SEE ALSO
--------
+man:babeltrace2(1),
man:lttng(1)
SYNOPSIS
--------
[verse]
-*lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH']
- [option:--quiet | option:-v | option:-vv | option:-vvv] '<<commands,COMMAND>>' ['COMMAND OPTIONS']
+*lttng* [option:--group='GROUP'] [option:--mi=xml] [option:--no-sessiond | option:--sessiond-path='PATH']
+ [option:--quiet | option:-verbose...] '<<commands,COMMAND>>' ['COMMAND OPTIONS']
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).
+The `lttng` command-line tool, as well as any user application linked
+with the LTTng control library (`liblttng-ctl`), sends commands to a
+listening LTTng session daemon (man:lttng-sessiond(8)). A session
+daemon:
-An LTTng _session daemon_, man:lttng-sessiond(8), receives
-commands from the command-line interface `lttng` to control the LTTng
-tracers. All interactions with the LTTng tracers happen through the
-`lttng` tool or through the liblttng-ctl library shipped with the
-LTTng-tools package.
+* Manages tracing sessions (see man:lttng-create(1) to learn more
+ about tracing sessions).
-A _tracing domain_ is a tracer category. There are five available
-domains. For some commands, the domain needs to be specified with a
-command-line option. The domain options are:
+* Controls the various components (like tracers and consumer daemons) of
+ LTTng.
-nloption:-j, nloption:--jul::
- Apply command to the `java.util.logging` (JUL) domain.
+* Sends asynchronous notifications to user applications.
-nloption:-k, nloption:--kernel::
- Apply command to the Linux kernel domain.
+By default, the man:lttng-create(1) command automatically spawns a
+session daemon for your Unix user if none is currently running. Override
+the path of the session daemon binary to spawn with the
+option:--sessiond-path option. Avoid automatically spawning a session
+daemon with the option:--no-sessiond option.
-nloption:-l, nloption:--log4j::
- Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2]
- (Java) domain.
+NOTE: The LTTng project recommends that you start the session daemon at
+boot time for stable and long-term tracing.
-nloption:-p, nloption:--python::
- Apply command to the https://www.python.org/[Python] domain.
-nloption:-u, nloption:--userspace::
- Apply command to the user space domain (application using
- liblttng-ust directly; see man:lttng-ust(3)).
+Session daemon connection
+~~~~~~~~~~~~~~~~~~~~~~~~~
+For most of its commands, the `lttng` tool needs to connect to a
+listening LTTng session daemon (man:lttng-sessiond(8)) to control LTTng
+tracing.
-The LTTng session daemon is a tracing registry which allows the user to
-interact with multiple tracers (kernel and user space) within the same
-container, a _tracing session_. Traces can be gathered from the Linux
-kernel and/or from instrumented applications (see
-man:lttng-ust(3)). You can aggregate and read the events of LTTng
-traces using man:babeltrace2(1).
+Each Unix user may have its own independent running session daemon.
+However, the `lttng` tool must connect to the session daemon of the
+`root` user (the root session daemon) to control Linux kernel tracing.
-To trace the Linux kernel, the session daemon needs to be running as
-`root`. LTTng uses a _tracing group_ to allow specific users to interact
-with the root session daemon. The default tracing group name is
-`tracing`. You can use the option:--group option to set the tracing
-group name to use.
+How the `lttng` tool chooses which session daemon to connect to
+is as follows:
-Session daemons can coexist. You can have a session daemon running as
-user Alice that can be used to trace her applications alongside a root
-session daemon or a session daemon running as user Bob.
+If your Unix user is `root`::
+ Connect to the root session daemon.
-NOTE: It is highly recommended to start the session daemon at boot time
-for stable and long-term tracing.
+If your Unix user is not `root`::
+ If your Unix user is part of the Unix tracing group:::
+ Try to connect to the root session daemon.
++
+If the root session daemon isn't running, connect to the session daemon
+of your Unix user.
-User applications instrumented with LTTng automatically register to the
-root session daemon and to user session daemons. This allows any session
-daemon to list the available traceable applications and event sources
-(see man:lttng-list(1)).
+ If your Unix user is not part of the tracing group:::
+ Connect to the session daemon of your Unix user.
-By default, the man:lttng-create(1) command automatically spawns a
-user session daemon if none is currently running. The
-option:--no-sessiond general option can be set to avoid this.
+The name of the Unix tracing group is one of:
+
+With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8))::
+ 'GROUP'
++
+In that case, you must use the option:--group='GROUP' option, with
+the same 'GROUP' argument, of the `lttng` tool.
+
+Without the nloption:--group option of the root session daemon::
+ `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)).
OPTIONS
-------
option:-g 'GROUP', option:--group='GROUP'::
- Use 'GROUP' as Unix tracing group (default: `tracing`).
-
-option:-m 'TYPE', option:--mi='TYPE'::
- Print the command's result using the machine interface type 'TYPE'
- instead of a human-readable output.
+ Set the name of the Unix tracing group to 'GROUP' instead of
+ `tracing`.
+
-Supported types: `xml`.
-+
-The machine interface (MI) mode converts the traditional pretty-printing
-to a machine output syntax. The MI mode provides a change-resistant way
-to access information generated by the `lttng` command-line program.
+You must use this option to be able to connect to a root session daemon
+(man:lttng-sessiond(8)) which was started with its own
+nloption:--group='GROUP' option.
+
+option:-m `xml`, option:--mi=++xml++::
+ Print the command's result using a stable XML machine interface (MI)
+ output instead of the default, unstable human-readable output.
+
-When using the MI mode, the data is printed to the standard output.
-Errors and warnings are printed on the standard error with the
-pretty-print default format.
+With this mode, `lttng` prints the resulting XML document to the
+standard output, while it prints any error/warning to the standard error
+with an unstable, human-readable format.
+
-If any error occurs during the execution of a command, the return value
-of the command will be different than 0. In this case, `lttng` does
-:not: guarantee the syntax and data validity of the generated MI output.
+If any error occurs during the execution of `lttng`, the command
+exits with a status different than{nbsp}0, and `lttng` does
+:not: guarantee the syntax and data validity of its MI output.
+
-For the `xml` MI type, an XML schema definition (XSD) file used for
-validation is available: see the `src/common/mi_lttng.xsd` file in
-the LTTng-tools source tree.
+An XML schema definition (XSD) file used for validation of the MI output
+is available: see the `src/common/mi_lttng.xsd` file in the LTTng-tools
+source tree.
option:-n, option:--no-sessiond::
- Do not automatically spawn a session daemon.
+ Do not automatically spawn a session daemon for your Unix user when
+ running the man:lttng-create(1) command.
++
+You may :not: use this option with the option:--sessiond-path option.
option:-q, option:--quiet::
Suppress all messages, including warnings and errors.
++
+You may :not: use this option with the option:--verbose option.
option:--sessiond-path='PATH'::
- Set the session daemon binary's absolute path to 'PATH'.
+ Set the absolute path of the session daemon binary to spawn from the
+ man:lttng-create(1) command to 'PATH'.
++
+You may :not: use this option with the option:--no-sessiond option.
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.
++
+You may :not: use this option with the option:--quiet option.
Program information
~~~~~~~~~~~~~~~~~~~
-option:-h, option:--help::
- Show help.
+include::common-help-option.txt[]
option:--list-commands::
- List available commands.
-
-option:--list-options::
- List available general options.
+ List available commands and quit.
option:-V, option:--version::
- Show version.
+ Show version and quit.
[[commands]]
The following commands also have their own nloption:--help option.
-Tracing sessions
-~~~~~~~~~~~~~~~~
-man:lttng-create(1)::
- {cmd_descr_create}.
-
-man:lttng-destroy(1)::
- {cmd_descr_destroy}.
-
-man:lttng-load(1)::
- {cmd_descr_load}.
-
-man:lttng-regenerate(1)::
- {cmd_descr_regenerate}.
-
-man:lttng-save(1)::
- {cmd_descr_save}.
-
-man:lttng-set-session(1)::
- {cmd_descr_set_session}.
-
-
-Channels
-~~~~~~~~
-man:lttng-add-context(1)::
- {cmd_descr_add_context}.
-
-man:lttng-disable-channel(1)::
- {cmd_descr_disable_channel}.
-
-man:lttng-enable-channel(1)::
- {cmd_descr_enable_channel}.
-
-
-Event rules
-~~~~~~~~~~~
-man:lttng-disable-event(1)::
- {cmd_descr_disable_event}.
-
-man:lttng-enable-event(1)::
- {cmd_descr_enable_event}.
-
-
-Status
-~~~~~~
-man:lttng-list(1)::
- {cmd_descr_list}.
-
-man:lttng-status(1)::
- {cmd_descr_status}.
-
-
-Control
+Tracing session
+~~~~~~~~~~~~~~~
+[options="header"]
+|===
+|Command |Description
+
+|man:lttng-create(1) |{cmd_descr_create}.
+|man:lttng-destroy(1) |{cmd_descr_destroy}.
+|man:lttng-disable-rotation(1) |{cmd_descr_disable_rotation}.
+|man:lttng-enable-rotation(1) |{cmd_descr_enable_rotation}.
+|man:lttng-load(1) |{cmd_descr_load}.
+|man:lttng-regenerate(1) |{cmd_descr_regenerate}.
+|man:lttng-rotate(1) |{cmd_descr_rotate}.
+|man:lttng-save(1) |{cmd_descr_save}.
+|man:lttng-set-session(1) |{cmd_descr_set_session}.
+|man:lttng-snapshot(1) |{cmd_descr_snapshot}.
+|man:lttng-start(1) |{cmd_descr_start}.
+|man:lttng-status(1) |{cmd_descr_status}.
+|man:lttng-stop(1) |{cmd_descr_stop}.
+|===
+
+
+Channel
~~~~~~~
-man:lttng-snapshot(1)::
- {cmd_descr_snapshot}.
-
-man:lttng-start(1)::
- {cmd_descr_start}.
-
-man:lttng-stop(1)::
- {cmd_descr_stop}.
+[options="header"]
+|===
+|Command |Description
+|man:lttng-add-context(1) |{cmd_descr_add_context}.
+|man:lttng-disable-channel(1) |{cmd_descr_disable_channel}.
+|man:lttng-enable-channel(1) |{cmd_descr_enable_channel}.
+|===
-Tracing session rotation
-~~~~~~~~~~~~~~~~~~~~~~~~
-man:lttng-disable-rotation(1)::
- {cmd_descr_disable_rotation}.
-man:lttng-enable-rotation(1)::
- {cmd_descr_enable_rotation}.
+Recording event rule
+~~~~~~~~~~~~~~~~~~~~
+[options="header"]
+|===
+|Command |Description
-man:lttng-rotate(1)::
- {cmd_descr_rotate}.
+|man:lttng-disable-event(1) |{cmd_descr_disable_event}.
+|man:lttng-enable-event(1) |{cmd_descr_enable_event}.
+|===
+Information
+~~~~~~~~~~~
+[options="header"]
+|===
+|Command |Description
+|man:lttng-list(1) |{cmd_descr_list}.
+|===
Resource tracking
~~~~~~~~~~~~~~~~~
-man:lttng-track(1)::
- {cmd_descr_track}.
+[options="header"]
+|===
+|Command |Description
+
+|man:lttng-track(1) |{cmd_descr_track}.
+|man:lttng-untrack(1) |{cmd_descr_untrack}.
+|===
-man:lttng-untrack(1)::
- {cmd_descr_untrack}.
+Trigger
+~~~~~~~
+[options="header"]
+|===
+|Command |Description
+|man:lttng-add-trigger(1) |{cmd_descr_add_trigger}.
+|man:lttng-list-triggers(1) |{cmd_descr_list_triggers}.
+|man:lttng-remove-trigger(1) |{cmd_descr_remove_trigger}.
+|===
Miscellaneous
~~~~~~~~~~~~~
-man:lttng-help(1)::
- {cmd_descr_help}.
-
-man:lttng-version(1)::
- {cmd_descr_version}.
+[options="header"]
+|===
+|Command |Description
-man:lttng-view(1)::
- {cmd_descr_view}.
+|man:lttng-help(1) |{cmd_descr_help}.
+|man:lttng-version(1) |{cmd_descr_version}.
+|man:lttng-view(1) |{cmd_descr_view}.
+|===
include::common-cmd-footer.txt[]
SEE ALSO
--------
-man:lttng-sessiond(8),
+man:babeltrace2(1),
man:lttng-relayd(8),
-man:lttng-crash(1),
-man:lttng-ust(3),
-man:babeltrace2(1)
+man:lttng-sessiond(8)
}
} else {
/* Pretty print */
- MSG("\n%sEvent rules:", indent4);
+ MSG("\n%sRecording event rules:", indent4);
if (count == 0) {
MSG("%sNone\n", indent6);
goto end;
puts(" disable-channel " CONFIG_CMD_DESCR_DISABLE_CHANNEL);
puts(" enable-channel " CONFIG_CMD_DESCR_ENABLE_CHANNEL);
puts("");
- puts("Event rules:");
+ puts("Recording event rules:");
puts(" disable-event " CONFIG_CMD_DESCR_DISABLE_EVENT);
puts(" enable-event " CONFIG_CMD_DESCR_ENABLE_EVENT);
puts("");
puts(" track " CONFIG_CMD_DESCR_TRACK);
puts(" untrack " CONFIG_CMD_DESCR_UNTRACK);
puts("");
+ puts("Triggers:");
+ puts(" add-trigger " CONFIG_CMD_DESCR_ADD_TRIGGER);
+ puts(" remove-trigger " CONFIG_CMD_DESCR_REMOVE_TRIGGER);
+ puts(" list-triggers " CONFIG_CMD_DESCR_LIST_TRIGGERS);
+ puts("");
puts("Miscellaneous:");
puts(" help " CONFIG_CMD_DESCR_HELP);
puts(" version " CONFIG_CMD_DESCR_VERSION);
projects / lttng-tools.git / commitdiff
