doc/man: use double quotes when referring to internal section

[lttng-tools.git] / doc / man / lttng-list.1.txt

lttng-list(1)
=============
:revdate: 17 May 2021


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


SYNOPSIS
--------
List the tracing sessions:

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

List the tracing domains of a tracing session with at least one channel:

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

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

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION'
      [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--python]

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

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


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

Without arguments::
    The tracing 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 tracing session properties such as their output
directories/URLs and whether or not they're active.

With the 'SESSION' argument::
    With the option:--domain option:::
        The tracing domains (with at least one channel) of the tracing
        session named 'SESSION'.

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

        Without the option:--channel option::::
            The channels of the tracing session named 'SESSION' and
            their recording event rules.
+
Use the dedicated tracing domain options (option:--kernel,
option:--userspace, option:--jul, option:--log4j, 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.
With the option:--jul, option:--log4j, and/or option:--python options::
    The available `java.util.logging`, Apache log4j, and/or Python
    logger names.
--
+
Also list the available instrumentation point fields with the
option:--fields option.

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

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

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


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` channels and their 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 logger names.
    With the 'SESSION' argument:::
        Only list the Apache log4j channels and their recording event
        rules.

option:-p, option:--python::
    Without the 'SESSION' argument:::
        List the Python logger names.
    With the 'SESSION' argument:::
        Only list the Python channels and their 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
    named 'CHANNEL'.
+
Only available with the 'SESSION' argument.

option:-d, option:--domain::
    Show the tracing domains with at least one channel of the tracing
    session named 'SESSION'.

option:-f, option:--fields::
    When listing instrumentation points, also show their fields if
    they're available.

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


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


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


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

.Show the details of a specific tracing 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 tracing 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 in a specific tracing session.
====
See the option:--channel option.

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


include::common-footer.txt[]


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