lttng-add-trigger(1) ==================== :revdate: 9 December 2025 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 <> and its actions with one or more <>. The order of the action specifiers is significant: LTTng attempts to execute the actions of a firing trigger in this order. See the ``<>'' 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 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 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 a 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). + Capture event record and context fields with one or more nloption:--capture options (see the ``<>'' 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 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 a 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 <> (`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: 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}, 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-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 ``<>'' section above to learn more. option:--action='ACTTYPE':: Introductory option for an action specifier of type 'ACTTYPE'. + See the ``<>'' 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 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 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, 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-list-triggers(1), man:lttng-remove-trigger(1), man:lttng-concepts(7)