lttng-add-trigger(1)
-=====================
-:revdate: 27 May 2020
+====================
+:revdate: 14 June 2021
NAME
----
-lttng-add-trigger - Create LTTng triggers
+lttng-add-trigger - Add an LTTng trigger
SYNOPSIS
--------
-
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
- --condition CONDITION-NAME CONDITION-ARGS
- --action ACTION-NAME ACTION-ARGS
- [--action ACTION-NAME ACTION-ARGS]...
-
+*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 `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.
+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.
-The syntax by which conditions and actions are specified is described
-below.
+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 firing trigger in this order.
-[[conditions]]
-Conditions
-~~~~~~~~~~
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-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.
+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.
-The available conditions are:
+Remove a trigger with the man:lttng-remove-trigger(1) command.
-Event rule: `event-rule-matches [event rule arguments]`::
- This type of condition is met when the tracer encounters an event
- matching the given event 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.
+[[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.
+
-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.
+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.
-[[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.
+[[capture-descr]]
+Capture descriptor
+~~~~~~~~~~~~~~~~~~
+A capture descriptor is a textual expression which describes how to read
+an event record or context field.
-The available actions are:
+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.
-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.
+A capture descriptor expression is one of:
-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.
+'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`.
-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.
+++$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`.
-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.
+++$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`.
-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.
+__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:
-[[capture-expr]]
-Capture expression
-~~~~~~~~~~~~~~~~~~
+* 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.
-A capture expression can be specified with the option:--capture option when
-creating a new event-rule-matches 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.
+[[action-spec]]
+Action specifier
+~~~~~~~~~~~~~~~~
+Synopsis:
-* 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.
+[verse]
+option:--action='ACTTYPE' ['ACTARGS']
-* The dynamic value of an event field is captured by using its name as a C
- identifier.
+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:
+
-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`.
+[verse]
+option:--action=**notify** [nloption:--rate-policy='POLICY']
+{nbsp}
+
-An enumeration field's value is an integer.
+Sends a notification through the notification
+mechanism of the session daemon (see man:lttng-session(8)).
+
-When the capture's field does not exist, the capture expression
-evaluates to `unavailable`.
+The session daemon sends details about the condition evaluation along
+with the notification.
+
-Examples: `my_field`, `target_cpu`, `seq[7]`
+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.
-* 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.
+Start a recording session::
+ Synopsis:
+
-When the expression's statically-known context field does not exist,
-the capture expression evaluates to `unavailable`.
+[verse]
+option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
+
-Examples: `$ctx.prio`, `$ctx.preemptible`,
-`$ctx.perf:cpu:stalled-cycles-frontend`.
+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.
+
-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.
+See below for the nloption:--rate-policy option.
-* 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).
+Stop a recording session::
+ Synopsis:
+
-When the expression's application-specific context field does not exist,
-the capture expression evaluates to `unavailable`.
+[verse]
+option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
+{nbsp}
+
-Example: `$app.server:cur_user`.
+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.
+
-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.
+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:--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 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`.
-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.
+Specifier
+~~~~~~~~~
+option:--condition='CONDTYPE'::
+ Introductory option for a condition specifier of type 'CONDTYPE'.
++
+See the ``<<cond-spec,Condition specifier>>'' section above to learn
+more.
-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.
+option:--action='ACTTYPE'::
+ Introductory option for an action specifier of type 'ACTTYPE'.
+
-If a trigger with the specified 'ID' already exists, the trigger
-creation will fail.
+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
+----
+====
-option:--fire-every 'N'::
- Execute the trigger's actions every 'N' times the condition is met.
+.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.
-option:--fire-once-after 'N'::
- Execute the trigger's actions once after 'N' times the condition is
- met, then never after that.
+The order of the option:--action options below is significant.
-include::common-cmd-help-options.txt[]
+[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
+----
+====
-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(1)
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff