lttng-add-trigger - Man Page

Synopsis:

--condition=CONDTYPE [CONDARGS]

A condition specifier is the --condition option, which specifies the type of condition CONDTYPE, followed, depending on CONDTYPE, with zero or more arguments CONDARGS.

The available condition types are:

event-rule-matches

Synopsis:

--condition=event-rule-matches [--capture=CDESCR]... ERSPEC
 

An event-rule-matches condition is considered satisfied when the event rule specified with ERSPEC matches an event.

See lttng-event-rule(7) to learn how to specify an event rule (ERSPEC part).

Capture event record and context fields with one or more --capture options (see the “Capture descriptor” 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 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.

A capture descriptor is a textual expression which describes how to read an event record or context field.

The argument of a --capture option, when using an “event rule matches” condition specifier (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.

$ctx.NAME

A statically-known context field named NAME.

List the available statically-known context field names with 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 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].

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:

• 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.

Synopsis:

--action=ACTTYPE [ACTARGS]

An action specifier is the --action option, which specifies the type of action ACTTYPE, followed, depending on ACTTYPE, with zero or more arguments ACTARGS.

The available action types are:

Notify

Synopsis:

--action=notify [--rate-policy=POLICY]
 

Sends a notification through the notification mechanism of the session daemon (see lttng-sessiond(8)).

The session daemon sends details about the condition evaluation along with the notification.

As of LTTng 2.13.14, you can write a C/C++ program to receive LTTng notifications (see the liblttng-ctl C headers).

See below for the --rate-policy option.

Start a recording session

--action=start-session SESSION [--rate-policy=POLICY]
 

Stop a recording session

--action=stop-session SESSION [--rate-policy=POLICY]
 

Rotate a recording session

--action=rotate-session SESSION [--rate-policy=POLICY]
 

Take a recording session snapshot

--action=snapshot-session SESSION [--rate-policy=POLICY]
 

Common action options (as of LTTng 2.13.14):

--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 A first increments the execution request count C of A. An execution request can then become an actual execution when C satisfies the rate policy of A.

POLICY is one of:

once-after:COUNT

Only execute A when C is equal to COUNT.

In other words, execute A a single time after COUNT execution requests.

every:COUNT

Only execute A when C is a multiple of COUNT.

In other words, execute A every COUNT execution requests.

COUNT must be an integer greater than 0.

As of LTTng 2.13.14, you can use this option with any action type, but new action types in the future may not support it.

--name=NAME

Set the unique name of the trigger to add to NAME instead of the add-trigger command automatically assigning one.

--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.

--condition=CONDTYPE

Introductory option for a condition specifier of type CONDTYPE.

See the “Condition specifier” section above to learn more.

--action=ACTTYPE

Introductory option for an action specifier of type ACTTYPE.

See the “Action specifier” section above to learn more.

-h,  --help

Show help.

This option attempts to launch /usr/bin/man to view this manual page. Override the manual pager path with the LTTNG_MAN_BIN_PATH environment variable.

--list-options

List available command options and quit.