lttng-add-trigger(1)
====================
-:revdate: 23 April 2021
+:revdate: 6 May 2021
NAME
SYNOPSIS
--------
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-id='UID']
+*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 session daemon (see man:lttng-sessiond(8)).
+the connected session daemon (see man:lttng-sessiond(8)).
-A trigger is an association between a _condition_ and one or more
-_actions_. When the condition of a trigger{nbsp}__T__ is satisfied,
-LTTng requests to execute the actions of{nbsp}__T__. Depending on the
-rate policy of an action, an execution request can become an actual
-execution.
+See man:lttng-concepts(7) to learn more about LTTng triggers.
-A trigger doesn't belong to a specific tracing session: it's global to
-the session daemon. Within the session daemon, and for a given Unix
-user, a trigger has a unique name. By default, the `add-trigger` command
-automatically assigns a name to the added trigger. Use the option:--name
-option to assign a specific name instead.
+By default, the `add-trigger` command automatically assigns a name,
+unique for a given session daemon and Unix user, to the added trigger.
+Assign a custom name with the option:--name.
The `add-trigger` command adds a trigger for your Unix user. If your
-Unix user is `root`, you can add the trigger as another user with the
-option:--owner-id option.
+Unix user is `root`, you may add the trigger as another user with the
+option:--owner-uid option.
Specify the condition of the trigger to add with a <<cond-spec,condition
specifier>> and its actions with one or more <<action-spec,action
specifiers>>. The order of the action specifiers is significant: LTTng
-attempts to execute the actions of a trigger in order.
+attempts to execute the actions of a firing trigger in this order.
-List the available triggers for your Unix user (or for all users if your
-Unix user is `root`) with the man:lttng-list-triggers(1) command.
+See the <<examples,EXAMPLES>> section below for usage examples.
-Remove an existing trigger with the man:lttng-remove-trigger(1) command.
+List the triggers of your Unix user, or of all users if your
+Unix user is `root`, with the man:lttng-list-triggers(1) command.
+
+Remove a trigger with the man:lttng-remove-trigger(1) command.
[[cond-spec]]
Synopsis:
+
[verse]
-option:--condition=event-rule-matches [nloption:--capture='CDESCR']... 'ERSPEC'
+option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
{nbsp}
+
An `event-rule-matches` condition is considered satisfied when the event
Synopsis:
+
[verse]
-option:--action=notify [nloption:--rate-policy='POLICY']
+option:--action=**notify** [nloption:--rate-policy='POLICY']
{nbsp}
+
Sends a notification through the notification
Synopsis:
+
[verse]
-option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Starts the tracing session named 'SESSION' like man:lttng-start(1)
Synopsis:
+
[verse]
-option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
Synopsis:
+
[verse]
-option:--action=rotate-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Archives the current trace chunk of the tracing session named 'SESSION'
Synopsis:
+
[verse]
-option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY']
+option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
{nbsp}
+
Takes a snapshot of the tracing session named 'SESSION' like
Common action options (as of LTTng{nbsp}{lttng_version}):
nloption:--rate-policy='POLICY'::
- Set the rate policy of the action to '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
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.
-+
'POLICY' is one of:
+
--
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.
Set the unique name of the trigger to add to 'NAME' instead of the
`add-trigger` command automatically assigning one.
-option:--owner-id='UID'::
+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`.
See the <<action-spec,Action specifier>> section above to learn more.
-include::common-cmd-help-options.txt[]
+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 \
+ --domain=kernel --type=syscall:entry \
+ --name='exec*' --action=notify
+----
+====
+
+.Add an ``event rule matches'' trigger of which the action is to stop a tracing 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 \
+ --domain=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 tracing 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 \
+ --domain=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 \
+ --domain=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 \
+ --domain=user --action=notify \
+ --rate-policy=every:10
+----
+====
+
+.Add an ``event rule matches'' trigger with a tracing 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 \
+ --domain=kernel --type=syscall \
+ --filter='fd < 3' \
+ --action=start-session my-session \
+ --rate-policy=once-after:40
+----
+====
-include::common-cmd-footer.txt[]
+include::common-footer.txt[]
SEE ALSO
--------
man:lttng(1),
man:lttng-list-triggers(1),
-man:lttng-remove-trigger(1)
+man:lttng-remove-trigger(1),
+man:lttng-concepts(7)