LTTNG-START(1)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

✨ NAME ✨

lttng-start — start one or more LTTng recording sessions 💖

okay so real quick, this is the manual page for lttng-start from the LTTng Manual, and bestie it is so much less scary than it looks. let's go 🫶

🌸 SYNOPSIS 🌸

lttng [GENERAL OPTIONS] start [--all | --glob=PATTERN | SESSION]

like literally that's it. that's the whole shape of it. ✨

💅 DESCRIPTION 💅

the lttng start command starts one or more recording sessions — translation: it activates the LTTng tracers for whatever sessions you point it at.

here's the vibe check on which sessions get started, depending on what you give it:

  • With the SESSION argument — it starts the recording session named SESSION.
  • With the --glob=PATTERN option — it starts the recording sessions whose name matches the globbing pattern PATTERN.
  • With the --all option — it starts all the recording sessions of the connected session daemon for your Unix user, or for all users if your Unix user is root, exactly as listed in the output of lttng list (peep lttng-list(1)).

also: check the “Session daemon connection” section of lttng(1) to learn how a user application connects to a session daemon. iykyk 🧚

  • Otherwise — it starts the current recording session.

see lttng-concepts(7) if you wanna learn more about the current recording session.

and yeah, lttng-concepts(7) is also where you go to learn more about recording sessions in general. obsessed with that page honestly 👑

🚨 ok important: the recording session(s) you select must be inactive (stopped). a recording session is inactive on creation (see lttng-create(1)).

also fun fact: a start-session trigger action can start a recording session too (see lttng-add-trigger(1)). so many ways to slay ✨

there's a whole “EXAMPLES” section below if you want usage examples, no cap.

and when you're done and you wanna stop one or more active recording sessions? that's the lttng-stop(1) command's whole job. 💀

🌈 OPTIONS 🌈

these are the general options — see lttng(1) for GENERAL OPTIONS. 💜

🎀 Program information 🎀

  • -h, --help — show help. this option tries to launch /usr/bin/man to view this manual page. you can override the manual pager path with the LTTNG_MAN_BIN_PATH environment variable. so fancy ✨
  • --list-options — list the available command options and quit. short, sweet, iconic.
  • -a, --all — start all the recording sessions of your Unix user, or of all users if your Unix user is root, as listed in the output of lttng-list(1). it's giving everything, everywhere 🌸
  • -g PATTERN, --glob=PATTERN — start the recording sessions of which the globbing pattern PATTERN matches the name.

and in PATTERN, the * character means “match anything”. if you want to match a literal * character, you write \*. that's the whole trick bestie 🪄

💀 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. one strike and we're out, periodt.
  • LTTNG_HOME — path to the LTTng home directory.

defaults to $HOME. 🔥 super useful when the Unix user running the commands has a non-writable home directory.

  • LTTNG_LIST_LEGACY — set to 1 to use the legacy output format (LTTng 2.14 and earlier) for the lttng-list(1) command instead of the modern output format.

heads up: the legacy output doesn't show anything related to features introduced after LTTng 2.14. so it's giving nostalgia, not completeness 💅

  • 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. pick your own pager, main character energy 👑
  • LTTNG_NO_UTF_8 — set to 1 to NOT emit multi-byte UTF-8 sequences, even if the locale claims to support it. (yes the double negative is on purpose, we don't make the rules 😭)
  • 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.

note that the --sessiond-path general option overrides this environment variable. so the flag wins, always ✨

  • LTTNG_TERM_COLOR — controls when to emit terminal SGR codes in the output.

the NO_COLOR environment variable overrides this one. 🎨

it's one of:

  • auto (default) — only emit SGR codes when the standard output is connected to a color-capable terminal.
  • always — always emit SGR codes. 🌈
  • never — never emit SGR codes. 💀
  • NO_COLOR — if set and not empty, then it's equivalent to setting LTTNG_TERM_COLOR to never.

see NO_COLOR at https://no-color.org/ to learn more. 🌸

🍓 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). the lttng-create(1) and lttng-set-session(1) commands 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. Start the current recording session.

$ lttng start

Example 2. Start a specific recording session.

$ lttng start my-session

Example 3. Start all the recording sessions.

see the --all option. 👑

$ lttng start --all

Example 4. Start all the recording sessions of which the name ends with foo.

see the --glob option. 🌈

$ lttng start --glob='*foo'

🧚 RESOURCES 🧚

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 file for details — https://github.com/lttng/lttng-tools/blob/master/LICENSE. 📜

🌸 THANKS 🌸

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

also thanks to the Ericsson teams working on tracing, who helped us greatly with detailed bug reports and unusual test cases. literal legends, no cap 💜

✨ SEE ALSO ✨

lttng(1), lttng-add-trigger(1), lttng-create(1), lttng-enable-event(1), lttng-stop(1), lttng-concepts(7)

okay that's the whole page bestie 💖 this was LTTng 2.15.1, dated 1 April 2025, and yeah it's LTTNG-START(1) all day. go start those sessions, you've got this 🎀✨💅

📦 where this page comes from