lttng-add-trigger — Add an LTTng trigger
lttng [GENERAL OPTIONS] add-trigger [--name=NAME] [--owner-uid=UID]--condition=CONDTYPE[CONDARGS]--action=ACTTYPE[ACTARGS] [--action=ACTTYPE[ACTARGS]]…
The lttng add-trigger command creates and adds an LTTng trigger to
the connected session daemon (see lttng-sessiond(8)).
See lttng-concepts(7) to learn more about LTTng triggers.
By default, the add-trigger command automatically assigns a name,
unique for a given session daemon and Unix user, to the added trigger.
Assign a custom name with the --name.
The add-trigger command adds a trigger for your Unix user. If your
Unix user is root, you may add the trigger as another user with the
--owner-uid option.
Specify the condition of the trigger to add with a condition specifier and its actions with one or more action specifiers. The order of the action specifiers is significant: LTTng attempts to execute the actions of a firing trigger in this order.
See the “EXAMPLES” section below for usage examples.
List the triggers of your Unix user, or of all users if your
Unix user is root, with the lttng-list-triggers(1) command.
Remove a trigger with the lttng-remove-trigger(1) command.
Synopsis:
--condition=CONDTYPE[CONDARGS]
A condition specifier is the --condition option, which specifies
the type of condition CONDTYPE, followed, depending on CONDTYPE,
with zero or more arguments CONDARGS.
The available condition types are:
channel-buffer-usage-ge
channel-buffer-usage-le
Synopses:
--condition=channel-buffer-usage-ge--session=SESSION--channel=CHANNEL--domain=(kernel|user|jul|log4j|log4j2|python) (--threshold-ratio=RATIO|--threshold-size=SIZE)--condition=channel-buffer-usage-le--session=SESSION--channel=CHANNEL--domain=(kernel|user|jul|log4j|log4j2|python) (--threshold-ratio=RATIO|--threshold-size=SIZE)
A channel-buffer-usage-ge or channel-buffer-usage-le condition is
considered satisfied when the ring buffer usage of the event record
channel CHANNEL (within the recording session SESSION and the
tracing domain specified by --domain) becomes greater/less than
or equal to either:
--threshold-size=SIZE option
SIZE bytes.
SIZE supports the k (KiB), M (MiB), and
G (GiB) suffixes.
--threshold-ratio=RATIO option
RATIO times the total size of the ring buffer
of the targeted event record channel.
RATIO is a floating point number from 0 to 1.
Every time the monitor timer (see the --monitor-timer option of
lttng-enable-channel(1)) of an event record channel expires, LTTng
updates its statistics, including its buffer usage. This is when LTTng
tries to evaluate channel-buffer-usage-ge and
channel-buffer-usage-le conditions.
The short options -c, -d, -s, and -t
are aliases of --channel, --domain,
--session, and --threshold-size.
event-rule-matches
Synopsis:
--condition=event-rule-matches [--capture=CDESCR]…ERSPEC
An event-rule-matches condition is considered satisfied when the event
rule specified with ERSPEC matches an event.
See lttng-event-rule(7) to learn how to specify an event rule
(ERSPEC part), including its instrumentation point type
(--type), event name (--name), instrumentation
point log level (--log-level), and event payload/context
filter (--filter) conditions.
Capture event record and context fields with one or more
--capture options (see the “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 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.
session-consumed-size-ge
Synopsis:
--condition=session-consumed-size-ge--session=SESSION--threshold-size=THRESHOLD
A session-consumed-size-ge condition is considered satisfied when the
total consumed size of the tracing data of all the event record channels
of the recording session SESSION becomes greater than or equal to
THRESHOLD bytes.
Every time the monitor timer (see the --monitor-timer option of
lttng-enable-channel(1)) of an event record channel expires, LTTng
updates the statistics, like the total consumed tracing data size, of
its owning recording session. This is when LTTng tries to evaluate
session-consumed-size-ge conditions.
THRESHOLD supports the k (KiB), M (MiB), and
G (GiB) suffixes.
The short options -s and -t are aliases of
--session and --threshold-size.
session-rotation-starts
session-rotation-finishes
Synopses:
--condition=session-rotation-starts--session=SESSION--condition=session-rotation-finishes--session=SESSION
A session-rotation-starts or session-rotation-finishes condition is
considered satisfied when the rotation operation (see
lttng-rotate(1)) of the recording session SESSION starts or
finishes.
The short option -s is an alias of --session.
A capture descriptor is a textual expression which describes how to read an event record or context field.
The argument of a --capture option, when using an
“event rule matches” condition specifier
(event-rule-matches), is a capture descriptor.
A capture descriptor expression is one of:
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.
$ctx.NAME
A statically-known context field named NAME.
List the available statically-known context field names with
lttng-add-context(1). As of LTTng 2.16,
context field names starting with perf: aren’t supported.
Examples: $ctx.prio, $ctx.gid, $ctx.preemptible.
$app.PROVIDER.NAME
An application-specific context field named NAME from the
provider PROVIDER.
See lttng-add-context(1) to learn more about application-specific context fields.
Example: $app.server:cur_user.
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].
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.
Synopsis:
--action=ACTTYPE[ACTARGS]
An action specifier is the --action option, which specifies
the type of action ACTTYPE, followed, depending on ACTTYPE, with zero
or more arguments ACTARGS.
The available action types are:
Synopsis:
--action=incr-map-value--session=SESSION--channel=CHANNEL--type=(kernel|user)--key=TEMPLATE
Increments a counter within the map channel named CHANNEL (see
lttng-add-map-channel(1)) with the type of --type
within the recording session named SESSION.
The effective key of the counter to increment is the result of
expanding TEMPLATE. Within TEMPLATE, LTTng substitutes the following
placeholders:
{event_name}
The effective name of the event which made the trigger fire (see the “Event name condition” section of lttng-event-rule(7)).
For example, canadian_tire:money_redeemed (user space tracepoint),
sched_switch (Linux kernel tracepoint), openat (Linux kernel
system call), or ca.provigo.checkout.ScannerLogger
(Java or Python logger name).
{provider_name}
The name of the LTTng tracepoint provider of the event which made the trigger fire.
For example, canadian_tire
(user space tracepoint canadian_tire:money_redeemed) or sched
(Linux kernel tracepoint sched_switch).
Any other text in TEMPLATE is used as is. To include a literal {
or } character in the resulting key, use in TEMPLATE
(similar to {fmt} and Python’s f-string syntax).
You may only use the {event_name} and {provider_name} placeholders
when the condition of the trigger is an
“event rule matches” condition
(event-rule-matches). With any other condition, TEMPLATE must be
literal text.
Moreover, you may not use the {event_name} or {provider_name}
placeholders when the event rule of the “event rule matches” condition
has the jul:logging, log4j:logging, log4j2:logging, or
python:logging instrumentation point type (see the --type
option of lttng-event-rule(7)): TEMPLATE must be literal text in
that case.
When the condition of the trigger isn’t an
“event rule matches” condition
(event-rule-matches), --type must be user: LTTng increments
a counter within the shared user space map, as there’s no kernel
instrumentation point executor in that case.
The map channel named CHANNEL within the recording session named
SESSION must exist when LTTng is ready to execute the action;
otherwise, LTTng does nothing.
LTTng only increments the counter when the recording session named
SESSION is active (started; see lttng-start(1)). While the
recording session is inactive (stopped; see lttng-stop(1)), the
action does nothing.
The update policy of CHANNEL (see the --update-policy
option of lttng-add-map-channel(1)) controls how LTTng increments
counters when multiple “increment map value” actions which target
SESSION and CHANNEL produce the same effective key (for example,
multiple “event rule matches” triggers matching the same event).
Unlike the other action types, the incr-map-value action doesn’t
support the --rate-policy option: its effective rate policy
is every:1.
Unlike the other action types, an incr-map-value action may
execute out of order: when the action list of the trigger contains at
least one incr-map-value action, LTTng doesn’t guarantee the execution
order of the incr-map-value action(s) relative to all the actions of
the list, including other incr-map-value actions. In other words,
the significant action specifier order (see above) only holds amongst
the non-``incr-map-value`` actions.
The short options -s, -c, -t, and
-k are aliases of --session, --channel,
--type, and --key.
Synopsis:
--action=notify [--rate-policy=POLICY]
Sends a notification through the notification mechanism of the session daemon (see lttng-sessiond(8)).
The session daemon sends details about the condition evaluation along with the notification.
As of LTTng 2.16, you can write a C/C++ program to receive LTTng notifications (see the liblttng-ctl C headers).
See below for the --rate-policy option.
Synopsis:
--action=start-sessionSESSION[--rate-policy=POLICY]
Starts the recording session named SESSION like lttng-start(1)
would.
If no recording session has the name SESSION when LTTng is ready to
execute the action, LTTng does nothing.
See below for the --rate-policy option.
Synopsis:
--action=stop-sessionSESSION[--rate-policy=POLICY]
Stops the recording session named SESSION like lttng-stop(1)
would.
If no recording session has the name SESSION when LTTng is ready to
execute the action, LTTng does nothing.
See below for the --rate-policy option.
Synopsis:
--action=rotate-sessionSESSION[--rate-policy=POLICY]
Archives the current trace chunk of the recording session named
SESSION like lttng-rotate(1) would.
If no recording session has the name SESSION when LTTng is ready to
execute the action, LTTng does nothing.
See below for the --rate-policy option.
Synopsis:
--action=snapshot-sessionSESSION[--name=NAME] [--max-size=SIZE] [--path=PATH|--url=URL| (--ctrl-url=URL--data-url=URL)] [--rate-policy=POLICY]
Takes a snapshot of the recording session named SESSION like
lttng-snapshot(1) would.
When the condition of the trigger is satisfied, the recording session
named SESSION, if any, must be a snapshot-mode recording session
(see lttng-create(1)).
If no recording session has the name SESSION when LTTng is ready to
execute the action, LTTng does nothing.
See the add-output action of the lttng-snapshot(1) command
to learn about the snapshot output options:
--name/-n,
--max-size/-m,
--url,
--ctrl-url/-C, and
--data-url/-D. The --path option specifies
to write the snapshot to the local directory PATH.
See below for the --rate-policy option.
Common action options (as of LTTng 2.16):
--rate-policy=POLICY
Set the rate policy of the action to POLICY instead of
every:1 (always execute).
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 A first increments the execution
request count C of A. An execution request can then
become an actual execution when C satisfies the rate policy
of A.
POLICY is one of:
once-after:COUNT
Only execute A when C is equal to COUNT.
In other words, execute A a single time after COUNT execution
requests.
every:COUNT
Only execute A when C is a multiple of COUNT.
In other words, execute A every COUNT execution requests.
COUNT must be an integer greater than 0.
As of LTTng 2.16, every action type except
incr-map-value supports this option, but new action types in the
future may also not support it.
--name=NAME
Set the unique name of the trigger to add to NAME instead of the
add-trigger command automatically assigning one.
--owner-uid=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.
--condition=CONDTYPE
Introductory option for a condition specifier of type CONDTYPE.
See the “Condition specifier” section above to learn more.
--action=ACTTYPE
Introductory option for an action specifier of type ACTTYPE.
See the “Action specifier” section above to learn more.
-h, --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.
--list-options
List available command options and quit.
Success
Command error
Undefined command
Fatal error
Command warning (something went wrong during the command)
LTTNG_ABORT_ON_ERROR
Set to 1 to abort the process after the first error is
encountered.
LTTNG_HOME
Path to the LTTng home directory.
Defaults to $HOME.
Useful when the Unix user running the commands has a non-writable home directory.
LTTNG_LIST_LEGACY
Set to 1 to use the legacy output format (LTTng 2.14 and
earlier) for the lttng-list(1) command instead of the modern
output format.
Note that the legacy output doesn’t show anything related to features introduced after LTTng 2.14.
LTTNG_MAN_BIN_PATH
Absolute path to the manual pager to use to read the LTTng
command-line help (with lttng-help(1) or with the
--help option) instead of /usr/bin/man.
LTTNG_NO_UTF_8
Set to 1 to not emit multi-byte UTF-8 sequences, even if the
locale claims to support it.
LTTNG_SESSION_CONFIG_XSD_PATH
Path to the directory containing the session.xsd recording session
configuration XML schema.
LTTNG_SESSIOND_PATH
Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from the lttng-create(1) command.
The --sessiond-path general option overrides this environment
variable.
LTTNG_TERM_COLOR
Controls when to emit terminal SGR codes in the output.
The NO_COLOR environment variable overrides this.
One of:
auto (default)
Only emit SGR codes when the standard output is connected to a color-capable terminal.
always
Always emit SGR codes.
never
Never emit SGR codes.
NO_COLOR
If set and not empty, then it’s equivalent to setting
LTTNG_TERM_COLOR to never.
See NO_COLOR to learn more.
$LTTNG_HOME/.lttngrc
Unix user’s LTTng runtime configuration.
This is where LTTng stores the name of the Unix user’s current recording session between executions of lttng(1). lttng-create(1) and lttng-set-session(1) set the current recording session.
$LTTNG_HOME/lttng-traces
Default output directory of LTTng traces in local and snapshot modes.
Override this path with the --output option of the
lttng-create(1) command.
$LTTNG_HOME/.lttng
Unix user’s LTTng runtime and configuration directory.
$LTTNG_HOME/.lttng/sessions
Default directory containing the Unix user’s saved recording session configurations (see lttng-save(1) and lttng-load(1)).
/etc/lttng/sessions
Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).
Note:$LTTNG_HOME defaults to the value of the HOME environment
variable.
Example:Add an “event rule matches” trigger of which the action is to send a notification.
The event-rule-matches trigger condition below specifies an event rule
which matches any Linux system call entry event with a name starting
with exec.
$
lttng add-trigger --condition=event-rule-matches \
--type=syscall:entry \
--name='exec*' --action=notifyExample:Add an “event rule matches” trigger of which the action is to stop a recording session and then rotate it.
The event-rule-matches trigger condition below specifies an event rule
which matches any user space tracepoint event with a name starting with
my_app: and with a log level at least as severe as a warning.
The order of the --action options below is significant.
$
lttng add-trigger --condition=event-rule-matches \
--type=user --name='my_app:*' \
--log-level=TRACE_WARNING.. \
--action=stop-session my-session \
--action=rotate-session my-sessionSee lttng-concepts(7) to learn more about recording sessions and rotations.
Example:Add an “event rule matches” trigger with a specific name.
The event-rule-matches trigger condition below specifies an event rule
which matches events which LTTng creates from the my-logger Python
logger.
The added trigger is named my-trigger, a unique name for your Unix
user.
See the --name option.
$
lttng add-trigger --name=my-trigger \
--condition=event-rule-matches \
--type=python --name=my-logger \
--action=snapshot-session my-sessionExample:Add an “event rule matches” trigger as another Unix user.
The command line below adds a trigger as the mireille Unix user.
Your Unix user must be root to use the --owner-uid option.
The condition of the trigger specifies an event rule which matches LTTng
kernel tracepoint events with a name which starts with sched.
#
lttng add-trigger --owner-uid=$(id --user mireille) \
--condition=event-rule-matches \
--type=kernel --name='sched*' \
--action=notifyExample:Add an “event rule matches” trigger with a notification action to be executed every 10 times.
The event-rule-matches trigger condition below specifies an event rule
which matches all user space tracepoint events.
See the --rate-policy option above.
$
lttng add-trigger --condition=event-rule-matches \
--type=user --action=notify \
--rate-policy=every:10Example:Add an “event rule matches” trigger with a recording session starting action to be executed a single time after 40 times.
The event-rule-matches trigger condition below specifies an event rule
which matches any Linux system call event (entry and exit) of which the
fd event record field is less than 3.
See the --rate-policy option above.
$
lttng add-trigger --condition=event-rule-matches \
--type=syscall --filter='fd < 3' \
--action=start-session my-session \
--rate-policy=once-after:40Example:Add an “event rule matches” trigger of which the action is to increment a counter.
The event-rule-matches trigger condition below specifies an event rule
which matches all user space tracepoint events.
The incr-map-value action increments, for each matching event, a
counter of the map channel named my-counters within the recording
session named my-session, using the name of the event as the
key suffix.
See lttng-add-map-channel(1) to learn how to add a map channel.
$
lttng add-trigger --condition=event-rule-matches --type=user \
--action=incr-map-value --type=user \
--session=my-session --channel=my-counters \
--key='count_a_{event_name}'Example:Add a “recording session consumed data size becomes greater than” trigger of which the action is to rotate the recording session.
The session-consumed-size-ge trigger condition below is considered
satisfied when the total consumed size of the recording session named
my-session becomes greater than or equal to 100 MiB.
$
lttng add-trigger --condition=session-consumed-size-ge \
--session=my-session --threshold-size=100M \
--action=rotate-session my-sessionSee lttng-concepts(7) to learn more about recording sessions and rotations.
Example:Add a “channel buffer usage becomes greater than or equal to” trigger of which the actions are to send a notification and to rotate the recording session.
The channel-buffer-usage-ge trigger condition below is considered
satisfied when the ring buffer usage of the Linux kernel event record
channel named my-channel within the recording session named
my-session becomes greater than or equal to 512 KiB.
The order of the --action options below is significant.
$
lttng add-trigger --condition=channel-buffer-usage-ge \
--session=my-session --channel=my-channel \
--domain=kernel --threshold-size=512k \
--action=notify \
--action=rotate-session my-sessionSee lttng-concepts(7) to learn more about recording sessions, event record channels, and rotations.
Example:Add a “recording session rotation finishes” trigger of which the action is to send a notification.
The session-rotation-finishes trigger condition below is considered
satisfied when a rotation of the recording session named my-session
finishes.
$
lttng add-trigger --condition=session-rotation-finishes \
--session=my-session --action=notifySee lttng-concepts(7) to learn more about recording sessions and rotations.
Mailing list for support and
development: lttng-dev@lists.lttng.org
IRC channel: #lttng on irc.oftc.net
This program is part of the LTTng-tools project.
LTTng-tools is distributed under the
GNU General
Public License version 2. See the
LICENSE file
for details.
Special thanks to Michel Dagenais and the DORSAL laboratory at École Polytechnique de Montréal for the LTTng journey.
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases.