lttng-add-trigger(1)
====================
-:revdate: 23 April 2021
+:revdate: 3 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.
+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 an existing trigger with the man:lttng-remove-trigger(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`.
--------
man:lttng(1),
man:lttng-list-triggers(1),
-man:lttng-remove-trigger(1)
+man:lttng-remove-trigger(1),
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff