X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-add-trigger.1.txt;h=84a175eb6cfa6093d3112a006fe7167bb2fef59b;hb=d65a3957032165689ca1f1ed4d001859d3542783;hp=ccca9da0f8b4353e19dc9d1cd2157505e9556e0e;hpb=d938377c86a9fd0f69881a6a03290bb436cb587d;p=lttng-tools.git diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index ccca9da0f..84a175eb6 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -1,6 +1,6 @@ lttng-add-trigger(1) ==================== -:revdate: 23 April 2021 +:revdate: 6 May 2021 NAME @@ -18,33 +18,29 @@ SYNOPSIS 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 +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 <> and its actions with one or more <>. 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. +See the <> section below for usage examples. -Remove an existing trigger with the man:lttng-remove-trigger(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 a trigger with the man:lttng-remove-trigger(1) command. [[cond-spec]] @@ -65,7 +61,7 @@ The available condition types are: 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 @@ -168,7 +164,7 @@ Notify:: Synopsis: + [verse] -option:--action=notify [nloption:--rate-policy='POLICY'] +option:--action=**notify** [nloption:--rate-policy='POLICY'] {nbsp} + Sends a notification through the notification @@ -186,7 +182,7 @@ Start a tracing session:: 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) @@ -201,7 +197,7 @@ Stop a tracing session:: 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. @@ -215,7 +211,7 @@ Rotate a tracing session:: 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' @@ -230,7 +226,7 @@ Take a tracing session snapshot:: 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 @@ -306,14 +302,128 @@ option:--action='ACTTYPE':: See the <> section above to learn more. -include::common-cmd-help-options.txt[] +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 \ + --domain=kernel --type=syscall:entry \ + --name='exec*' --action=notify +---- +==== + +.Add an ``event rule matches'' trigger of which the action is to stop a tracing 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. + +The order of the option:--action options below is significant. + +[role="term"] +---- +$ lttng add-trigger --condition=event-rule-matches \ + --domain=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 tracing 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 \ + --domain=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 \ + --domain=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 \ + --domain=user --action=notify \ + --rate-policy=every:10 +---- +==== + +.Add an ``event rule matches'' trigger with a tracing 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 \ + --domain=kernel --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-remove-trigger(1), +man:lttng-concepts(7)