Ubuntu Manpage: lttng-add-trigger - Add an LTTng trigger

Provided by: lttng-tools_2.13.9-1build1_amd64

NAME

       lttng-add-trigger - Add an LTTng trigger

SYNOPSIS

       lttng [GENERAL OPTIONS] add-trigger [--name=NAME] [--owner-uid=UID]
             --condition=CONDTYPE [CONDARGS]
             --action=ACTTYPE [ACTARGS] [--action=ACTTYPE [ACTARGS]]...

DESCRIPTION

The lttng add-trigger command creates and adds an LTTng trigger to the connected session
daemon (see lttng-sessiond(8)).

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

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 --owner-uid option.

Specify the condition of the trigger to add with a condition specifier and its actions
with one or more action specifiers. The order of the action specifiers is significant:
LTTng attempts to execute the actions of a firing trigger in this order.

See the “EXAMPLES” section below for usage examples.

List the triggers of your Unix user, or of all users if your Unix user is root, with the
lttng-list-triggers(1) command.

Remove a trigger with the lttng-remove-trigger(1) command.

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

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

Action specifier
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-session(8)).

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

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