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)