LTTNG-ENABLE-EVENT(1)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

💖 lttng-enable-event(1) 💖

okay bestie, grab a snack because we're in the LTTng Manual and this page is the page for making events happen. it's lttng-enable-event, it's iconic, it's giving main character energy, and by the end of this you're gonna be creating recording event rules like it's nothing 🫶

✨ NAME ✨

lttng-enable-event — create or enable LTTng recording event rules 🌸

🌈 SYNOPSIS 🌈

okay so there are four flavours of this command depending on what kind of thing you're trying to catch. here they all are, no skips, fr fr.

To create or enable one or more recording event rules matching Linux kernel tracepoint or system call events: 👑

lttng [GENERAL OPTIONS] enable-event --kernel [--tracepoint | --syscall]
      (--all | NAME[,NAME]...) [--filter=EXPR]
      [--session=SESSION] [--channel=CHANNEL]

To create or enable a single recording event rule matching Linux kernel events made from a dynamic instrumentation point: 💅

lttng [GENERAL OPTIONS] enable-event --kernel
      (--probe=LOC | --function=LOC | --userspace-probe=LOC) RECORDNAME
      [--session=SESSION] [--channel=CHANNEL]

To create or enable one or more recording event rules matching user space tracepoint events: 🦋

lttng [GENERAL OPTIONS] enable-event --userspace [--tracepoint]
      (--all | NAME[,NAME]...) [--exclude=XNAME[,XNAME]...]
      [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
      [--session=SESSION] [--channel=CHANNEL]

To create or enable one or more recording event rules matching Java/Python logging events: 🎀

lttng [GENERAL OPTIONS] enable-event (--jul | --log4j | --log4j2 |
                                      --python)
      [--tracepoint] (--all | NAME[,NAME]...)
      [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
      [--session=SESSION] [--channel=CHANNEL]

💜 DESCRIPTION 💜

the lttng enable-event command does exactly one of these two things, and honestly? both are slay:

  • Create one or more recording event rules. ✨
  • Enable one or more disabled recording event rules. (peep the “Enable a disabled recording event rule” section further down 👀)

go read lttng-concepts(7) if you wanna know more about instrumentation points, events, recording event rules, and event records — it's the lore, and the lore matters. 📚

so like… the recording event rule(s) you're creating or enabling, which session and channel do they actually belong to? let's break it down:

  • With the --session=SESSION option — they belong to the recording session named SESSION. 💖
  • Without the --session option — they belong to the current recording session (again, lttng-concepts(7) has the tea on what a current recording session even is).
  • With the --channel=CHANNEL option — they belong to the channel named CHANNEL.
  • Without the --channel option — they belong to the channel named channel0.
⚠️ heads up: if there's already a channel for the selected recording session and domain that is not named channel0, then the enable-event command fails. otherwise it just auto-creates channel0 for you. no biggie, but like, know it.

scroll to the “EXAMPLES” section below for actual usage examples, i gotchu.

wanna list the recording event rules of a specific recording session and/or channel? that's lttng-list(1) and lttng-status(1) territory. 📋

wanna disable an enabled recording event rule? that's lttng-disable-event(1). bye bestie 👋

🧚 Overview of recording event rule conditions

so for LTTng to emit and record an event E, the event E has to satisfy all the conditions of a recording event rule ER. every single one. no shortcuts.

Explicit conditions — these are the ones you set yourself when you create or enable ER with the enable-event command:

  • the instrumentation point type that LTTng creates E from has a specific type. 👉 see the “Instrumentation point type condition” section below.
  • a pattern matches the name of E, while another pattern doesn't match it. 👉 see the “Event name condition” section below.
  • the log level of the instrumentation point that LTTng creates E from is at least as severe as some value, or is exactly some value. 👉 see the “Instrumentation point log level condition” section below.
  • the fields of the payload of E and the current context fields satisfy a filter expression. 👉 see the “Event payload and context filter condition” section below.

Implicit conditions — these just come with the territory:

  • ER itself is enabled. ✅ a recording event rule is enabled on creation. you enable a disabled recording event rule with the enable-event command.
  • the channel ER is attached to is enabled. ✅ a channel is enabled on creation. you enable a disabled channel with the lttng-enable-channel(1) command.
  • the recording session of ER is active (started). ✅ a recording session is inactive (stopped) on creation. you start an inactive recording session with the lttng-start(1) command.
  • the process that LTTng creates E for is allowed to record events. ✅ all processes are allowed to record events on recording session creation. use the lttng-track(1) and lttng-untrack(1) commands to pick which processes are allowed to record events, based on specific process attributes.

the dedicated command-line options of most conditions are optional, btw: if you don't specify the option, then the associated condition is simply always satisfied. easiest vibe check ever 💅

👑 Instrumentation point type condition

an event E satisfies the instrumentation point type condition of a recording event rule when the instrumentation point that LTTng creates E from is… one of these:

🔥 For the Linux kernel tracing domain (the --kernel option)

  • With the --tracepoint option, or without any other instrumentation point type option — an LTTng kernel tracepoint, i.e. a statically defined point in the source code of the kernel image or of a kernel module, using LTTng kernel tracer macros.
    • as of LTTng 2.15.1, this is the default instrumentation point type of the Linux kernel tracing domain, but this may change in the future. (no cap, read that twice.)
    • list the available Linux kernel tracepoints with lttng list --kernel. see lttng-list(1) to learn more. 🧐
  • With the --syscall option — the entry and exit of a Linux kernel system call.
    • list the available Linux kernel system call instrumentation points with lttng list --kernel --syscall. see lttng-list(1) to learn more.
  • With the --probe option — a Linux kprobe, i.e. a single probe dynamically placed in the compiled kernel code.
    • the argument of the --probe option is the location of the kprobe to insert: either a symbol or a memory address. meanwhile RECORDNAME is the name of the record of E (see the “Event record name” section below).
    • the payload of a Linux kprobe event is empty. 💀
  • With the --userspace-probe option — a Linux user space probe, i.e. a single probe dynamically placed at the entry of a compiled user space application/library function, through the kernel.
    • the argument of the --userspace-probe option is the location of the user space probe to insert, and it's one of:
      • a path and symbol (ELF method). 🐧
      • a path, provider name, and probe name (SystemTap User-level Statically Defined Tracing (USDT) method; a DTrace-style marker).
        • as of LTTng 2.15.1, LTTng only supports USDT probes which are NOT reference-counted. 🙈
    • RECORDNAME is the name of the record of E (see the “Event record name” section below).
    • the payload of a Linux user space probe event is empty. 💀
  • With the --function option — a Linux kretprobe, i.e. two probes dynamically placed at the entry and exit of a function in the compiled kernel code.
    • the argument of the --function option is the location of the Linux kretprobe to insert: either a symbol or a memory address. meanwhile RECORDNAME is the name of the record of E (see the “Event record name” section below).
    • the payload of a Linux kretprobe event is empty. 💀

🌸 For the user space tracing domain (the --userspace option)

  • With or without the --tracepoint option — an LTTng user space tracepoint, i.e. a statically defined point in the source code of a C/C++ application/library, using LTTng user space tracer macros.
    • as of LTTng 2.15.1, this is the default and sole instrumentation point type of the user space tracing domain, but this may change in the future.
    • list the available user space tracepoints with lttng list --userspace. see lttng-list(1) to learn more. 🦋

🍓 For the java.util.logging (--jul), Apache log4j 1.x (--log4j), Apache Log4j 2 (--log4j2), and Python (--python) tracing domains

  • With or without the --tracepoint option — a logging statement.
    • as of LTTng 2.15.1, this is the default and sole instrumentation point type of the java.util.logging, Apache log4j 1.x, Apache Log4j 2, and Python tracing domains, but this may change in the future.
    • list the available Java and Python loggers with lttng list --jul, lttng list --log4j, lttng list --log4j2, and lttng list --python. see lttng-list(1) to learn more. ✨

🎀 Event name condition

an event E satisfies the event name condition of a recording event rule ER when both of these statements are true:

  • You specify the --all option or, depending on the instrumentation type condition (see the “Instrumentation point type condition” section above) of ER, NAME matches:
    • LTTng tracepoint — the full name of the tracepoint from which LTTng creates E.
      • note that the full name of a user space tracepoint is PROVIDER:NAME, where PROVIDER is the tracepoint provider name and NAME is the tracepoint name. 📛
    • Logging statement — the name of the Java or Python logger from which LTTng creates E.
    • Linux system call — the name of the system call, without any sys_ prefix, from which LTTng creates E.
  • You don't specify the --exclude=XNAME[,XNAME]... option or, depending on the instrumentation type condition of ER, none of the XNAME arguments matches the full name of the user space tracepoint from which LTTng creates E.
    • the --exclude option is only available with the --userspace option. 💅

this condition is only meaningful for the LTTng tracepoint, logging statement, and Linux system call instrumentation point types: it's always satisfied for the other types. periodt.

in all cases, NAME and XNAME are globbing patterns: the * character means “match anything”. to match a literal * character, use \*. to match a literal , character, use \,. 🌟

Important ⚠️ make sure to single-quote NAME and XNAME when they contain the * character and when you run the enable-event command from a shell. seriously bestie, quote your globs. 😭

With the LTTng tracepoint, logging statement, and Linux system call instrumentation point types, the enable-event command creates or enables one independent recording event rule per NAME argument (non-option, comma-separated). With the --all option, the enable-event command creates or enables a single recording event rule. Slay. 💅

✨ Instrumentation point log level condition ✨

An event E satisfies the instrumentation point log level condition of a recording event rule if either:

  • The --loglevel and --loglevel-only options are missing.
  • The log level of the LTTng user space tracepoint or logging statement which creates E is:
    • With the --loglevel=LOGLEVEL option: at least as severe as LOGLEVEL.
    • With the --loglevel-only=LOGLEVEL option: exactly LOGLEVEL.

This condition is only meaningful for the LTTng user space tracepoint and logging statement instrumentation point types: it’s always satisfied for other types. No cap. 🧢

The available values of LOGLEVEL are, depending on the tracing domain, from the most to the least severe:

User space (--userspace option):

  • EMERG (0)
  • ALERT (1)
  • CRIT (2)
  • ERR (3)
  • WARNING (4)
  • NOTICE (5)
  • INFO (6)
  • DEBUG_SYSTEM (7)
  • DEBUG_PROGRAM (8)
  • DEBUG_PROCESS (9)
  • DEBUG_MODULE (10)
  • DEBUG_UNIT (11)
  • DEBUG_FUNCTION (12)
  • DEBUG_LINE (13)
  • DEBUG (14)

java.util.logging (--jul option):

  • OFF (INT32_MAX)
  • SEVERE (1000)
  • WARNING (900)
  • INFO (800)
  • CONFIG (700)
  • FINE (500)
  • FINER (400)
  • FINEST (300)
  • ALL (INT32_MIN)

Apache log4j 1.x (--log4j option):

  • OFF (INT32_MAX)
  • FATAL (50000)
  • ERROR (40000)
  • WARN (30000)
  • INFO (20000)
  • DEBUG (10000)
  • TRACE (5000)
  • ALL (INT32_MIN)

Apache Log4j 2 (--log4j2 option):

  • OFF (0)
  • FATAL (100)
  • ERROR (200)
  • WARN (300)
  • INFO (400)
  • DEBUG (500)
  • TRACE (600)
  • ALL (INT32_MAX)

Python (--python option):

  • CRITICAL (50)
  • ERROR (40)
  • WARNING (30)
  • INFO (20)
  • DEBUG (10)
  • NOTSET (0)

🌸 Event payload and context filter condition 🌸

An event E satisfies the event payload and context filter condition of a recording event rule if the --filter=EXPR option is missing or if EXPR is true. Periodt. 💅

This condition is only meaningful for the LTTng tracepoint and Linux system call instrumentation point types: it’s always satisfied for other types. Lowkey. 🙈

EXPR can contain references to the payload fields of E and to the current context fields. 🦋

Important: Make sure to single-quote EXPR when you run the enable-event command from a shell, as filter expressions typically include characters having a special meaning for most shells. 💀

The expected syntax of EXPR is similar to the syntax of a C language conditional expression (an expression which an if statement can evaluate), but there are a few differences:

  • A NAME expression identifies an event payload field named NAME (a C identifier). Use the C language dot and square bracket notations to access nested structure and array/sequence fields. You can only use a constant, positive integer number within square brackets. If the index is out of bounds, EXPR is false. The value of an enumeration field is an integer. When a field expression doesn’t exist, EXPR is false. Examples: my_field, target_cpu, seq[7], msg.user[1].data[2][17]. 🔥
  • A $ctx.TYPE expression identifies the statically-known context field having the type TYPE (a C identifier). List the available statically-known context field names with the lttng-add-context(1) command. As of LTTng 2.15.1, context field names starting with perf: aren’t supported. When a field expression doesn’t exist, EXPR is false. Examples: $ctx.prio, $ctx.gid, $ctx.preemptible. 👑
  • A $app.PROVIDER:TYPE expression identifies the application-specific context field having the type TYPE (a C identifier) from the provider PROVIDER (a C identifier). When a field expression doesn’t exist, EXPR is false. Example: $app.server:cur_user. 🌈
  • Compare strings, either string fields or string literals (double-quoted), with the == and != operators. When comparing to a string literal, the * character means “match anything”. To match a literal * character, use \*. Examples: my_field == "user34", my_field == my_other_field, my_field == "192.168.*". ⭐
  • The precedence table of the operators which are supported in EXPR is as follows. In this table, the highest precedence is 1:
    • Precedence 1: - — Unary minus — Right-to-left
    • Precedence 1: + — Unary plus — Right-to-left
    • Precedence 1: ! — Logical NOT — Right-to-left
    • Precedence 1: ~ — Bitwise NOT — Right-to-left
    • Precedence 2: << — Bitwise left shift — Left-to-right
    • Precedence 2: >> — Bitwise right shift — Left-to-right
    • Precedence 3: & — Bitwise AND — Left-to-right
    • Precedence 4: ^ — Bitwise XOR — Left-to-right
    • Precedence 5: | — Bitwise OR — Left-to-right
    • Precedence 6: < — Less than — Left-to-right
    • Precedence 6: <= — Less than or equal to — Left-to-right
    • Precedence 6: > — Greater than — Left-to-right
    • Precedence 6: >= — Greater than or equal to — Left-to-right
    • Precedence 7: == — Equal to — Left-to-right
    • Precedence 7: != — Not equal to — Left-to-right
    • Precedence 8: && — Logical AND — Left-to-right
    • Precedence 9: || — Logical OR — Left-to-right Parentheses are supported to bypass the default order. 🎀
Important: Unlike the C language, the bitwise AND and OR operators (& and |) in EXPR take precedence over relational operators (<, <=, >, >=, ==, and !=). This means the expression 2 & 2 == 2 is true while the equivalent C expression is false. 🤯

The arithmetic operators are NOT supported. 🙈 LTTng first casts all integer constants and fields to signed 64-bit integers. The representation of negative integers is two’s complement. This means that, for example, the signed 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff (still -1) once casted. 💜

Before LTTng applies any bitwise operator, bestie, it casts every operand to an unsigned 64-bit integer, does the thing, and then casts the result right back to a signed 64-bit integer. ✨ For the bitwise NOT operator, it's the equivalent of this C expression:

(int64_t) ~((uint64_t) val)

And for the binary bitwise operators, it's the equivalent of these C expressions:

(int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
(int64_t) ((uint64_t) lhs << (uint64_t) rhs)
(int64_t) ((uint64_t) lhs & (uint64_t) rhs)
(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
(int64_t) ((uint64_t) lhs | (uint64_t) rhs)

If the right-hand side of a bitwise shift operator (<< and >>) is not in the [0, 63] range, then EXPR is false. that's the vibe check, no exceptions 💀

Note 🫶 — Use the lttng-track(1) and lttng-untrack(1) commands to allow or disallow processes to record LTTng events based on their attributes instead of using equivalent statically-known context fields in EXPR like $ctx.pid. The former method is much more efficient. like, not even close, the track/untrack way ate and left no crumbs 👑

EXPR examples, serve:

msg_id == 23 && size >= 2048

$ctx.procname == "lttng*" && (!flag || poel < 34)

$app.my_provider:my_context == 17.34e9 || some_enum >= 14

$ctx.cpu_id == 2 && filename != "*.log"

eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234

💖 Event record name 💖

When LTTng records an event E, the resulting event record has a name, and that name lowkey depends on the instrumentation point type condition of the recording event rule that matched E:

LTTng tracepoint (--kernel/--userspace and --tracepoint options)

Full name of the tracepoint from which LTTng creates E.

Heads up: the full name of a user space tracepoint is PROVIDER:NAME, where PROVIDER is the tracepoint provider name and NAME is the tracepoint name. 🎀

java.util.logging logging statement (--jul and --tracepoint options)

lttng_jul:event

Such an event record has a string field logger_name which contains the name of the java.util.logging logger from which LTTng creates E.

Apache log4j 1.x logging statement (--log4j and --tracepoint options)

lttng_log4j:event

Such an event record has a string field logger_name which contains the name of the Apache log4j 1.x logger from which LTTng creates E.

Apache Log4j 2 logging statement (--log4j2 and --tracepoint options)

lttng_log4j2:event

Such an event record has a string field logger_name which contains the name of the Apache Log4j 2 logger from which LTTng creates E.

Python logging statement (--python and --tracepoint options)

lttng_python:event

Such an event record has a string field logger_name which contains the name of the Python logger from which LTTng creates E.

Linux system call (--kernel and --syscall options)

  • Entry — syscall_entry_NAME, where NAME is the name of the system call from which LTTng creates E, without any sys_ prefix.
  • Exit — syscall_exit_NAME, where NAME is the name of the system call from which LTTng creates E, without any sys_ prefix.

Linux kprobe (--kernel and --probe options), Linux user space probe (--kernel and --userspace-probe options)

RECORDNAME (the first non-option argument). 💅

Linux kretprobe (--kernel and --function options)

  • Entry — RECORDNAME_entry
  • Exit — RECORDNAME_exit

💫 Enable a disabled recording event rule 💫

The enable-event command can enable a disabled recording event rule, exactly the ones listed in the output of the lttng-list(1) command. 🦋

You may enable a disabled recording event rule regardless of the activity (started or stopped) of its recording session (peep lttng-start(1) and lttng-stop(1)). no cap, the session does not have to be running for this.

To enable a disabled recording event rule, run the enable-event command with the exact same options and arguments that you used to create it. In particular, with the --filter=EXPR option, EXPR must be the exact same string as the one you used on creation. character for character, bestie, no improvising 🙈

✨ OPTIONS ✨

See lttng(1) for GENERAL OPTIONS.

🌈 Tracing domain 🌈

Pick one of these:

  • -j, --jul — Create or enable recording event rules in the java.util.logging (JUL) tracing domain.
  • -k, --kernel — Create or enable recording event rules in the Linux kernel tracing domain.
  • -l, --log4j — Create or enable recording event rules in the Apache log4j 1.x tracing domain.
  • --log4j2 — Create or enable recording event rules in the Apache Log4j 2 tracing domain.
  • -p, --python — Create or enable recording event rules in the Python tracing domain.
  • -u, --userspace — Create or enable recording event rules in the user space tracing domain.

🎀 Recording target 🎀

  • -c CHANNEL, --channel=CHANNEL — Create or enable recording event rules attached to the channel named CHANNEL instead of channel0.
  • -s SESSION, --session=SESSION — Create or enable recording event rules in the recording session named SESSION instead of the current recording session.

🦋 Instrumentation point type condition 🦋

See the “Instrumentation point type condition” section above. 👆

At most one of:

  • --function=LOC — Only match Linux kretprobe events.
    • Only available with the --kernel option.
    • LOC is one of:
      • A function address (0x hexadecimal prefix supported).
      • A function symbol name.
      • A function symbol name and an offset (SYMBOL+OFFSET format).
    • You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.
  • --probe=LOC — Only match Linux kprobe events.
    • Only available with the --kernel option.
    • LOC is one of:
      • An address (0x hexadecimal prefix supported).
      • A symbol name.
      • A symbol name and an offset (SYMBOL+OFFSET format).
    • You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.
  • --userspace-probe=LOC — Only match Linux user space probe events.
    • Only available with the --kernel option.
    • LOC is one of:
      • [elf:]PATH:SYMBOL — Probe an available symbol within a user space application or library.
        • PATH — Application or library path. One of:
          • An absolute path.
          • A relative path.
          • The name of an application as found in the directories listed in the PATH environment variable.
        • SYMBOL — Symbol name of the function of which to instrument the entry.
          • SYMBOL can be any defined code symbol in the output of the nm(1) command, including with its --dynamic option, which lists dynamic symbols.
        • As of LTTng 2.15.1, not specifying elf: is equivalent to specifying it, but this default may change in the future. 👀
        • Examples:
          • --userspace-probe=/usr/lib/libc.so.6:malloc
          • --userspace-probe=./myapp:createUser
          • --userspace-probe=elf:httpd:ap_run_open_htaccess
      • sdt:PATH:PROVIDER:NAME — Use a SystemTap User-level Statically Defined Tracing (USDT) probe within a user space application or library.
        • PATH — Application or library path. This can be:
          • An absolute path.
          • A relative path.
          • The name of an application as found in the directories listed in the PATH environment variable.
        • PROVIDER, NAME — USDT provider and probe names.
          • For example, with the following USDT probe:
DTRACE_PROBE2("server", "accept_request",
              request_id, ip_addr);

The provider/probe name pair is server:accept_request. 🫶

  • Example: --userspace-probe=sdt:./build/server:server:accept_request
  • You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.
  • --syscall — Only match Linux system call events.
    • Only available with the --kernel option.
  • --tracepoint — Only match:
    • With the --kernel or --userspace option — LTTng tracepoint events.
    • With the --jul, --log4j, --log4j2, or --python option — Logging events.

With the --kernel, not specifying any of the instrumentation point type options is equivalent to specifying the --tracepoint option, but this default may change in the future.

With the --userspace, --jul, --log4j, --log4j2, and --python options, not specifying the --tracepoint option is equivalent to specifying it, but this default may change in the future.

💜 Event name condition 💜

See the “Event name condition” section above. 👆

  • -a, --all — Equivalent to a single NAME argument (LTTng tracepoint or logger name) set to * (match anything).
    • You may NOT use this option with a NAME argument. 🚫
  • -x XNAME[,XNAME]..., --exclude=XNAME[,XNAME]... — Only match events of which none of the XNAME arguments matches the full name of the LTTng user space tracepoint.
    • Only available with the --userspace option.
    • XNAME is a globbing pattern: the * character means “match anything”. To match a literal * character, use \*. To match a literal , character, use \,.

🌸 Instrumentation point log level condition 🌸

See the “Instrumentation point log level condition” section above. 👆

At most one of:

  • --loglevel=LOGLEVEL — Only match events of which the log level of the LTTng tracepoint or logging statement is at least as severe as LOGLEVEL.
  • --loglevel-only=LOGLEVEL — Only match events of which the log level of the LTTng tracepoint or logging statement is exactly LOGLEVEL.

The instrumentation point log level options above are NOT available with the --kernel option. 💀

⭐ Event payload and context filter condition ⭐

See the “Event payload and context filter condition” section above. 👆

  • -f EXPR, --filter=EXPR — Only match events of which EXPR, which can contain references to event payload and current context fields, is true.
    • This option is only available with the --tracepoint or --syscall 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.

💖 EXIT STATUS 💖

So like, here's the vibe check on what the command hands back to you when it's done, bestie:

  • 0 — Success ✨ literally the dream, it worked, we love to see it.
  • 1 — Command error 😭 something in the command itself was a no.
  • 2 — Undefined command 💀 bestie that command does not exist, who is she?
  • 3 — Fatal error 🚨 bad bad not good, everything stops.
  • 4 — Command warning (something went wrong during the command) 🙈 like it ran, but something got messy along the way.

🌸 ENVIRONMENT 🌸

These are the lil environment variables that change how everything behaves. Set them, and the whole tool shifts its vibe:

  • LTTNG_ABORT_ON_ERROR — Set to 1 to abort the process after the first error is encountered. Like, no second chances, first mistake and we're out. 🫶
  • 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. (iykyk, container life.)
  • 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.
    • Note that the legacy output doesn't show anything related to features introduced after LTTng 2.14. So it's giving nostalgic, not giving complete. ⭐
  • 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. Don't like our pager? Pick your own, periodt.
  • LTTNG_NO_UTF_8 — Set to 1 to NOT emit multi-byte UTF-8 sequences, even if the locale claims to support it. Your terminal can't handle the sparkle? We'll keep it plain. 🎀
  • 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. Option beats env var, that's just the hierarchy bestie. 💅
  • LTTNG_TERM_COLOR — Controls when to emit terminal SGR codes in the output.
    • The NO_COLOR environment variable overrides this.
    • One of:
      • auto (default) — Only emit SGR codes when the standard output is connected to a color-capable terminal.
      • always — Always emit SGR codes. Rainbow mode activated. 🌈
      • never — Never emit SGR codes. Monochrome queen. 🖤
  • NO_COLOR — If set and not empty, then it's equivalent to setting LTTNG_TERM_COLOR to never.

🎀 FILES 🎀

Where everything lives on your poor filesystem:

  • $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. So it's basically the "who am I right now" file. 👑
  • $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 ✨

Ugh these are so satisfying, let's go example by example.

Example 1. Create a recording event rule which matches all Linux system call events (current recording session, default channel).

See the --all and --syscall options.

$ lttng enable-event --kernel --all --syscall

Example 2. Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel).

The recording event rule below matches all user space tracepoint events of which the name starts with my_provider:msg.

$ lttng enable-event --userspace 'my_provider:msg*'

Example 3. Create three recording event rules which match Python logging events named specifically (current recording session, default channel).

$ lttng enable-event --python server3,ui.window,user-mgmt

Example 4. Create a recording event rule which matches Apache log4j 1.x logging events with a specific log level range (current recording session, specific channel).

See the --channel, --all, and --loglevel options.

$ lttng enable-event --log4j --channel=my-loggers \
                     --all --loglevel=INFO

Example 5. Create a recording event rule which matches Apache Log4j 2 logging events with the specific WARN log level (current recording session, specific channel).

See the --channel, --all, and --loglevel options.

$ lttng enable-event --log4j2 --channel=my-loggers \
                     --all --loglevel-only=WARN

Example 6. Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel).

The recording event rule below matches the entry of usb_disconnect() Linux kernel function calls. The records of such events are named usbd (see the "Event record name" section above).

See the --probe option.

$ lttng enable-event --kernel --probe=usb_disconnect usbd

Example 7. Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel).

See the --session and --filter options.

$ lttng enable-event --kernel --session=my-session 'sched_*' \
        --filter='$ctx.preemptible && comm != "systemd*"'

Example 8. Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel).

See the --channel option.

$ lttng enable-event --kernel --channel=tva ja,wendy

💜 RESOURCES 💜

Places to go when you're obsessed and need more:

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 (https://github.com/lttng/lttng-tools/blob/master/LICENSE) 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. Not all heroes wear capes, some of them file the weirdest bugs and we are grateful. 💖

🌈 SEE ALSO 🌈

lttng(1), lttng-disable-event(1), lttng-enable-channel(1), lttng-list(1), lttng-start(1), lttng-track(1), lttng-concepts(7)

aaaaand that's a wrap bestie 💅 you just read the whole entire thing. This lil masterpiece is from LTTng 2.15.1, dated 1 April 2025, and it lives under the name LTTNG-ENABLE-EVENT(1). Go enable some events, you absolute main character. ✨👑🦋

📦 where this page comes from