X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-add-trigger.1.txt;fp=doc%2Fman%2Flttng-add-trigger.1.txt;h=5e2e90e4362535dfcf0b874c11f95047f282234c;hp=0000000000000000000000000000000000000000;hb=2463b7879c00298daa79744cdaae82ac061a4ed8;hpb=3a4595c2469472dee1656cde5f8882c2123efd3c diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt new file mode 100644 index 000000000..5e2e90e43 --- /dev/null +++ b/doc/man/lttng-add-trigger.1.txt @@ -0,0 +1,207 @@ +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 +<> 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 + <> section for more details. + +option:--action:: + Define an action for the trigger. See the <> + 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)