X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-add-trigger.1.txt;h=656f87b4e5e67686fb7266e63923dc88f83004e7;hp=5e2e90e4362535dfcf0b874c11f95047f282234c;hb=e971184584781f70bbbfc52bbede8b9abf0436e5;hpb=943061bdffe3186f34912de959d1d37147914d6c diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index 5e2e90e43..656f87b4e 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -1,207 +1,431 @@ lttng-add-trigger(1) -===================== -:revdate: 27 May 2020 +==================== +:revdate: 14 June 2021 NAME ---- -lttng-add-trigger - Create LTTng triggers +lttng-add-trigger - Add an LTTng trigger 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]... - +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-uid='UID'] + option:--condition='CONDTYPE' ['CONDARGS'] + option:--action='ACTTYPE' ['ACTARGS'] [option:--action='ACTTYPE' ['ACTARGS']]... DESCRIPTION ----------- +The `lttng add-trigger` command creates and adds an LTTng _trigger_ to +the connected session daemon (see man:lttng-sessiond(8)). + +See man:lttng-concepts(7) to learn more about LTTng triggers. + +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 `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. +The `add-trigger` command adds a trigger for your Unix user. If your +Unix user is `root`, you may add the trigger as another user with the +option:--owner-uid option. -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. +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 firing trigger in this order. -The syntax by which conditions and actions are specified is described -below. +See the ``<>'' section below for usage examples. -[[conditions]] -Conditions -~~~~~~~~~~ +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. -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. +Remove a trigger with the man:lttng-remove-trigger(1) command. -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: +[[cond-spec]] +Condition specifier +~~~~~~~~~~~~~~~~~~~ +Synopsis: + +[verse] +option:--condition='CONDTYPE' ['CONDARGS'] + +A condition specifier is the option:--condition option, which specifies +the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE', +with zero or more arguments 'CONDARGS'. - - It is not possible to use filter operands that use values from - the context. +The available condition types are: +[[er-matches-cond-spec]]`event-rule-matches`:: + Synopsis: + -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. +[verse] +option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC' +{nbsp} ++ +An `event-rule-matches` condition is considered satisfied when the event +rule specified with 'ERSPEC' matches an event. ++ +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. ++ +IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the +`add-trigger` command from a shell, as capture descriptors can include +characters having a special meaning for most shells. -[[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. +[[capture-descr]] +Capture descriptor +~~~~~~~~~~~~~~~~~~ +A capture descriptor is a textual expression which describes how to read +an event record or context field. + +The argument of a nloption:--capture option, when using an +<> +(`event-rule-matches`), is a capture descriptor. + +A capture descriptor expression is one of: + +'NAME':: + An event record field named 'NAME'. ++ +The supported event record field types are: ++ +-- +* Integer +* Enumeration (integral value) +* Floating point number +* Static array of integers +* Dynamic array (``sequence'') of integers +* Text string +-- ++ +Examples: `my_field`, `target_cpu`, `ip`. -The available actions are: +++$ctx.++__NAME__:: + A statically-known context field named 'NAME'. ++ +List the available statically-known context field names with +man:lttng-add-context(1). ++ +Examples: `$ctx.prio`, `$ctx.preemptible`, +`$ctx.perf:cpu:stalled-cycles-frontend`. -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. +++$app.++__PROVIDER__++.++__NAME__:: + An application-specific context field named 'NAME' from the + provider 'PROVIDER'. ++ +See man:lttng-add-context(1) to learn more about application-specific +context fields. ++ +Example: `$app.server:cur_user`. -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. +__EXPR__++[++__INDEX__++]++:: + The element at index 'INDEX' of the array field (static or dynamic) + identified by the expression 'EXPR'. ++ +'INDEX' must be a constant, positive integral value. ++ +Examples: `ip[3]`, `user_ids[15]`. -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. +If, when an event rule matches, a given capture descriptor doesn't +identify an existing event or context field, then the captured value is +reported as being unavailable. This applies to: -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. +* A nonexistent event record field name. +* A nonexistent statically-known context field name. +* A nonexistent application-specific context field name. +* An out-of-bounds array field index. -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. +[[action-spec]] +Action specifier +~~~~~~~~~~~~~~~~ +Synopsis: -[[capture-expr]] -Capture expression -~~~~~~~~~~~~~~~~~~ +[verse] +option:--action='ACTTYPE' ['ACTARGS'] -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. +An action specifier is the option:--action option, which specifies +the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero +or more arguments 'ACTARGS'. -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. +The available action types are: -* 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. +Notify:: + Synopsis: ++ +[verse] +option:--action=**notify** [nloption:--rate-policy='POLICY'] +{nbsp} ++ +Sends a notification through the notification +mechanism of the session daemon (see man:lttng-session(8)). ++ +The session daemon sends details about the condition evaluation along +with the notification. ++ +As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program +to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers). ++ +See below for the nloption:--rate-policy option. -* The dynamic value of an event field is captured by using its name as a C - identifier. +Start a recording session:: + Synopsis: + -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`. +[verse] +option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -An enumeration field's value is an integer. +Starts the recording session named 'SESSION' like man:lttng-start(1) +would. + -When the capture's field does not exist, the capture expression -evaluates to `unavailable`. +If no recording session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. + -Examples: `my_field`, `target_cpu`, `seq[7]` +See below for the nloption:--rate-policy option. -* 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. +Stop a recording session:: + Synopsis: + -When the expression's statically-known context field does not exist, -the capture expression evaluates to `unavailable`. +[verse] +option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -Examples: `$ctx.prio`, `$ctx.preemptible`, -`$ctx.perf:cpu:stalled-cycles-frontend`. +Stops the recording session named 'SESSION' like man:lttng-stop(1) +would. ++ +If no recording session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. + -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. +See below for the nloption:--rate-policy option. -* 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). +Rotate a recording session:: + Synopsis: ++ +[verse] +option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -When the expression's application-specific context field does not exist, -the capture expression evaluates to `unavailable`. +Archives the current trace chunk of the recording session named +'SESSION' like man:lttng-rotate(1) would. + -Example: `$app.server:cur_user`. +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 recording session snapshot:: + Synopsis: ++ +[verse] +option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -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. +Takes a snapshot of the recording session named 'SESSION' like +man:lttng-snapshot(1) would. ++ +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 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. + +Common action options (as of LTTng{nbsp}{lttng_version}): + +nloption:--rate-policy='POLICY':: + Set the rate policy of the action to 'POLICY' instead of + `every:1` (always execute). ++ +A trigger which ``fires'' (its condition is satisfied) leads to an +execution request for each of its actions, in order. An execution +request of a given action{nbsp}__A__ first increments the execution +request count{nbsp}__C__ of{nbsp}__A__. An execution request can then +become an actual execution when{nbsp}__C__ satisfies the rate policy +of{nbsp}__A__. ++ +'POLICY' is one of: ++ +-- +++once-after:++__COUNT__:: + Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'. ++ +In other words, execute{nbsp}__A__ a single time after 'COUNT' execution +requests. + +++every:++__COUNT__:: + Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'. ++ +In other words, execute{nbsp}__A__ every 'COUNT' execution requests. +-- ++ +'COUNT' must be an integer greater than{nbsp}0. ++ +As of LTTng{nbsp}{lttng_version}, you can use this option with any +action type, but new action types in the future may not support it. OPTIONS ------- +Identification +~~~~~~~~~~~~~~ +option:--name='NAME':: + Set the unique name of the trigger to add to 'NAME' instead of the + `add-trigger` command automatically assigning one. + +option:--owner-uid='UID':: + Add the trigger as the Unix user having the user ID 'UID'. ++ +You may only use this option if your Unix user is `root`. -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. +Specifier +~~~~~~~~~ +option:--condition='CONDTYPE':: + Introductory option for a condition specifier of type 'CONDTYPE'. ++ +See the ``<>'' section above to learn +more. -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. +option:--action='ACTTYPE':: + Introductory option for an action specifier of type 'ACTTYPE'. + -If a trigger with the specified 'ID' already exists, the trigger -creation will fail. +See the ``<>'' section above to learn +more. + + +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 \ + --type=syscall:entry \ + --name='exec*' --action=notify +---- +==== -option:--fire-every 'N':: - Execute the trigger's actions every 'N' times the condition is met. +.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 +`my_app:` and with a log level at least as severe as a warning. -option:--fire-once-after 'N':: - Execute the trigger's actions once after 'N' times the condition is - met, then never after that. +The order of the option:--action options below is significant. -include::common-cmd-help-options.txt[] +[role="term"] +---- +$ lttng add-trigger --condition=event-rule-matches \ + --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 recording 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 \ + --type=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 \ + --type=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 \ + --type=user --action=notify \ + --rate-policy=every:10 +---- +==== + +.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 +`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 \ + --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(1) +man:lttng-concepts(7)