+The `lttng add-trigger` command creates and adds an LTTng _trigger_ to
+the 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+Remove an existing 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:
+
+[[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 <<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.
+
+
+[[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).
++
+Examples: `$ctx.prio`, `$ctx.preemptible`,
+`$ctx.perf:cpu:stalled-cycles-frontend`.
+
+++$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-session(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 tracing session::
+ Synopsis:
++
+[verse]
+option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
++
+Starts the tracing session named 'SESSION' like man:lttng-start(1)
+would.
++
+If no tracing 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::
+ Synopsis:
++
+[verse]
+option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
++
+Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
++
+If no tracing 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::
+ Synopsis:
++
+[verse]
+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.
++
+If no tracing 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::
+ Synopsis:
++
+[verse]
+option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
++
+Takes a snapshot of the tracing 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
+(see man:lttng-create(1)).
++
+If no tracing session has the name 'SESSION' when LTTng is ready to
+execute the action, LTTng does nothing.
++
+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'.
++
+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__.
++
+The default action rate policy is `every:1` (always execute{nbsp}__A__).
+Use this option to specify another rate policy.
++
+'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.
+--
++
+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.