// SPDX-FileCopyrightText: 2020 Simon Marchi <simon.marchi@efficios.com>
// SPDX-FileCopyrightText: 2021-2025 Philippe Proulx <pproulx@efficios.com>
// SPDX-FileCopyrightText: 2025 Kienan Stewart <kstewart@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

lttng-add-trigger(1)
====================
:revdate: 27 April 2026


NAME
----
lttng-add-trigger - Add an LTTng trigger


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-uid='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 connected session daemon (see man:lttng-sessiond(8)).

See man: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 option:--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
option:--owner-uid option.

Specify the condition of the trigger to add with a <<cond-spec,condition
specifier>> and its actions with one or more <<action-spec,action
specifiers>>. The order of the action specifiers is significant: LTTng
attempts to execute the actions of a firing trigger in this order.

See the ``<<examples,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 man:lttng-list-triggers(1) command.

Remove a trigger with the man:lttng-remove-trigger(1) command.


[[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:

[[channel-buffer-usage-cond-spec]]`channel-buffer-usage-ge`::
`channel-buffer-usage-le`::
    Synopses:
+
[verse]
option:--condition=**channel-buffer-usage-ge** nloption:--session='SESSION'
nloption:--channel='CHANNEL'
nloption:--domain=(`kernel` | `user` | `jul` | `log4j` | `log4j2` | `python`)
(nloption:--threshold-ratio='RATIO' | nloption:--threshold-size='SIZE')
{nbsp}
option:--condition=**channel-buffer-usage-le** nloption:--session='SESSION'
nloption:--channel='CHANNEL'
nloption:--domain=(`kernel` | `user` | `jul` | `log4j` | `log4j2` | `python`)
(nloption:--threshold-ratio='RATIO' | nloption:--threshold-size='SIZE')
{nbsp}
+
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 nloption:--domain) becomes greater/less than
or equal to either:
+
--
With the nloption:--threshold-size='SIZE' option::
    'SIZE' bytes.
+
'SIZE' supports the `k`{nbsp}(KiB), `M`{nbsp}(MiB), and
`G`{nbsp}(GiB) suffixes.

With the nloption:--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{nbsp}0 to{nbsp}1.
--
+
Every time the monitor timer (see the nloption:--monitor-timer option of
man: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 nloption:-c, nloption:-d, nloption:-s, and nloption:-t
are aliases of nloption:--channel, nloption:--domain,
nloption:--session, and nloption:--threshold-size.

[[er-matches-cond-spec]]`event-rule-matches`::
    Synopsis:
+
[verse]
option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
{nbsp}
+
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), including its instrumentation point type
(nloption:--type), event name (nloption:--name), instrumentation
point log level (nloption:--log-level), and event payload/context
filter (nloption:--filter) conditions.
+
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.

[[session-consumed-size-cond-spec]]`session-consumed-size-ge`::
    Synopsis:
+
[verse]
option:--condition=**session-consumed-size-ge** nloption:--session='SESSION'
nloption:--threshold-size='THRESHOLD'
{nbsp}
+
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 nloption:--monitor-timer option of
man: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`{nbsp}(KiB), `M`{nbsp}(MiB), and
`G`{nbsp}(GiB) suffixes.
+
The short options nloption:-s and nloption:-t are aliases of
nloption:--session and nloption:--threshold-size.

[[session-rotation-cond-spec]]`session-rotation-starts`::
`session-rotation-finishes`::
    Synopses:
+
[verse]
option:--condition=**session-rotation-starts** nloption:--session='SESSION'
{nbsp}
option:--condition=**session-rotation-finishes** nloption:--session='SESSION'
{nbsp}
+
A `session-rotation-starts` or `session-rotation-finishes` condition is
considered satisfied when the rotation operation (see
man:lttng-rotate(1)) of the recording session 'SESSION' starts or
finishes.
+
The short option nloption:-s is an alias of nloption:--session.

[[capture-descr]]
Capture descriptor
~~~~~~~~~~~~~~~~~~
A capture descriptor is a textual expression which describes how to read
an event record or context field.

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.

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
man:lttng-add-context(1). As of LTTng{nbsp}{lttng_version},
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 man: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.


[[action-spec]]
Action specifier
~~~~~~~~~~~~~~~~
Synopsis:

[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:

Increment a map value::
    Synopsis:
+
[verse]
option:--action=**incr-map-value** nloption:--session='SESSION' nloption:--channel='CHANNEL'
                        nloption:--type=(`kernel` | `user`) nloption:--key='TEMPLATE'
{nbsp}
+
Increments a counter within the map channel named 'CHANNEL' (see
man:lttng-add-map-channel(1)) with the type of nloption:--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 man: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 `{{` or `}}` in 'TEMPLATE'
(similar to pass:[{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
<<er-matches-cond-spec,``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 nloption:--type
option of man:lttng-event-rule(7)): 'TEMPLATE' must be literal text in
that case.
+
When the condition of the trigger isn't an
<<er-matches-cond-spec,``event rule matches'' condition>>
(`event-rule-matches`), nloption:--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 man:lttng-start(1)). While the
recording session is inactive (stopped; see man:lttng-stop(1)), the
action does nothing.
+
The update policy of 'CHANNEL' (see the nloption:--update-policy
option of man: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 nloption:--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 nloption:-s, nloption:-c, nloption:-t, and
nloption:-k are aliases of nloption:--session, nloption:--channel,
nloption:--type, and nloption:--key.

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-sessiond(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.

Start a recording session::
    Synopsis:
+
[verse]
option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Starts the recording session named 'SESSION' like man: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 nloption:--rate-policy option.

Stop a recording session::
    Synopsis:
+
[verse]
option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Stops the recording session named 'SESSION' like man: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 nloption:--rate-policy option.

Rotate a recording session::
    Synopsis:
+
[verse]
option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Archives the current trace chunk of the recording session named
'SESSION' like man: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 nloption:--rate-policy option.

Take a recording session snapshot::
    Synopsis:
+
[verse]
option:--action=**snapshot-session** 'SESSION' [nloption:--name='NAME']
                          [nloption:--max-size='SIZE']
                          [nloption:--path='PATH' | nloption:--url='URL' |
                           (nloption:--ctrl-url='URL' nloption:--data-url='URL')]
                          [nloption:--rate-policy='POLICY']
{nbsp}
+
Takes a snapshot of the recording session named 'SESSION' like
man: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 man: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 man:lttng-snapshot(1) command
to learn about the snapshot output options:
nloption:--name/nloption:-n,
nloption:--max-size/nloption:-m,
nloption:--url,
nloption:--ctrl-url/nloption:-C, and
nloption:--data-url/nloption:-D. The nloption:--path option specifies
to write the snapshot to the local directory{nbsp}__PATH__.
+
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' 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{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__.
+
'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.
--
+
'COUNT' must be an integer greater than{nbsp}0.
+
As of LTTng{nbsp}{lttng_version}, every action type except
`incr-map-value` supports this option, but new action types in the
future may also 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-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`.


Specifier
~~~~~~~~~
option:--condition='CONDTYPE'::
    Introductory option for a condition specifier of type 'CONDTYPE'.
+
See the ``<<cond-spec,Condition specifier>>'' section above to learn
more.

option:--action='ACTTYPE'::
    Introductory option for an action specifier of type 'ACTTYPE'.
+
See the ``<<action-spec,Action specifier>>'' section above to learn
more.


include::common-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.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`.

[role="term"]
----
$ lttng add-trigger --condition=event-rule-matches \
                    --type=syscall:entry \
                    --name='exec*' --action=notify
----
====

.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 option:--action options below is significant.

[role="term"]
----
$ 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-session
----

See man:lttng-concepts(7) to learn more about recording sessions and
rotations.
====

.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 option:--name option.

[role="term"]
----
$ lttng add-trigger --name=my-trigger \
                    --condition=event-rule-matches \
                    --type=python --name=my-logger \
                    --action=snapshot-session my-session
----
====

.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 option:--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`.

[role="term"]
----
# lttng add-trigger --owner-uid=$(id --user mireille) \
                    --condition=event-rule-matches \
                    --type=kernel --name='sched*' \
                    --action=notify
----
====

.Add an ``event rule matches'' trigger with a notification action to be executed every 10{nbsp}times.
====
The `event-rule-matches` trigger condition below specifies an event rule
which matches all user space tracepoint events.

See the nloption:--rate-policy option above.

[role="term"]
----
$ lttng add-trigger --condition=event-rule-matches \
                    --type=user --action=notify \
                    --rate-policy=every:10
----
====

.Add an ``event rule matches'' trigger with a recording session starting action to be executed a single time after 40{nbsp}times.
====
The `event-rule-matches` trigger condition below specifies an event rule
which matches any Linux system call event (entry and exit) of which the
`fd` event record field is less than{nbsp}3.

See the nloption:--rate-policy option above.

[role="term"]
----
$ lttng add-trigger --condition=event-rule-matches \
                    --type=syscall --filter='fd < 3' \
                    --action=start-session my-session \
                    --rate-policy=once-after:40
----
====

.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 man:lttng-add-map-channel(1) to learn how to add a map channel.

[role="term"]
----
$ 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}'
----
====

.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{nbsp}MiB.

[role="term"]
----
$ lttng add-trigger --condition=session-consumed-size-ge \
                    --session=my-session --threshold-size=100M \
                    --action=rotate-session my-session
----

See man:lttng-concepts(7) to learn more about recording sessions and
rotations.
====

.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{nbsp}KiB.

The order of the option:--action options below is significant.

[role="term"]
----
$ 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-session
----

See man:lttng-concepts(7) to learn more about recording sessions,
event record channels, and rotations.
====

.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.

[role="term"]
----
$ lttng add-trigger --condition=session-rotation-finishes \
                    --session=my-session --action=notify
----

See man:lttng-concepts(7) to learn more about recording sessions and
rotations.
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-add-map-channel(1),
man:lttng-list-triggers(1),
man:lttng-remove-trigger(1),
man:lttng-concepts(7)
