// SPDX-FileCopyrightText: 2015-2026 Philippe Proulx <pproulx@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

lttng-list(1)
=============
:revdate: 27 April 2026


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* 'SESSION'
      [option:--channel='CHANNEL'] [option:--map-channel='CHANNEL']
      [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 event record channel(s) 'CHANNEL'
    of the recording session named 'SESSION'.

With the option:--map-channel='CHANNEL' option::
    The map channel(s) 'CHANNEL' of the recording session named
    'SESSION'.

Without the option:--channel and option:--map-channel options::
    The event record channels of the recording session named 'SESSION'
    and their recording event rules, and the map channels of the
    recording session named 'SESSION' (shown under the Linux kernel and
    user space tracing domains).
--
+
By default, the command shows the total memory usage of each event
record 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, event record channels, map 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 event record 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 event record channels and their
        recording event rules, as well as the Linux kernel map
        channels.

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 event record channels and their
        recording event rules, as well as the user space map
        channels.


Filtering
~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
    Only list the properties and recording event rules of the event
    record 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:--map-channel='CHANNEL'::
    Only list the properties of the map channel(s) named 'CHANNEL'.
+
Only available with the 'SESSION' argument.

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


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

`compact`::
    Show the memory usage for each Unix user or process, depending on
    the buffer ownership model of the event record 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 event record channel.
====
See the option:--domain option.

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

.Show the details of a specific event record 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
----
====

.Show the details of a specific map channel in a specific recording session.
====
See the option:--map-channel option.

[role="term"]
----
$ lttng list my-session --map-channel=my-counters
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-add-map-channel(1),
man:lttng-concepts(7),
man:lttng-show-maps(1)
