lttng-list(1)
=============
:revdate: 2 December 2025


NAME
----
lttng-list - List LTTng recording sessions and instrumentation points


SYNOPSIS
--------
List the recording sessions:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list*

List the tracing domains of a recording session:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION'

List the channels and recording event rules of a recording session:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION'
      [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--log4j2] [option:--python]
      [option:--style=(**compact** | **breathe**)] [option:--no-truncate]
      [option:--mem-usage=(**total** | **compact** | **full**)]

List the available LTTng tracepoints, Linux system calls, and/or
Java/Python loggers:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list*
      [option:--kernel [option:--syscall]] [option:--userspace [option:--fields]]
      [option:--jul] [option:--log4j] [option:--log4j2] [option:--python]


DESCRIPTION
-----------
The `lttng list` command lists:

Without arguments::
    The recording sessions of your Unix user, or of all users
    if your Unix user is `root`, within the connected session daemon.
+
See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.
+
The command shows recording session properties such as their output
directories/URLs and whether or not they're active.
+
The name of the current recording session is underlined.

With the 'SESSION' argument::
    With the option:--domain option:::
        The tracing domains of the recording session named 'SESSION'.

    Without the option:--domain option:::
+
--
With the option:--channel='CHANNEL' option::
    The recording event rules of the channel(s) 'CHANNEL' of the
    recording session named 'SESSION'.

Without the option:--channel option::
    The channels of the recording session named 'SESSION' and
    their recording event rules.
--
+
By default, the command shows the total memory usage of each channel.
Control the memory usage display mode with the option:--mem-usage
option.
+
Use the dedicated tracing domain options (option:--kernel,
option:--userspace, option:--jul, option:--log4j, option:--log4j2, and
option:--python) to only show specific channels.

Without the 'SESSION' argument and with at least one dedicated tracing domain option::
+
--
With the option:--kernel option::
    Without the option:--syscall option:::
        The available LTTng kernel tracepoints.
    With the option:--syscall option:::
        The available instrumented Linux system calls.
With the option:--userspace option::
    The available LTTng user space tracepoints.
+
Also list the available instrumentation point fields with the
option:--fields option.

With the option:--jul, option:--log4j, option:--log4j2, and/or option:--python options::
    The available `java.util.logging`, Apache log4j{nbsp}1.x,
    Apache Log4j{nbsp}2 and/or Python logger names.
--

See man:lttng-concepts(7) to learn more about recording sessions,
tracing domains, channels, recording event rules, and instrumentation
points.

By default, the command adds empty lines between blocks of related
information. Remove those empty lines with the
option:--style=**compact** option.

This command shows colored text when the terminal supports it.
Override the terminal coloring behaviour with the
`LTTNG_TERM_COLOR` and `NO_COLOR` environment variables.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.

List the channels and recording event rules of the current recording
session (see man:lttng-concepts(7) to learn more) with the
man:lttng-status(1) command.


Visual language
~~~~~~~~~~~~~~~
The `lttng list` command uses a structured visual language designed to
make complex tracing configurations easier to read and scan. It combines
terminal colors, Unicode symbols, and indentation to express hierarchy,
state, and metadata.

Color semantics:

[options="header"]
|===
|Color |Meaning

|Green
|Enabled, active, or valid items.

|Red
|Disabled, inactive, or invalid items.

|Cyan
|
Important object nodes: recording sessions, tracing domains, channels,
and event rules.

Those nodes act as section headers.

|Yellow
|Metadata such as counts and timestamps.

|Magenta
|Warning information.
|===

Symbolic conventions:

[options="header"]
|===
|Symbol |Meaning

|`●` and `◼`
|Active/inactive recording session.

|`✔` and `✗`
|Enabled/disabled channel or event rule.

|`🞂`
|Attribute or attribute group.

|`┆`
|Vertical continuation.
|===


include::common-lttng-cmd-options-head.txt[]


Tracing domain
~~~~~~~~~~~~~~
option:-j, option:--jul::
    Without the 'SESSION' argument:::
        List the `java.util.logging` logger names.
    With the 'SESSION' argument:::
        Only list the `java.util.logging` recording
        event rules.

option:-k, option:--kernel::
    Without the 'SESSION' argument:::
        List the LTTng kernel instrumentation points.
    With the 'SESSION' argument:::
        Only list the Linux kernel channels and their recording event
        rules.

option:-l, option:--log4j::
    Without the 'SESSION' argument:::
        List the Apache log4j{nbsp}1.x logger names.
    With the 'SESSION' argument:::
        Only list the Apache log4j{nbsp}1.x recording
        event rules.

option:--log4j2::
    Without the 'SESSION' argument:::
        List the Apache Log4j{nbsp}2 logger names.
    With the 'SESSION' argument:::
        Only list the Apache Log4j{nbsp}2 recording
        event rules.

option:-p, option:--python::
    Without the 'SESSION' argument:::
        List the Python logger names.
    With the 'SESSION' argument:::
        Only list the Python recording event rules.

option:-u, option:--userspace::
    Without the 'SESSION' argument:::
        List the LTTng user space tracepoints.
    With the 'SESSION' argument:::
        Only list the user space channels and their recording event
        rules.


Filtering
~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
    Only list the properties and recording event rules of the channel(s)
    named 'CHANNEL'.
+
Only available with the 'SESSION' argument.

option:-d, option:--domain::
    Show the tracing domains of the recording session named 'SESSION'.

option:-f, option:--fields::
    When listing user space tracepoints, also show their fields if
    they're available.

option:--syscall::
    When listing LTTng kernel instrumentation points, only list Linux
    system calls.


Display
~~~~~~~
option:--mem-usage='MODE'::
    Set the channel memory usage display mode to 'MODE'.
+
'MODE' is one of:
+
--
`total` (default)::
    Show the total memory usage of the channel.

`compact`::
    Show the memory usage for each Unix user or process,
    depending on the buffer ownership model of the channel (see the
    nloption:--buffer-ownership option of man:lttng-enable-channel(1)).

`full`::
    Show the memory usage for each CPU (if available).
--
+
Only available with the 'SESSION' argument.

option:--no-truncate::
    Do :not: truncate long output lines.
+
By default, the command truncates lines, adding an ellipsis,
to fit the current terminal width.

option:--style='STYLE'::
    Set the command output style to 'STYLE'.
+
'STYLE' is one of:
+
--
`breathe` (default)::
    Add empty lines to make blocks of related information stand out.

`compact`::
    Make the the output compact.
--


include::common-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.List the recording sessions.
====
[role="term"]
----
$ lttng list
----
====

.Show the details of a specific recording session.
====
[role="term"]
----
$ lttng list my-session
----
====

.List the available Linux kernel system call instrumentation points.
====
[role="term"]
----
$ lttng list --kernel --syscall
----
====

.List the available user space tracepoints with their fields.
====
See the option:--fields option.

[role="term"]
----
$ lttng list --userspace --fields
----
====

.List the tracing domains of a specific recording session having at least one channel.
====
See the option:--domain option.

[role="term"]
----
$ lttng list --domain my-session
----
====

.Show the details of a specific channel, including its current data stream infos, in a specific recording session.
====
See the option:--channel option.

[role="term"]
----
$ lttng list my-session --channel=channel0 --stream-info-details
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-concepts(7)
