X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-add-trigger.1.txt;h=5694d28d695dd03dcb8351f5b1ffc50c38f6687c;hb=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66;hp=5e2e90e4362535dfcf0b874c11f95047f282234c;hpb=943061bdffe3186f34912de959d1d37147914d6c;p=lttng-tools.git diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index 5e2e90e43..5694d28d6 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -1,198 +1,304 @@ lttng-add-trigger(1) -===================== -:revdate: 27 May 2020 +==================== +:revdate: 3 May 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. -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, 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. -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 `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. -The syntax by which conditions and actions are specified is described -below. +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. -[[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'] - - It is not possible to use filter operands that use values from - the context. +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'. +The available condition types are: + +[[er-matches-cond-spec]]`event-rule-matches`:: + Synopsis: ++ +[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. + -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. +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 available actions are: +The argument of a nloption:--capture option, when using an +<> +(`event-rule-matches`), is a capture descriptor. -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. +A capture descriptor expression is one of: -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. +'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`. -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. +++$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`. + +++$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`. + +__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]`. -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. +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: -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. +* 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. -[[capture-expr]] -Capture expression -~~~~~~~~~~~~~~~~~~ +[[action-spec]] +Action specifier +~~~~~~~~~~~~~~~~ +Synopsis: -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. +[verse] +option:--action='ACTTYPE' ['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. +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'. -* 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 available action types are: -* The dynamic value of an event field is captured by using its name as a C - identifier. +Notify:: + Synopsis: ++ +[verse] +option:--action=**notify** [nloption:--rate-policy='POLICY'] +{nbsp} + -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`. +Sends a notification through the notification +mechanism of the session daemon (see man:lttng-session(8)). + -An enumeration field's value is an integer. +The session daemon sends details about the condition evaluation along +with the notification. + -When the capture's field does not exist, the capture expression -evaluates to `unavailable`. +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). + -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. +Start a tracing session:: + Synopsis: + -When the expression's statically-known context field does not exist, -the capture expression evaluates to `unavailable`. +[verse] +option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -Examples: `$ctx.prio`, `$ctx.preemptible`, -`$ctx.perf:cpu:stalled-cycles-frontend`. +Starts the tracing session named 'SESSION' like man:lttng-start(1) +would. + -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. +If no tracing session has the name 'SESSION' when LTTng is ready to +execute the action, LTTng does nothing. ++ +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). +Stop a tracing session:: + Synopsis: ++ +[verse] +option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] +{nbsp} + -When the expression's application-specific context field does not exist, -the capture expression evaluates to `unavailable`. +Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. + -Example: `$app.server:cur_user`. +If no tracing 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:: + 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. ++ +If no tracing 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:: + 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 tracing 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 +(see man:lttng-create(1)). ++ +If no tracing 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. -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. +Specifier +~~~~~~~~~ +option:--condition='CONDTYPE':: + Introductory option for a condition specifier of type 'CONDTYPE'. + -If a trigger with the specified 'ID' already exists, the trigger -creation will fail. +See the <> section above to learn more. -option:--fire-every 'N':: - Execute the trigger's actions every 'N' times the condition is met. +option:--action='ACTTYPE':: + Introductory option for an action specifier of type 'ACTTYPE'. ++ +See the <> section above to learn more. -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[] @@ -202,6 +308,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- +man:lttng(1), +man:lttng-concepts(7), man:lttng-list-triggers(1), -man:lttng-remove-trigger(1), -man:lttng(1) +man:lttng-remove-trigger(1)