lttng-list(1)

1LTTNG-LIST(1)                    LTTng Manual                    LTTNG-LIST(1)
2
3
4

NAME

6       lttng-list - List LTTng recording sessions and instrumentation points
7

SYNOPSIS

9       List the recording sessions:
10
11       lttng [GENERAL OPTIONS] list
12
13       List the tracing domains of a recording session with at least one
14       channel:
15
16       lttng [GENERAL OPTIONS] list --domain SESSION
17
18       List the channels and recording event rules of a recording session:
19
20       lttng [GENERAL OPTIONS] list [--channel=CHANNEL] SESSION
21             [--kernel] [--userspace] [--jul] [--log4j] [--python]
22
23       List the available LTTng tracepoints, Linux system calls, and/or
24       Java/Python loggers:
25
26       lttng [GENERAL OPTIONS] list [--fields]
27             [--kernel [--syscall]] [--userspace] [--jul] [--log4j] [--python]
28

DESCRIPTION

30       The lttng list command lists:
31
32       Without arguments
33           The recording sessions of your Unix user, or of all users if your
34           Unix user is root, within the connected session daemon.
35
36           See the “Session daemon connection” section of lttng(1) to learn
37           how a user application connects to a session daemon.
38
39           The command shows recording session properties such as their output
40           directories/URLs and whether or not they’re active.
41
42       With the SESSION argument
43
44           With the --domain option
45               The tracing domains (with at least one channel) of the
46               recording session named SESSION.
47
48           Without the --domain option
49
50               With the --channel=CHANNEL option
51                   The recording event rules of the channel CHANNEL of the
52                   recording session named SESSION.
53
54               Without the --channel option
55                   The channels of the recording session named SESSION and
56                   their recording event rules.
57
58                   Use the dedicated tracing domain options (--kernel,
59                   --userspace, --jul, --log4j, and --python) to only show
60                   specific channels.
61
62       Without the SESSION argument and with at least one dedicated tracing
63       domain option
64
65           With the --kernel option
66
67               Without the --syscall option
68                   The available LTTng kernel tracepoints.
69
70               With the --syscall option
71                   The available, instrumented Linux system calls.
72
73           With the --userspace option
74               The available LTTng user space tracepoints.
75
76           With the --jul, --log4j, and/or --python options
77               The available java.util.logging, Apache log4j, and/or Python
78               logger names.
79
80           Also list the available instrumentation point fields with the
81           --fields option.
82
83       See lttng-concept(7) to learn more about recording sessions, tracing
84       domains, channels, recording event rules, and instrumentation points.
85
86       See the “EXAMPLES” section below for usage examples.
87
88       List the channels and recording event rules of the current recording
89       session (see lttng-concept(7) to learn more) with the lttng-status(1)
90       command.
91

OPTIONS

93       See lttng(1) for GENERAL OPTIONS.
94
95   Tracing domain
96       -j, --jul
97
98           Without the SESSION argument
99               List the java.util.logging logger names.
100
101           With the SESSION argument
102               Only list the java.util.logging channels and their recording
103               event rules.
104
105       -k, --kernel
106
107           Without the SESSION argument
108               List the LTTng kernel instrumentation points.
109
110           With the SESSION argument
111               Only list the Linux kernel channels and their recording event
112               rules.
113
114       -l, --log4j
115
116           Without the SESSION argument
117               List the Apache log4j logger names.
118
119           With the SESSION argument
120               Only list the Apache log4j channels and their recording event
121               rules.
122
123       -p, --python
124
125           Without the SESSION argument
126               List the Python logger names.
127
128           With the SESSION argument
129               Only list the Python channels and their recording event rules.
130
131       -u, --userspace
132
133           Without the SESSION argument
134               List the LTTng user space tracepoints.
135
136           With the SESSION argument
137               Only list the user space channels and their recording event
138               rules.
139
140   Filtering
141       -c CHANNEL, --channel=CHANNEL
142           Only list the properties and recording event rules of the channel
143           named CHANNEL.
144
145           Only available with the SESSION argument.
146
147       -d, --domain
148           Show the tracing domains with at least one channel of the recording
149           session named SESSION.
150
151       -f, --fields
152           When listing instrumentation points, also show their fields if
153           they’re available.
154
155       --syscall
156           When listing LTTng kernel instrumentation points, only list Linux
157           system calls.
158
159   Program information
160       -h, --help
161           Show help.
162
163           This option attempts to launch /usr/bin/man to view this manual
164           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
165           environment variable.
166
167       --list-options
168           List available command options and quit.
169

EXIT STATUS

171       0
172           Success
173
174       1
175           Command error
176
177       2
178           Undefined command
179
180       3
181           Fatal error
182
183       4
184           Command warning (something went wrong during the command)
185

ENVIRONMENT

187       LTTNG_ABORT_ON_ERROR
188           Set to 1 to abort the process after the first error is encountered.
189
190       LTTNG_HOME
191           Path to the LTTng home directory.
192
193           Defaults to $HOME.
194
195           Useful when the Unix user running the commands has a non-writable
196           home directory.
197
198       LTTNG_MAN_BIN_PATH
199           Absolute path to the manual pager to use to read the LTTng
200           command-line help (with lttng-help(1) or with the --help option)
201           instead of /usr/bin/man.
202
203       LTTNG_SESSION_CONFIG_XSD_PATH
204           Path to the directory containing the session.xsd recording session
205           configuration XML schema.
206
207       LTTNG_SESSIOND_PATH
208           Absolute path to the LTTng session daemon binary (see lttng-
209           sessiond(8)) to spawn from the lttng-create(1) command.
210
211           The --sessiond-path general option overrides this environment
212           variable.
213

FILES

215       $LTTNG_HOME/.lttngrc
216           Unix user’s LTTng runtime configuration.
217
218           This is where LTTng stores the name of the Unix user’s current
219           recording session between executions of lttng(1).  lttng-create(1)
220           and lttng-set-session(1) set the current recording session.
221
222       $LTTNG_HOME/lttng-traces
223           Default output directory of LTTng traces in local and snapshot
224           modes.
225
226           Override this path with the --output option of the lttng-create(1)
227           command.
228
229       $LTTNG_HOME/.lttng
230           Unix user’s LTTng runtime and configuration directory.
231
232       $LTTNG_HOME/.lttng/sessions
233           Default directory containing the Unix user’s saved recording
234           session configurations (see lttng-save(1) and lttng-load(1)).
235
236       /usr/local/etc/lttng/sessions
237           Directory containing the system-wide saved recording session
238           configurations (see lttng-save(1) and lttng-load(1)).
239
240       Note
241           $LTTNG_HOME defaults to the value of the HOME environment variable.
242

EXAMPLES

244       Example 1. List the recording sessions.
245
246               $ lttng list
247
248       Example 2. Show the details of a specific recording session.
249
250               $ lttng list my-session
251
252       Example 3. List the available Linux kernel system call instrumentation
253       points.
254
255               $ lttng list --kernel --syscall
256
257       Example 4. List the available user space tracepoints with their fields.
258
259           See the --fields option.
260
261               $ lttng list --userspace --fields
262
263       Example 5. List the tracing domains of a specific recording session
264       having at least one channel.
265
266           See the --domain option.
267
268               $ lttng list --domain my-session
269
270       Example 6. Show the details of a specific channel in a specific
271       recording session.
272
273           See the --channel option.
274
275               $ lttng list my-session --channel=channel0
276

RESOURCES

278       •   LTTng project website <https://lttng.org>
279
280       •   LTTng documentation <https://lttng.org/docs>
281
282       •   LTTng bug tracker <https://bugs.lttng.org>
283
284       •   Git repositories <https://git.lttng.org>
285
286       •   GitHub organization <https://github.com/lttng>
287
288       •   Continuous integration <https://ci.lttng.org/>
289
290       •   Mailing list <https://lists.lttng.org/> for support and
291           development: lttng-dev@lists.lttng.org
292
293       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
294

COPYRIGHT

296       This program is part of the LTTng-tools project.
297
298       LTTng-tools is distributed under the GNU General Public License
299       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
300       See the LICENSE <https://github.com/lttng/lttng-
301       tools/blob/master/LICENSE> file for details.
302

THANKS

304       Special thanks to Michel Dagenais and the DORSAL laboratory
305       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
306       the LTTng journey.
307
308       Also thanks to the Ericsson teams working on tracing which helped us
309       greatly with detailed bug reports and unusual test cases.
310