Message-ID: <9a161f81-a02a-4196-9106-9c645664157f@efficios.com>
Date: Wed, 16 Apr 2025 18:08:27 -0400
From: Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
To: lttng-dev <lttng-dev@...ts.lttng.org>
Cc: Diamon discuss <diamon-discuss@...ts.linuxfoundation.org>,
 linux-trace-users <linux-trace-users@...r.kernel.org>, lwn@....net,
 linux-kernel <linux-kernel@...r.kernel.org>
Subject: [RELEASE] LTTng 2.14.0-rc1 - Orbitales - Linux kernel and user space
 tracer

Hi everyone,

We're excited to share the first release candidate of LTTng 2.14,
codenamed Orbitales!

Four years in the making, this release introduces a range of new
features, improvements, and experimental capabilities. The release
candidate phase will run for a few weeks, giving the community time
to test and provide feedback before the final version ships.

WHAT'S NEW?
━━━━━━━━━━━
New features and changes in LTTng 2.14:

General:
     • User space channels now have a _buffer allocation policy_ which
       specifies whether LTTng tracers allocate ring buffers per CPU
       (what you've always known) or per channel.

       The buffering scheme term now refers to the ownership model
       (system, user, or process) and the allocation policy together.

       The new per-channel allocation policy means each user/process
       (depending on the buffer ownership model), instead of each CPU of
       each user/process, gets its own ring buffer.

     • User space tracing now supports the Apache Log4j 2 tracing domain
       in addition to the existing support for Apache log4j 1.2.

     • LTTng 2.14 brings _experimental_ support of
       Common Trace Format 2 (CTF 2) [1] for both the user space and kernel
       tracers.

       CTF 2 output isn't enabled by default and is intended solely for
       preview and feedback purposes: having an experimental support will
       allow users to test and evaluate CTF 2 until we make it the
       default output format.

Tracing control:
     • The new `--buffer-allocation` option of the
       lttng-enable-channel(1) command can set the buffer allocation
       policy of the channel to create.

       The default `per-cpu` value is what you've always known while the
       new `per-channel` value is available for user space channels.

     • The new `--buffer-ownership` option of the `enable-channel`
       command of the `lttng` CLI tool replaces the `--buffers-global`,
       `--buffers-uid`, and `--buffers-pid` options (now deprecated).

     • The `enable-channel` command of the `lttng` CLI tool, when
       creating a user space channel with the usual per-CPU buffer
       allocation policy, automatically adds a `cpu_id` context field
       which, as of LTTng 2.14, you cannot remove. This has always been
       the case and remains true, but `cpu_id` is now an officially
       supported context field.

       Knowing this, with the new per-channel buffer allocation policy,
       the `enable-channel` command doesn't add the `cpu_id` context
       field: add it afterwards with the lttng-add-context(1) command if
       needed, for example:

           $ lttng add-context -u --channel=my-channel --type=cpu_id

     • Everywhere the Apache log4j 1.2 `--log4j` option or
       `log4j:logging` option value is available with the `lttng` CLI
       tool, you may now use resp. `--log4j2` and `log4j2:logging` to
       target the new Apache Log4j 2 [2] tracing domain.

     • The `liblttng-ctl` C API is updated to support the new features:

       ‣ Set and get the buffer allocation policy of a channel with
         `lttng_channel_set_allocation_policy()`
         and `lttng_channel_get_allocation_policy()`.

       ‣ Add the `cpu_id` context field to a channel with the
         `LTTNG_EVENT_CONTEXT_CPU_ID` enumerator when
         calling `lttng_add_context()`.

       ‣ Apache Log4j 2 functions and enumerators are available
         everywhere there are Apache Log4j 2 equivalents:

         ⁃ `LTTNG_DOMAIN_LOG4J2`
         ⁃ `LTTNG_EVENT_RULE_TYPE_LOG4J2_LOGGING`
         ⁃ `enum lttng_loglevel_log4j2`
         ⁃ `lttng_event_rule_log4j2_logging_create()`
         ⁃ `lttng_event_rule_log4j2_logging_get_filter()`
         ⁃ `lttng_event_rule_log4j2_logging_get_log_level_rule()`
         ⁃ `lttng_event_rule_log4j2_logging_get_name_pattern()`
         ⁃ `lttng_event_rule_log4j2_logging_set_filter()`
         ⁃ `lttng_event_rule_log4j2_logging_set_log_level_rule()`
         ⁃ `lttng_event_rule_log4j2_logging_set_name_pattern()`

       ‣ Get the status of the Linux kernel tracer
         with `lttng_get_kernel_tracer_status()`.

       ‣ Get the shared memory directory path of a recording session
         with `lttng_get_session_shm_path_override()`.

     • Set the `LTTNG_EXPERIMENTAL_FORCE_CTF_2` environment variable to
       `1` when starting `lttng-sessiond` to enable the experimental
       CTF 2 [1] output format.

       With this setting, all the recording sessions which the session
       daemon manages produce CTF 2 traces. As of LTTng 2.14, this is not
       a per-session configuration.

       The produced CTF 2 traces are expected to be semantically
       equivalent to what the tracers would have produced without
       `LTTNG_EXPERIMENTAL_FORCE_CTF_2` set to `1` (CTF 1.8).

       ┌──────────────────────────────────────────────────────────────┐
       │ NOTE: A client of a session daemon started with the          │
       │ `LTTNG_EXPERIMENTAL_FORCE_CTF_2` environment variable set to │
       │ `1` cannot create:                                           │
       │                                                              │
       │ ‣ A network streaming mode recording session.                │
       │                                                              │
       │ ‣ A snapshot mode recording session where you send the trace │
       │   data over the network.                                     │
       │                                                              │
       │ ‣ A live mode recording session.                             │
       └──────────────────────────────────────────────────────────────┘

     • The `--all` option of the lttng-start(1) and lttng-stop(1)
       commands is now available to start/stop _all_ the
       recording sessions.

     • The `--glob` option of the `start`, and `stop`, and
       lttng-destroy(1) commands is now available to start/stop/destroy
       recording sessions of which some globbing pattern matches
       the name.

     • New lttng-relayd(8) options are available to help control
       its process:

       `--dynamic-port-allocation`::
           Let the operating system assign the control, data, and live
           ports if their respective option is missing (`--control-port`,
           `--data-port`, and `--live-port`) or if their port number part
           is `0`.

           With this option, `lttng-relayd` writes the `control.port`,
           `data.port`, and `live.port` files, as needed, to its runtime
           and configuration directory (`$LTTNG_HOME/.lttng`).

       `--pid-file`:
           Write the process ID (PID) of the `lttng-relayd` process to
           some file (like the `--pidfile` option of lttng-sessiond(8)).

       `--sig-parent`:
           Send the `USR1` signal to the parent process to notify
           readiness (like the `--sig-parent` option
           of `lttng-sessiond`).

     • You can now override the path of the directory where
       `lttng-sessiond` places special files for user space tracing
       applications with the `LTTNG_UST_CTL_PATH` environment variable.

       See lttng-sessiond(8).

     • You can now override the path of the directory where
       `lttng-sessiond` places its control files with the `LTTNG_RUNDIR`
       environment variable.

       See lttng-sessiond(8).

User space tracing specifics:
     • You can now override the path of the directory where a user
       application instrumented with liblttng-ust looks for special
       registration and control files of `lttng-sessiond` with the
       `LTTNG_UST_APP_PATH` environment variable.

       See lttng-ust(3).

     • You can now override the policy used to populate shared memory
       pages within the instrumented application with the
       `LTTNG_UST_MAP_POPULATE_POLICY` environment variable.

       See lttng-ust(3).

     • We improved the memory usage of lttng_ust_tracef()
       and lttng_ust_tracelog().

Kernel tracing specifics:
     The minimum supported Linux kernel version is now 4.4 instead
     of 3.0.

VERSION NAME
━━━━━━━━━━━━
This release is named after "Orbitales", a bold creation from
Noctem Artisans Brasseurs in Québec City.

Pitch black and dense—one team member compared the color to used motor oil—this
beer offers an intriguing sensory experience. Aged in wood casks, it delivers
rich aromas and flavors of blackberry as well as a hint of acidity. There’s no
head to speak of, but a whisper of blue cheese funk lingers just enough to keep
you curious.

IMPORTANT LINKS
━━━━━━━━━━━━━━━
LTTng tarball:
     <https://lttng.org/files/lttng-tools/lttng-tools-2.14.0-rc1.tar.bz2>
     <https://lttng.org/files/lttng-ust/lttng-ust-2.14.0-rc1.tar.bz2>
     <https://lttng.org/files/lttng-modules/lttng-modules-2.14.0-rc1.tar.bz2>

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

Mailing list for support and development:
     <https://lists.lttng.org/>

IRC channel:
     `#lttng` on `irc.oftc.net`

Bug tracker:
     <https://bugs.lttng.org/projects/lttng/>

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

Continuous integration:
     <https://ci.lttng.org/view/LTTng-tools/>
     <https://ci.lttng.org/view/LTTng-ust/>
     <https://ci.lttng.org/view/LTTng-modules/>

Code review:
     <https://review.lttng.org/q/project:lttng-tools>
     <https://review.lttng.org/q/project:lttng-ust>
     <https://review.lttng.org/q/project:lttng-modules>

REFERENCES
━━━━━━━━━━
[1]: https://diamon.org/ctf/
[2]: https://logging.apache.org/log4j/2.x/index.html

-- 
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com

Powered by blists - more mailing lists