X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-add-trigger.1.txt;h=656f87b4e5e67686fb7266e63923dc88f83004e7;hb=4e8ba2e1cb5bb4eb2a91cae39c3b1e4ea334d832;hp=d111c43b9f3f7991117ed2fec83bdf71780c81ea;hpb=473c70cacf20bda64e8bf5a298001f55edc37898;p=lttng-tools.git diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index d111c43b9..656f87b4e 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: 6 May 2021 +:revdate: 14 June 2021 NAME @@ -35,13 +35,13 @@ specifier>> and its actions with one or more <>. The order of the action specifiers is significant: LTTng attempts to execute the actions of a firing trigger in this order. +See the ``<>'' section below for usage examples. + 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. -See the <> section below for usage examples. - [[cond-spec]] Condition specifier @@ -71,11 +71,11 @@ See man:lttng-event-rule(7) to learn how to specify an event rule ('ERSPEC' part). + Capture event record and context fields with one or more -nloption:--capture options (see the <> -section below to learn more). When an `event-rule-matches` condition -with capture descriptors is satisfied, the captured field values are -available in the evaluation object of the condition using the -liblttng-ctl C{nbsp}API. +nloption:--capture options (see the ``<>'' section below to learn more). When an +`event-rule-matches` condition with capture descriptors is satisfied, +the captured field values are available in the evaluation object of the +condition using the liblttng-ctl C{nbsp}API. + IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the `add-trigger` command from a shell, as capture descriptors can include @@ -178,65 +178,66 @@ to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers). + See below for the nloption:--rate-policy option. -Start a tracing session:: +Start a recording session:: Synopsis: + [verse] option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Starts the tracing session named 'SESSION' like man:lttng-start(1) +Starts the recording session named 'SESSION' like man:lttng-start(1) would. + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. -Stop a tracing session:: +Stop a recording session:: Synopsis: + [verse] option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. +Stops the recording session named 'SESSION' like man:lttng-stop(1) +would. + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. -Rotate a tracing session:: +Rotate a recording session:: Synopsis: + [verse] option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Archives the current trace chunk of the tracing session named 'SESSION' -like man:lttng-rotate(1) would. +Archives the current trace chunk of the recording session named +'SESSION' like man:lttng-rotate(1) would. + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. -Take a tracing session snapshot:: +Take a recording session snapshot:: Synopsis: + [verse] option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY'] {nbsp} + -Takes a snapshot of the tracing session named 'SESSION' like +Takes a snapshot of the recording session named 'SESSION' like man:lttng-snapshot(1) would. + -When the condition of the trigger is satisfied, the tracing session -named 'SESSION', if any, must be a snapshot-mode tracing session +When the condition of the trigger is satisfied, the recording session +named 'SESSION', if any, must be a snapshot-mode recording session (see man:lttng-create(1)). + -If no tracing session has the name 'SESSION' when LTTng is ready to +If no recording session has the name 'SESSION' when LTTng is ready to execute the action, LTTng does nothing. + See below for the nloption:--rate-policy option. @@ -294,12 +295,14 @@ Specifier option:--condition='CONDTYPE':: Introductory option for a condition specifier of type 'CONDTYPE'. + -See the <> section above to learn more. +See the ``<>'' section above to learn +more. option:--action='ACTTYPE':: Introductory option for an action specifier of type 'ACTTYPE'. + -See the <> section above to learn more. +See the ``<>'' section above to learn +more. include::common-lttng-cmd-help-options.txt[] @@ -320,12 +323,12 @@ with `exec`. [role="term"] ---- $ lttng add-trigger --condition=event-rule-matches \ - --domain=kernel --type=syscall:entry \ + --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. +.Add an ``event rule matches'' trigger of which the action is to stop a recording 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 @@ -336,13 +339,13 @@ The order of the option:--action options below is significant. [role="term"] ---- $ lttng add-trigger --condition=event-rule-matches \ - --domain=user --name='my_app:*' \ + --type=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 +See man:lttng-concepts(7) to learn more about recording sessions and rotations. ==== @@ -361,7 +364,7 @@ See the option:--name option. ---- $ lttng add-trigger --name=my-trigger \ --condition=event-rule-matches \ - --domain=python --name=my-logger \ + --type=python --name=my-logger \ --action=snapshot-session my-session ---- ==== @@ -379,7 +382,7 @@ kernel tracepoint events with a name which starts with `sched`. ---- # lttng add-trigger --owner-uid=$(id --user mireille) \ --condition=event-rule-matches \ - --domain=kernel --name='sched*' \ + --type=kernel --name='sched*' \ --action=notify ---- ==== @@ -394,12 +397,12 @@ See the nloption:--rate-policy option above. [role="term"] ---- $ lttng add-trigger --condition=event-rule-matches \ - --domain=user --action=notify \ + --type=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. +.Add an ``event rule matches'' trigger with a recording 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 @@ -410,8 +413,7 @@ See the nloption:--rate-policy option above. [role="term"] ---- $ lttng add-trigger --condition=event-rule-matches \ - --domain=kernel --type=syscall \ - --filter='fd < 3' \ + --type=syscall --filter='fd < 3' \ --action=start-session my-session \ --rate-policy=once-after:40 ----