Provided by: lttng-tools_2.13.4-1build1_amd64 bug

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.4, 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
           Synopsis:

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

           Starts the recording session named SESSION like lttng-start(1) would.

           If no recording session has the name SESSION when LTTng is ready to execute the
           action, LTTng does nothing.

           See below for the --rate-policy option.

       Stop a recording session
           Synopsis:

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

           Stops the recording session named SESSION like lttng-stop(1) would.

           If no recording session has the name SESSION when LTTng is ready to execute the
           action, LTTng does nothing.

           See below for the --rate-policy option.

       Rotate a recording session
           Synopsis:

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

           Archives the current trace chunk of the recording session named SESSION like lttng-
           rotate(1) would.

           If no recording session has the name SESSION when LTTng is ready to execute the
           action, LTTng does nothing.

           See below for the --rate-policy option.

       Take a recording session snapshot
           Synopsis:

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

           Takes a snapshot of the recording session named SESSION like 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 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 --rate-policy option.

       Common action options (as of LTTng 2.13.4):

       --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.4, you can use this option with any action type, but new action types
           in the future may not support it.

OPTIONS

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

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

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

EXIT STATUS

       0
           Success

       1
           Command error

       2
           Undefined command

       3
           Fatal error

       4
           Command warning (something went wrong during the command)

ENVIRONMENT

       LTTNG_ABORT_ON_ERROR
           Set to 1 to abort the process after the first error is encountered.

       LTTNG_HOME
           Path to the LTTng home directory.

           Defaults to $HOME.

           Useful when the Unix user running the commands has a non-writable home directory.

       LTTNG_MAN_BIN_PATH
           Absolute path to the manual pager to use to read the LTTng command-line help (with
           lttng-help(1) or with the --help option) instead of /usr/bin/man.

       LTTNG_SESSION_CONFIG_XSD_PATH
           Path to the directory containing the session.xsd recording session configuration XML
           schema.

       LTTNG_SESSIOND_PATH
           Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from
           the lttng-create(1) command.

           The --sessiond-path general option overrides this environment variable.

FILES

       $LTTNG_HOME/.lttngrc
           Unix user’s LTTng runtime configuration.

           This is where LTTng stores the name of the Unix user’s current recording session
           between executions of lttng(1).  lttng-create(1) and lttng-set-session(1) set the
           current recording session.

       $LTTNG_HOME/lttng-traces
           Default output directory of LTTng traces in local and snapshot modes.

           Override this path with the --output option of the lttng-create(1) command.

       $LTTNG_HOME/.lttng
           Unix user’s LTTng runtime and configuration directory.

       $LTTNG_HOME/.lttng/sessions
           Default directory containing the Unix user’s saved recording session configurations
           (see lttng-save(1) and lttng-load(1)).

       /etc/lttng/sessions
           Directory containing the system-wide saved recording session configurations (see
           lttng-save(1) and lttng-load(1)).

       Note
           $LTTNG_HOME defaults to the value of the HOME environment variable.

EXAMPLES

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

               $ lttng add-trigger --condition=event-rule-matches \
                                   --type=syscall:entry \
                                   --name='exec*' --action=notify

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

           The order of the --action options below is significant.

               $ 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 lttng-concepts(7) to learn more about recording sessions and rotations.

       Example 3. 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 --name option.

               $ lttng add-trigger --name=my-trigger \
                                   --condition=event-rule-matches \
                                   --type=python --name=my-logger \
                                   --action=snapshot-session my-session

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

               # lttng add-trigger --owner-uid=$(id --user mireille) \
                                   --condition=event-rule-matches \
                                   --type=kernel --name='sched*' \
                                   --action=notify

       Example 5. Add an “event rule matches” trigger with a notification action to be executed
       every 10 times.

           The event-rule-matches trigger condition below specifies an event rule which matches
           all user space tracepoint events.

           See the --rate-policy option above.

               $ lttng add-trigger --condition=event-rule-matches \
                                   --type=user --action=notify \
                                   --rate-policy=every:10

       Example 6. Add an “event rule matches” trigger with a recording session starting action to
       be executed a single time after 40 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 3.

           See the --rate-policy option above.

               $ lttng add-trigger --condition=event-rule-matches \
                                   --type=syscall --filter='fd < 3' \
                                   --action=start-session my-session \
                                   --rate-policy=once-after:40

RESOURCES

       •   LTTng project website <https://lttng.org>

       •   LTTng documentation <https://lttng.org/docs>

       •   LTTng bug tracker <https://bugs.lttng.org>

       •   Git repositories <https://git.lttng.org>

       •   GitHub organization <https://github.com/lttng>

       •   Continuous integration <https://ci.lttng.org/>

       •   Mailing list <https://lists.lttng.org/> for support and development: lttng-
           dev@lists.lttng.org

       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net

COPYRIGHT

       This program is part of the LTTng-tools project.

       LTTng-tools is distributed under the GNU General Public License version 2
       <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE
       <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

THANKS

       Special thanks to Michel Dagenais and the DORSAL laboratory
       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey.

       Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed
       bug reports and unusual test cases.

SEE ALSO

       lttng(1), lttng-list-triggers(1), lttng-remove-trigger(1), lttng-concepts(7)