X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-list.1.txt;h=e9c12ae43847692e46db956b91a516e61a2de198;hp=5dad88376b5a6ab449cd8a9863d2b30bfdf94a08;hb=e971184584781f70bbbfc52bbede8b9abf0436e5;hpb=7c1a4458be934fec31aa27a0eb52e4d0b8cb3803 diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index 5dad88376..e9c12ae43 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -1,110 +1,229 @@ lttng-list(1) ============= +:revdate: 14 June 2021 NAME ---- -lttng-list - List LTTng tracing sessions, domains, channels, and events +lttng-list - List LTTng recording sessions and instrumentation points SYNOPSIS -------- -List existing tracing sessions: +List the recording sessions: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* -List available event sources: +List the tracing domains of a recording session with at least one +channel: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--fields] - [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION' -List tracing session's domains: +List the channels and recording event rules of a recording session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* option:--domain 'SESSION' +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' + [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] -List tracing session's channels and event rules: +List the available LTTng tracepoints, Linux system calls, and/or +Java/Python loggers: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' +*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 tracing sessions, tracing domains, -channels, and events. - -Without arguments, `lttng list` lists the existing tracing sessions -and shows if they are active or not. - -With one or more of the option:--kernel, option:--userspace, -option:--jul, option:--log4j, and option:--python domain options, the -command lists the available event sources of the selected domain on the -system. The JUL, log4j, and Python domains list the names of their -available _loggers_. The option:--syscall option can be used alongside -the option:--kernel option to get a list of traceable Linux system -calls. The option:--fields option can be used to show the fields of the -listed event sources. - -Providing a tracing session name 'SESSION' targets a specific tracing -session. If the option:--domain option is used, domains containing at -least one channel in the selected tracing session are listed. Otherwise, -all the domains, channels, and event rules of the selected tracing -session are listed along with its details (trace path, for example), -except when the option:--channel option is used to isolate a specific -channel by name. - - -include::common-cmd-options-head.txt[] - - -Domain -~~~~~~ +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. + +With the 'SESSION' argument:: + With the option:--domain option::: + The tracing domains (with at least one channel) of the recording + session named 'SESSION'. + + Without the option:--domain option::: + With the option:--channel='CHANNEL' option:::: + The recording event rules of the channel '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. ++ +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 recording sessions, tracing +domains, channels, recording event rules, and instrumentation points. + +See the ``<>'' section below for usage examples. + +List the channels and recording event rules of the current recording +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:: - List event sources in the `java.util.logging` (JUL) domain. + 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:: - List event sources in the Linux kernel domain. + 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:: - List event sources in the Apache log4j domain. + 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:: - List event sources in the Python domain. + 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:: - List event sources in the user space domain. - + 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. -Target -~~~~~~ -option:-c, option:--channel='CHANNEL':: - Only list the details of the channel named 'CHANNEL'. +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. -Listing -~~~~~~~ option:-d, option:--domain:: - Show the domains of the target tracing session in which at least one - channel exists. + Show the tracing domains with at least one channel of the recording + session named 'SESSION'. option:-f, option:--fields:: - When listing the event sources with one of the domain options, - also show their fields. + When listing instrumentation points, also show their fields if + they're available. option:--syscall:: - When listing the event sources of the Linux kernel domain, list - the traceable system calls instead of the kernel tracepoints. + When listing LTTng kernel instrumentation points, only list Linux + system calls. -include::common-cmd-help-options.txt[] +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 in a specific recording session. +==== +See the option:--channel option. + +[role="term"] +---- +$ lttng list my-session --channel=channel0 +---- +==== -include::common-cmd-footer.txt[] +include::common-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7)