lttng-add-trigger(1)
====================
-:revdate: 23 April 2021
+:revdate: 14 June 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
('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.
+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
Synopsis:
+
[verse]
-option:--action=notify [nloption:--rate-policy='POLICY']
+option:--action=**notify** [nloption:--rate-policy='POLICY']
{nbsp}
+
Sends a notification through the notification
+
See below for the nloption:--rate-policy option.
-Start a tracing session::
+Start a recording session::
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)
+Starts the recording session named 'SESSION' like man:lttng-start(1)
would.
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+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 tracing session::
+Stop a recording session::
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.
+Stops the recording session named 'SESSION' like man:lttng-stop(1)
+would.
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+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 tracing session::
+Rotate a recording session::
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'
-like man:lttng-rotate(1) would.
+Archives the current trace chunk of the recording session named
+'SESSION' like man:lttng-rotate(1) would.
+
-If no tracing session has the name 'SESSION' when LTTng is ready to
+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 tracing session snapshot::
+Take a recording session snapshot::
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
+Takes a snapshot of the recording 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
+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 tracing session has the name 'SESSION' when LTTng is ready to
+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.
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`.
option:--condition='CONDTYPE'::
Introductory option for a condition specifier of type 'CONDTYPE'.
+
-See the <<cond-spec,Condition specifier>> section above to learn more.
+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.
+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.
-include::common-cmd-help-options.txt[]
+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
+----
+====
-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)