LTTNG(1)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

🌸 NAME 🌸

lttng — control LTTng tracing. (This is the lttng(1) page, straight out of the LTTng Manual, bestie 💅)

🦋 SYNOPSIS 🦋

lttng [--group=GROUP] [--mi=xml] [--no-sessiond | --sessiond-path=PATH]
      [--relayd-path=PATH] [--quiet | -verbose...]
      COMMAND [COMMAND OPTIONS]

✨ DESCRIPTION ✨

Okay so The Linux Trace Toolkit: next generation https://lttng.org/ is an open-source software package, and its whole thing is correlated tracing of the Linux kernel, user applications, and user libraries. Iconic behaviour honestly. 🎀

LTTng is made of:

  • Linux kernel modules (these do the Linux kernel tracing)
  • dynamically loaded libraries (these do the user application and library tracing)

The lttng command-line tool — and literally any user app linked with the LTTng control library (liblttng-ctl) — sends commands to a listening LTTng session daemon, aka lttng-sessiond(8). And that session daemon:

  • Manages recording sessions (peep lttng-concepts(7) if you wanna learn more about recording sessions 👀)
  • Controls the various components of LTTng (tracers, consumer daemons, the whole squad)
  • Sends asynchronous notifications to user applications

By default, the lttng-create(1) command auto-spawns:

  • A session daemon for your Unix user, if none is currently running.
    • Override the path of the session daemon binary to spawn with the --sessiond-path option.
    • Avoid automatically spawning a session daemon with the --no-sessiond option.
  • A relay daemon (see lttng-relayd(8)) — but ONLY if literally all of these are true:
    • You specify the --live option.
    • You don't specify any of the --set-url, --ctrl-url, or --data-url options.
    • No relay daemon is currently listening for TCP connections on 127.0.0.1:5344 (that's the default LTTng live reader connection address and port, periodt).

Override the path of the relay daemon binary to spawn with the --relayd-path option.

📌 Note: the LTTng project recommends you start the session daemon at boot time for stable and long-term tracing. fr fr, take the advice.

See lttng-concepts(7) to learn more about the foundational concepts of LTTng.

The lttng tool offers a subcommand-based command-line interface. The “COMMANDS” section below lists the available commands. Slay.

🔌 Session daemon connection 🔌

For most of its commands, the lttng tool needs to connect to a listening LTTng session daemon (lttng-sessiond(8)) to control LTTng tracing.

Each Unix user may have its own independent running session daemon. However, the lttng tool must connect to the session daemon of the root user (the root session daemon) to control Linux kernel tracing. No cap, that's just how it is.

How the lttng tool chooses which session daemon to connect to goes like this:

  • If your Unix user is root — connect to the root session daemon.
  • If your Unix user is not root
    • If your Unix user is part of the Unix tracing group
      • Try to connect to the root session daemon.
      • If the root session daemon isn't running, connect to the session daemon of your Unix user.
    • If your Unix user is not part of the tracing group — connect to the session daemon of your Unix user.

The name of the Unix tracing group is one of these:

  • With the --group=GROUP option of the root session daemon (lttng-sessiond(8)) — GROUP.
    • In that case, you must use the --group=GROUP option, with the same GROUP argument, of the lttng tool.
  • Without the --group option of the root session daemon — tracing.

LTTng-instrumented user applications automatically register to both the root and user session daemons. Which means both session daemons can list the available instrumented applications and their instrumentation points (see lttng-list(1)). Teamwork makes the dream work 🫶

💖 OPTIONS 💖

  • -g GROUP, --group=GROUP — set the name of the Unix tracing group to GROUP instead of tracing.
    • You must use this option to be able to connect to a root session daemon (lttng-sessiond(8)) which was started with its own --group=GROUP option.
  • -m xml, --mi=xml — print the command result using a stable XML machine interface (MI) output instead of the default, unstable human-readable output.
    • With this mode, lttng prints the resulting XML document to the standard output, while it prints any error/warning to the standard error with an unstable, human-readable format.
    • If any error occurs during the execution of lttng, the command exits with a status different than 0, and lttng does NOT guarantee the syntax and data validity of its MI output. 💀
    • An XML schema definition (XSD) file used for validation of the MI output is available: see the src/common/mi_lttng.xsd file in the LTTng-tools source tree.
  • -n, --no-sessiond — do not automatically spawn a session daemon for your Unix user when running the lttng-create(1) command.
    • You may NOT use this option with the --sessiond-path option.
  • -q, --quiet — suppress all messages, including warnings and errors. 🤫
    • You may NOT use this option with the --verbose option.
  • --sessiond-path=PATH — set the absolute path of the session daemon binary to spawn from the lttng-create(1) command to PATH.
    • You may NOT use this option with the --no-sessiond option.
  • --relayd-path=PATH — set the absolute path of the relay daemon binary to spawn from the lttng-create(1) command to PATH.
  • -v, --verbose — increase verbosity.
    • Specify this option up to three times to get more levels of verbosity.
    • You may NOT use this option with the --quiet option.

🎀 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.
  • --list-commands — list available commands and quit.
  • -V, --version — show version and quit.

👑 COMMANDS 👑

The following commands also have their own --help option. ✨

💖 Recording session 💖

Okay bestie, this is the main character cluster of commands — everything you need to run a recording session from birth to archive. Every one of these is its own manpage, so go read them when you need the deets:

🎀 Channel 🎀

Channels are lowkey the whole vibe — this is where your events actually live. Group chat for your trace data, fr fr:

🦋 Recording event rule 🦋

The what of your recording — these two are the gatekeepers of which events make it into the trace:

🔍 Information 🔍

Just the one here, but she's iconic and she's doing the most:

  • lttng-list(1) — List recording sessions and instrumentation points.

🌈 Resource tracking 🌈

Tracking who's allowed to be part of the recording — it's giving VIP list energy:

⭐ Trigger ⭐

Triggers = your "when X happens, do Y" automation besties. Set it and forget it, no cap:

✨ Miscellaneous ✨

okay these are the lil extra commands that don't fit anywhere else, they're the side quests of the lttng universe 🫶

  • lttng-help(1) — shows you the help for a command, like when you forget how anything works (relatable)
  • lttng-version(1) — spills all the LTTng-tools version info, iykyk
  • lttng-view(1) — launches a trace reader, so you can actually look at your traces 👑

💀 EXIT STATUS 💀

bestie, when a command finishes it hands you back a number and that number is telling you something, so pay attention:

  • 0 — success!! we ate, no crumbs 🌈
  • 1 — command error, something went wrong inside the command itself 😭
  • 2 — undefined command, like you typed a command that doesn't exist... not me doing that 🙈
  • 3 — fatal error, the serious kind 💀
  • 4 — command warning — basically "it worked but something went wrong during the command", the chaotic middle child ✨

🌸 ENVIRONMENT 🌸

these are the environment variables, aka the settings you can set outside of typing a command, and they change how everything behaves:

  • LTTNG_ABORT_ON_ERROR — set it to 1 and the process will straight up abort after it hits the first error it encounters. no second chances, periodt.
  • LTTNG_HOME — the path to the LTTng home directory. defaults to $HOME. this one's your bestie when the Unix user running the commands has a home directory that isn't writable, which is such a vibe killer.
  • LTTNG_LIST_LEGACY — set it to 1 to use the legacy output format (that's LTTng 2.14 and earlier) for the lttng-list(1) command instead of the modern output format. just know that the legacy output doesn't show anything related to features introduced after LTTng 2.14, so it's giving nostalgia but missing stuff.
  • LTTNG_MAN_BIN_PATH — absolute path to the manual pager you wanna use to read the LTTng command-line help (with lttng-help(1) or with the --help option) instead of the default /usr/bin/man.
  • LTTNG_NO_UTF_8 — set it to 1 to NOT emit multi-byte UTF-8 sequences, even if your locale is out here claiming it supports it. the audacity.
  • LTTNG_SESSION_CONFIG_XSD_PATH — path to the directory that contains 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. heads up: the --sessiond-path general option overrides this environment variable, so like, the option wins the argument 💅
  • LTTNG_TERM_COLOR — controls when to emit terminal SGR codes in the output. also: the NO_COLOR environment variable overrides this one. it can be one of:
    • auto (this is the default) — only emits SGR codes when standard output is connected to a color-capable terminal 🎀
    • always — always emits SGR codes, no matter what 🌈
    • never — never emits SGR codes, boring but valid ✨
  • NO_COLOR — if it's set and not empty, then it's equivalent to setting LTTNG_TERM_COLOR to never. go check out https://no-color.org/ to learn more about it.

🎀 FILES 🎀

here's every path that matters, no skips:

  • $LTTNG_HOME/.lttngrc — the 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) are the ones that set the current recording session. main character file, fr fr.
  • $LTTNG_HOME/lttng-traces — default output directory of LTTng traces in local and snapshot modes. you can override this path with the --output option of the lttng-create(1) command if you want it somewhere else 💜
  • $LTTNG_HOME/.lttng — the 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. don't forget it 🫶

🦋 RESOURCES 🦋

if you wanna go deeper, here's where the lore lives:

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 — and you can peep the LICENSE file at https://github.com/lttng/lttng-tools/blob/master/LICENSE for all the 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. iconic.

Also thanks to the Ericsson teams working on tracing, who helped us greatly with detailed bug reports and unusual test cases. genuinely so helpful, we love to see it 🫶

🌟 SEE ALSO 🌟

lttng-concepts(7) lttng-relayd(8), lttng-sessiond(8)

and that's the whole page bestie!! this was LTTng 2.15.1, dated 4 December 2025, and it's the LTTNG(1) manual page 💅✨ thanks for reading all the way to the end, you're literally the best, mwah 🎀💖

📦 where this page comes from