Release Notes

This release is named after Nordicité, the product of a collaboration between Champ Libre and Boréale. This farmhouse IPA is brewed with Kveik yeast and Québec-grown barley, oats and juniper branches. The result is a remarkable fruity hazy golden IPA that offers a balanced touch of resinous and woodsy bitterness.

The most notable features of this new release are:

• Event-rule matches condition triggers and new actions,
• Notification payload capture,
• vtracef and vtracelog (LTTng-UST),
• Add user space time namespace context (LTTng-UST and LTTng-modules).

Read on for a short description of each of the new features and the links to this release.

Note on LTTng-UST backward compatibility

• soname major version change

  This release changes the LTTng-UST soname major from 0 to 1.

  The event notifier (triggers using an event-rule-matches condition) functionality required a significant rework of public data structures which should never have been made public in the first place.

  Bumping the soname major to 1 will require applications and tracepoint providers to be rebuilt against an updated LTTng-UST.

  Old applications and tracepoint providers linked against libraries with the 0 major soname can co-exist on the same system.

• Building probe providers using a C++ compiler requires C++11

• API namespace-ing

  The LTTng-UST API is now systematically namespaced under lttng_ust_* (e.g tracepoint() becomes lttng_ust_tracepoint()).

  However, the un-namespaced names are still exposed to maintain API compatibility.

What's New?

Event-rule matches condition trigger and new actions

Expanding the trigger infrastructure and making it usable through the lttng client was the core focus of this release.

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.

Since their introduction as part of LTTng 2.10, new conditions and actions were added to make this little-known mechanism more flexible.

For instance, before this release, triggers supported the following condition
types:

• Buffer usage exceeded a given threshold,
• Buffer usage went under a configurable threshold,
• A session rotation occurred,
• A session rotation completed.

A notify action could be used to send a notification to a third party applications whenever those conditions were met.

This made it possible, for instance, to disable certain event rules if the tracing buffers were almost full. It could also be used to wait for session
rotations to be completed to start processing the resulting trace chunk archives as part of various post-processing trace analyses.

This release introduces a new powerful condition type: event-rule matches.

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 enable-event command.

While this is not intended as a general replacement for the existing high-throughput tracing facilities, this makes it possible for an application
to wait for a very-specific event to occur and take action whenever it occurs.
The purpose of event-rule matches triggers is to react quickly to an event without the delay introduced by buffering.

For example, the following command will create a trigger that emits a notification whenever the openat system call is invoked with the
/etc/passwd filename argument.

$ lttng add-trigger
    --condition event-rule-matches
      --domain=kernel
      --type=syscall
      --name="openat"
    --action notify

New actions were also introduced as part of this release:

• Start session

  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.

• Stop session

  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.

• Rotate session

  This action causes the LTTng session daemon to rotate the session with the given name. See 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.

• Snapshot session

  This action causes the LTTng session daemon to take a snapshot of the
  session with the given name. See 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.

These new actions can also be combined together. For instance, the following
trigger will stop my_session, record a snapshot of my_session, and notify
any listening application when /etc/passwd is opened:

$ lttng add-trigger
    --condition event-rule-matches
      --domain kernel
      --type syscall
      --name "openat"
      --filter 'filename == "/etc/passwd"'
    --action stop-session my_session
    --action snapshot-session my_session
    --action notify

For more information, see the following manual pages:

• lttng-add-trigger(1),
• lttng-remove-trigger(1),
• lttng-list-triggers(1).

Notification payload capture

The new event-rule matches condition type also supports captures. Captures allow event record and context fields to be captured when an event-rule matches condition is satisfied.

The captured field values are made available in the evaluation object of the notifications transmitted to listening applications.

Capture descriptors can be specified using a syntax reminiscent of the one used by the filter expressions.

The following example will capture a process's name and the filename argument of all openat() system calls:

$ lttng add-trigger
    --condition event-rule-matches
      --domain kernel
      --type syscall
      --name "openat"
      --capture "filename"
      --capture "$ctx.procname"
    --action notify

See the lttng-add-trigger(1) manual page for more information.

vtracef and vtracelog (LTTng-UST)

New versions of the tracef() and tracelog() tracing helpers accepting variable argument lists are introduced as vtracef() and vtracelog().

See the tracef(3) and tracelog(3) manual pages for more information.

Add time namespace context (LTTng-UST and LTTng-modules)

It is now possible to add the time namespace of a process as a context to channels (time_ns) using the add-context command.

See the time_namespaces(7) manual page for more information.