--- /dev/null
+lttng-add-trigger(1)
+=====================
+:revdate: 27 May 2020
+
+
+NAME
+----
+lttng-add-trigger - Create LTTng triggers
+
+
+SYNOPSIS
+--------
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
+ [--fire-every N] [--fire-once-after N]
+ --condition CONDITION-NAME CONDITION-ARGS
+ --action ACTION-NAME ACTION-ARGS
+ [--action ACTION-NAME ACTION-ARGS]...
+
+
+DESCRIPTION
+-----------
+
+The `lttng add-trigger` command is used to create triggers. A
+trigger is an association between a *condition* and one or more
+*actions*. When the condition associated to a trigger is met, the
+actions associated to that trigger are executed. The tracing does not
+have to be active for the conditions to be met, and triggers are
+independent from tracing sessions.
+
+By default, a trigger fires every time its condition is met. The
+'--fire-every' and '--fire-once-after' options can be used to change
+this mode.
+
+The syntax by which conditions and actions are specified is described
+below.
+
+[[conditions]]
+Conditions
+~~~~~~~~~~
+
+Conditions are specified with the `--condition` option, followed by a
+condition name, and possibly some more arguments, depending on the
+specific condition. There must be exactly one condition given in the
+`lttng add-trigger` invocation.
+
+The available conditions are:
+
+Event rule: `on-event [event rule arguments]`::
+ This type of condition is met when the tracer encounters an event
+ matching the given even rule. The arguments describing the event
+ rule are the same as those describing the event rules of the
+ man:lttng-enable-event(1) command, with these exceptions:
+
+ - It is not possible to use filter operands that use values from
+ the context.
+
++
+Fields to capture can be specified with the option:--capture option, followed by
+a capture expression. Zero or more captures can be configured. See the
+<<capture-expr, Capture expression>> section below for more information.
+
+[[actions]]
+Actions
+~~~~~~~
+
+Actions are specified with the `--action` option, followed by an action
+name, and possibly some more arguments, depending on the specific
+action. There must be at least one action given in the
+`lttng add-trigger` invocation.
+
+The available actions are:
+
+Notify: *notify*::
+ This action causes the LTTng session daemon to send a notification,
+ through its notification mechanism (see man:lttng-sessiond(8)).
+ Some details about the condition evaluation are sent along with the
+ notification.
+
+Start session: *start-session* session-name::
+ This action causes the LTTng session daemon to start tracing for the
+ session with the given name. If no session with the given name exist
+ at the time the condition is met, nothing is done.
+
+Stop session: *stop-session* session-name::
+ This action causes the LTTng session daemon to stop tracing for the
+ session with the given name. If no session with the given name exist
+ at the time the condition is met, nothing is done.
+
+Rotate session: *rotate-session* session-name::
+ This action causes the LTTng session daemon to rotate the session
+ with the given name. See man:lttng-rotate(1) for more information
+ about the session rotation concept. If no session with the given
+ name exist at the time the condition is met, nothing is done.
+
+Snapshot session: *snapshot-session* session-name::
+ This action causes the LTTng session daemon to take a snapshot of the
+ session with the given name. See man:lttng-snapshot(1) for more
+ information about the session snapshot concept. If no session with
+ the given name exist at the time the condition is met, nothing is
+ done.
+
+
+[[capture-expr]]
+Capture expression
+~~~~~~~~~~~~~~~~~~
+
+A capture expression can be specified with the option:--capture option when
+creating a new on-event condition. If the capture expression corresponds with an
+event's field when tracing, the runtime dynamic value corresponding to the
+capture expression is captured.
+
+NOTE: Make sure to **single-quote** the capture expression when running
+the command from a shell, as capture expressions typically include
+characters having a special meaning for most shells.
+
+* Supported field types:
+ - integer,
+ - unsigned integer,
+ - floating point value,
+ - fixed-size array of integers,
+ - variable-size array of integers (sequence),
+ - enumeration,
+ - text string,
+ - element of any allowing previous type.
+
+* The dynamic value of an event field is captured by using its name as a C
+ identifier.
++
+The square bracket notation is available, like in the C
+language, to access array/sequence field.
+Only a constant, positive integer number can be used within square
+brackets. If the index is out of bounds, the capture expression
+evaluates to `unavailable`.
++
+An enumeration field's value is an integer.
++
+When the capture's field does not exist, the capture expression
+evaluates to `unavailable`.
++
+Examples: `my_field`, `target_cpu`, `seq[7]`
+
+* The dynamic value of a statically-known context field is captured by
+ prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of
+ available contexts.
++
+When the expression's statically-known context field does not exist,
+the capture expression evaluates to `unavailable`.
++
+Examples: `$ctx.prio`, `$ctx.preemptible`,
+`$ctx.perf:cpu:stalled-cycles-frontend`.
++
+NOTE: The statically-known context field does NOT need to be added using the
+man:lttng-add-context(1) command. The statically-known context fields are
+always available in the context of triggers.
+
+* The dynamic value of an application-specific context field is captured by
+ prefixing its name with `$app.` (follows the format used to add such a context
+ field with the man:lttng-add-context(1) command).
++
+When the expression's application-specific context field does not exist,
+the capture expression evaluates to `unavailable`.
++
+Example: `$app.server:cur_user`.
++
+NOTE: The application-specific context field does NOT need to be added using the
+man:lttng-add-context(1) command. The application-specific context fields fields
+are always available in the context of triggers.
+
+
+OPTIONS
+-------
+
+option:--condition::
+ Define the condition for the trigger. See the
+ <<conditions,CONDITIONS>> section for more details.
+
+option:--action::
+ Define an action for the trigger. See the <<actions,ACTIONS>>
+ section for more details.
+
+option:--id='ID'::
+ Set the id of the trigger to 'ID'. If omitted, an id will
+ automatically be assigned to the trigger by the session daemon.
++
+If a trigger with the specified 'ID' already exists, the trigger
+creation will fail.
+
+option:--fire-every 'N'::
+ Execute the trigger's actions every 'N' times the condition is met.
+
+option:--fire-once-after 'N'::
+ Execute the trigger's actions once after 'N' times the condition is
+ met, then never after that.
+
+include::common-cmd-help-options.txt[]
+
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:lttng-list-triggers(1),
+man:lttng-remove-trigger(1),
+man:lttng(1)
projects / lttng-tools.git / blobdiff