SoW-2019-0002: Dynamic Snapshot
[lttng-tools.git] / doc / man / lttng-add-trigger.1.txt
1 lttng-add-trigger(1)
2 =====================
3 :revdate: 17 January 2020
4
5
6 NAME
7 ----
8 lttng-add-trigger - Create LTTng triggers
9
10
11 SYNOPSIS
12 --------
13
14 [verse]
15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
16 [--fire-every N] [--fire-once-after N]
17 --condition CONDITION-NAME CONDITION-ARGS
18 --action ACTION-NAME ACTION-ARGS
19 [--action ACTION-NAME ACTION-ARGS]...
20
21
22 DESCRIPTION
23 -----------
24
25 The `lttng add-trigger` command is used to create triggers. A
26 trigger is an association between a *condition* and one or more
27 *actions*. When the condition associated to a trigger is met, the
28 actions associated to that trigger are executed. The tracing does not
29 have to be active for the conditions to be met, and triggers are
30 independent from tracing sessions.
31
32 By default, a trigger fires every time its condition is met. The
33 '--fire-every' and '--fire-once-after' options can be used to change
34 this mode.
35
36 The syntax by which conditions and actions are specified is described
37 below.
38
39 [[conditions]]
40 Conditions
41 ~~~~~~~~~~
42
43 Conditions are specified with the `--condition` option, followed by a
44 condition name, and possibly some more arguments, depending on the
45 specific condition. There must be exactly one condition given in the
46 `lttng add-trigger` invocation.
47
48 The available conditions are:
49
50 Event rule: `on-event [event rule arguments]`::
51 This type of condition is met when the tracer encounters an event
52 matching the given even rule. The arguments describing the event
53 rule are the same as those describing the event rules of the
54 man:lttng-enable-event(1) command, with these exceptions:
55
56 - It is not possible to use filter operands that use values from
57 the context.
58
59 [[actions]]
60 Actions
61 ~~~~~~~
62
63 Actions are specified with the `--action` option, followed by an action
64 name, and possibly some more arguments, depending on the specific
65 action. There must be at least one action given in the
66 `lttng add-trigger` invocation.
67
68 The available actions are:
69
70 Notify: *notify*::
71 This action causes the LTTng session daemon to send a notification,
72 through its notification mechanism (see man:lttng-sessiond(8)).
73 Some details about the condition evaluation are sent along with the
74 notification.
75
76 Start session: *start-session* session-name::
77 This action causes the LTTng session daemon to start tracing for the
78 session with the given name. If no session with the given name exist
79 at the time the condition is met, nothing is done.
80
81 Stop session: *stop-session* session-name::
82 This action causes the LTTng session daemon to stop tracing for the
83 session with the given name. If no session with the given name exist
84 at the time the condition is met, nothing is done.
85
86 Rotate session: *rotate-session* session-name::
87 This action causes the LTTng session daemon to rotate the session
88 with the given name. See man:lttng-rotate(1) for more information
89 about the session rotation concept. If no session with the given
90 name exist at the time the condition is met, nothing is done.
91
92 Snapshot session: *snapshot-session* session-name::
93 This action causes the LTTng session daemon to take a snapshot of the
94 session with the given name. See man:lttng-snapshot(1) for more
95 information about the session snapshot concept. If no session with
96 the given name exist at the time the condition is met, nothing is
97 done.
98
99 OPTIONS
100 -------
101
102 option:--condition::
103 Define the condition for the trigger. See the
104 <<conditions,CONDITIONS>> section for more details.
105
106 option:--action::
107 Define an action for the trigger. See the <<actions,ACTIONS>>
108 section for more details.
109
110 option:--id='ID'::
111 Set the id of the trigger to 'ID'. If omitted, an id will
112 automatically be assigned to the trigger by the session daemon.
113 +
114 If a trigger with the specified 'ID' already exists, the trigger
115 creation will fail.
116
117 option:--fire-every 'N'::
118 Execute the trigger's actions every 'N' times the condition is met.
119
120 option:--fire-once-after 'N'::
121 Execute the trigger's actions once after 'N' times the condition is
122 met, then never after that.
123
124 include::common-cmd-help-options.txt[]
125
126
127 include::common-cmd-footer.txt[]
128
129
130 SEE ALSO
131 --------
132 man:lttng-list-triggers(1),
133 man:lttng-remove-trigger(1),
134 man:lttng(1)
This page took 0.050505 seconds and 5 git commands to generate.