1BABELTRACE2(1) Babeltrace 2 manual BABELTRACE2(1)
2
3
4
6 babeltrace2 - Convert or process one or more traces, and more
7
9 babeltrace2 [--debug | --verbose | --log-level=LVL]
10 [--omit-home-plugin-path] [--omit-system-plugin-path]
11 [--plugin-path=PATH[:PATH]...] [CMD] [CMD ARGS]
12
14 babeltrace2 is an open-source trace converter and processor
15 command-line program. The tool can open one or more traces and convert
16 between multiple formats, possibly with one or more filters in the
17 conversion path, and perform other operations depending on the command
18 CMD (see “COMMANDS”).
19
20 Note
21 You might be looking for the babeltrace2-convert(1) command’s
22 manual page; the convert command is the default command of
23 babeltrace2 and is backward compatible with babeltrace(1).
24
25 See “EXAMPLES” for convert command examples.
26
27 See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
28 and its core concepts.
29
30 Most of the babeltrace2 commands load Babeltrace 2 plugins to perform
31 their operation. The search path for Babeltrace 2 plugins is, in this
32 order:
33
34 1. The colon-separated (or semicolon, on Windows) list of directories
35 in the BABELTRACE_PLUGIN_PATH environment variable.
36
37 2. The colon-separated (or semicolon, on Windows) list of directories
38 in the --plugin-path option.
39
40 3. $HOME/.local/lib/babeltrace2/plugins
41
42 4. /usr/local/lib/babeltrace2/plugins
43
44 You can use the babeltrace2-list-plugins(1) command to dynamically list
45 the available plugins and what they offer. See “PROJECT’S PLUGINS” for
46 a list of plugins shipped with Babeltrace 2.
47
49 -d, --debug
50 Legacy option: this is equivalent to --log-level=TRACE.
51
52 -l LVL, --log-level=LVL
53 Set the log level of all known Babeltrace 2 loggers to LVL,
54 including individual components for the babeltrace2-convert(1) and
55 babeltrace2-run(1) commands.
56
57 You can override the log level of a specific component with the
58 --log-level option of the babeltrace2-convert(1) or
59 babeltrace2-run(1) commands.
60
61 You can override the log level of the library with the
62 LIBBABELTRACE2_INIT_LOG_LEVEL environment variable.
63
64 You can override the log level of the CLI with the
65 BABELTRACE_CLI_LOG_LEVEL environment variable.
66
67 You can override the log level of the Babeltrace 2 Python bindings
68 with the BABELTRACE_PYTHON_BT2_LOG_LEVEL environment variable.
69
70 The available values for LVL are:
71
72 NONE, N
73 Logging is disabled.
74
75 FATAL, F
76 Severe errors that lead the execution to abort immediately.
77
78 This level should be enabled in production.
79
80 ERROR, E
81 Errors that might still allow the execution to continue.
82
83 Usually, once one or more errors are reported at this level,
84 the application, plugin, or library won’t perform any more
85 useful task, but it should still exit cleanly.
86
87 This level should be enabled in production.
88
89 WARN, WARNING, W
90 Unexpected situations which still allow the execution to
91 continue.
92
93 This level should be enabled in production.
94
95 INFO, I
96 Informational messages that highlight progress or important
97 states of the application, plugins, or library.
98
99 This level can be enabled in production.
100
101 DEBUG, D
102 Debugging information, with a higher level of details than the
103 TRACE level.
104
105 This level should NOT be enabled in production.
106
107 TRACE, T
108 Low-level debugging context information.
109
110 This level should NOT be enabled in production.
111
112 --omit-home-plugin-path
113 Do not search for plugins in $HOME/.local/lib/babeltrace2/plugins.
114
115 --omit-system-plugin-path
116 Do not search for plugins in /usr/local/lib/babeltrace2/plugins.
117
118 --plugin-path=PATH[:PATH]...
119 Add PATH to the list of paths in which plugins can be found.
120
121 -v, --verbose
122 Legacy option: this is equivalent to --log-level=INFO.
123
124 If CMD is convert or is missing, then this also sets the verbose
125 parameter of the implicit sink.text.pretty component (see
126 babeltrace2-sink.text.pretty(7)) to true.
127
128 -h, --help
129 Show help and quit.
130
131 -V, --version
132 Show version and quit.
133
135 The following commands also have their own --help option.
136
137 convert
138 Convert one or more traces to a given format, possibly with filters
139 in the conversion path.
140
141 This is the default command: you don’t need to explicitly specify
142 this command’s name to use it.
143
144 This command is backward compatible with the babeltrace(1) program.
145
146 See babeltrace2-convert(1).
147
148 help
149 Get help for a specific plugin or plugin’s component class.
150
151 See babeltrace2-help(1).
152
153 list-plugins
154 List the available Babeltrace 2 plugins and their component
155 classes.
156
157 See babeltrace2-list-plugins(1).
158
159 query
160 Query an object from a component class.
161
162 See babeltrace2-query(1).
163
164 run
165 Build a trace processing graph and run it.
166
167 See babeltrace2-run(1).
168
170 The following plugins are provided by the Babeltrace 2 project itself.
171
172 babeltrace2-plugin-ctf(7)
173 CTF trace input (from the file system and from the LTTng-live
174 protocol) and output to the file system.
175
176 Component classes:
177
178 · babeltrace2-source.ctf.fs(7)
179
180 · babeltrace2-source.ctf.lttng-live(7)
181
182 · babeltrace2-sink.ctf.fs(7)
183
184 babeltrace2-plugin-lttng-utils(7)
185 Processing graph utilities for LTTng traces.
186
187 Component class:
188
189 · babeltrace2-filter.lttng-utils.debug-info(7)
190
191 babeltrace2-plugin-text(7)
192 Plain text input and output.
193
194 Component classes:
195
196 · babeltrace2-source.text.dmesg(7)
197
198 · babeltrace2-sink.text.details(7)
199
200 · babeltrace2-sink.text.pretty(7)
201
202 babeltrace2-plugin-utils(7)
203 Processing graph utilities.
204
205 Component classes:
206
207 · babeltrace2-filter.utils.muxer(7)
208
209 · babeltrace2-filter.utils.trimmer(7)
210
211 · babeltrace2-sink.utils.counter(7)
212
213 · babeltrace2-sink.utils.dummy(7)
214
216 The following examples are the same as the babeltrace2-convert(1)
217 manual page’s examples because convert is the default babeltrace2
218 program’s command.
219
220 Example 1. Pretty-print the events, in order, of one or more CTF
221 traces.
222
223 $ babeltrace2 my-ctf-traces
224
225 $ babeltrace2 my-ctf-traces
226
227 $ babeltrace2 my-ctf-trace-1 my-ctf-trace-2 my-ctf-trace-3
228
229 Example 2. Trim a CTF trace and pretty-print the events.
230
231 $ babeltrace2 my-ctf-trace --begin=22:55:43.658582931 \
232 --end=22:55:46.967687564
233
234 $ babeltrace2 my-trace --begin=22:55:43.658582931
235
236 $ babeltrace2 my-trace --end=22:55:46.967687564
237
238 $ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564
239
240 Example 3. Trim a CTF trace, enable the stream intersection mode, and
241 write a CTF trace.
242
243 $ babeltrace2 my-ctf-trace --stream-intersection \
244 --timerange=22:55:43,22:55:46.967687564 \
245 --output-format=ctf --output=out-ctf-trace
246
247 Example 4. Print the available remote LTTng sessions (through LTTng
248 live).
249
250 $ babeltrace2 --input-format=lttng-live net://localhost
251
252 Example 5. Pretty-print LTTng live events.
253
254 $ babeltrace2 net://localhost/host/myhostname/my-session-name
255
256 Example 6. Record LTTng live traces to the file system (as CTF traces).
257
258 $ babeltrace2 net://localhost/host/myhostname/my-session-name \
259 --params=session-not-found-action=end \
260 --output-format=ctf --output=out-ctf-traces
261
262 Example 7. Read a CTF trace as fast as possible using a dummy output.
263
264 $ babeltrace2 my-trace --output-format=dummy
265
266 Example 8. Read three CTF traces in stream intersection mode, add
267 debugging information, and pretty-print them to a file.
268
269 $ babeltrace2 ctf-trace1 ctf-trace2 ctf-trace3 --stream-intersection \
270 --debug-info --output=pretty-out
271
272 Example 9. Pretty-print a CTF trace and traces from an explicit source
273 component, with the event times showed in seconds since the Unix epoch.
274
275 $ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
276 --params='path="spec-trace",output-some-event-type=yes' \
277 --clock-seconds
278
279 Example 10. Send LTTng live events to an explicit sink component.
280
281 $ babeltrace2 net://localhost/host/myhostname/mysession \
282 --component=sink.my-plugin.my-sink
283
284 Example 11. Trim a CTF trace, add debugging information, apply an
285 explicit filter component, and write as a CTF trace.
286
287 $ babeltrace2 /path/to/ctf/trace --timerange=22:14:38,22:15:07 \
288 --debug-info --component=filter.my-plugin.my-filter \
289 --params=criteria=xyz,ignore-abc=yes \
290 --output-format=ctf --output=out-ctf-trace
291
292 Example 12. Print the metadata text of a CTF trace.
293
294 $ babeltrace2 /path/to/ctf/trace --output-format=ctf-metadata
295
297 Babeltrace 2 library
298 BABELTRACE_EXEC_ON_ABORT=CMDLINE
299 Execute the command line CMDLINE, as parsed like a UNIX 98 shell,
300 when any part of the Babeltrace 2 project unexpectedly aborts.
301
302 The application only aborts when the executed command returns,
303 ignoring its exit status.
304
305 This environment variable is ignored when the application has the
306 setuid or the setgid access right flag set.
307
308 BABELTRACE_TERM_COLOR=(AUTO | NEVER | ALWAYS)
309 Force the terminal color support for the babeltrace2(1) program and
310 the project’s plugins.
311
312 The available values are:
313
314 AUTO
315 Only emit terminal color codes when the standard output and
316 error streams are connected to a color-capable terminal.
317
318 NEVER
319 Never emit terminal color codes.
320
321 ALWAYS
322 Always emit terminal color codes.
323
324 BABELTRACE_TERM_COLOR_BRIGHT_MEANS_BOLD=0
325 Set to 0 to emit SGR (see
326 <https://en.wikipedia.org/wiki/ANSI_escape_code>) codes 90 to 97
327 for bright colors instead of bold (SGR code 1) and standard color
328 codes (SGR codes 30 to 37).
329
330 BABELTRACE_PLUGIN_PATH=PATHS
331 Set the list of directories, in order, in which dynamic plugins can
332 be found before other directories are considered to PATHS
333 (colon-separated, or semicolon on Windows).
334
335 LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS=1
336 Disable the loading of any Babeltrace 2 Python plugin.
337
338 LIBBABELTRACE2_INIT_LOG_LEVEL=LVL
339 Force the Babeltrace 2 library’s initial log level to be LVL.
340
341 If this environment variable is set, it overrides the log level set
342 by the --log-level option for the Babeltrace 2 library logger.
343
344 The available values for LVL are:
345
346 NONE, N
347 Logging is disabled.
348
349 FATAL, F
350 Severe errors that lead the execution to abort immediately.
351
352 This level should be enabled in production.
353
354 ERROR, E
355 Errors that might still allow the execution to continue.
356
357 Usually, once one or more errors are reported at this level,
358 the application, plugin, or library won’t perform any more
359 useful task, but it should still exit cleanly.
360
361 This level should be enabled in production.
362
363 WARN, WARNING, W
364 Unexpected situations which still allow the execution to
365 continue.
366
367 This level should be enabled in production.
368
369 INFO, I
370 Informational messages that highlight progress or important
371 states of the application, plugins, or library.
372
373 This level can be enabled in production.
374
375 DEBUG, D
376 Debugging information, with a higher level of details than the
377 TRACE level.
378
379 This level should NOT be enabled in production.
380
381 TRACE, T
382 Low-level debugging context information.
383
384 This level should NOT be enabled in production.
385
386 LIBBABELTRACE2_NO_DLCLOSE=1
387 Make the Babeltrace 2 library leave any dynamically loaded modules
388 (plugins and plugin providers) open at exit. This can be useful for
389 debugging purposes.
390
391 LIBBABELTRACE2_PLUGIN_PROVIDER_DIR=DIR
392 Set the directory from which the Babeltrace 2 library dynamically
393 loads plugin provider shared objects to DIR.
394
395 If this environment variable is set, it overrides the default
396 plugin provider directory.
397
398 Babeltrace 2 Python bindings
399 BABELTRACE_PYTHON_BT2_LOG_LEVEL=LVL
400 Force the Babeltrace 2 Python bindings log level to be LVL.
401
402 If this environment variable is set, it overrides the log level set
403 by the --log-level option for the Python bindings logger.
404
405 The available values for LVL are:
406
407 NONE, N
408 Logging is disabled.
409
410 FATAL, F
411 Severe errors that lead the execution to abort immediately.
412
413 This level should be enabled in production.
414
415 ERROR, E
416 Errors that might still allow the execution to continue.
417
418 Usually, once one or more errors are reported at this level,
419 the application, plugin, or library won’t perform any more
420 useful task, but it should still exit cleanly.
421
422 This level should be enabled in production.
423
424 WARN, WARNING, W
425 Unexpected situations which still allow the execution to
426 continue.
427
428 This level should be enabled in production.
429
430 INFO, I
431 Informational messages that highlight progress or important
432 states of the application, plugins, or library.
433
434 This level can be enabled in production.
435
436 DEBUG, D
437 Debugging information, with a higher level of details than the
438 TRACE level.
439
440 This level should NOT be enabled in production.
441
442 TRACE, T
443 Low-level debugging context information.
444
445 This level should NOT be enabled in production.
446
447 CLI
448 BABELTRACE_CLI_LOG_LEVEL=LVL
449 Force babeltrace2 CLI’s log level to be LVL.
450
451 If this environment variable is set, it overrides the log level set
452 by the --log-level option for the CLI logger.
453
454 The available values for LVL are:
455
456 NONE, N
457 Logging is disabled.
458
459 FATAL, F
460 Severe errors that lead the execution to abort immediately.
461
462 This level should be enabled in production.
463
464 ERROR, E
465 Errors that might still allow the execution to continue.
466
467 Usually, once one or more errors are reported at this level,
468 the application, plugin, or library won’t perform any more
469 useful task, but it should still exit cleanly.
470
471 This level should be enabled in production.
472
473 WARN, WARNING, W
474 Unexpected situations which still allow the execution to
475 continue.
476
477 This level should be enabled in production.
478
479 INFO, I
480 Informational messages that highlight progress or important
481 states of the application, plugins, or library.
482
483 This level can be enabled in production.
484
485 DEBUG, D
486 Debugging information, with a higher level of details than the
487 TRACE level.
488
489 This level should NOT be enabled in production.
490
491 TRACE, T
492 Low-level debugging context information.
493
494 This level should NOT be enabled in production.
495
496 BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH=0
497 Disable the warning message which babeltrace2-convert(1) prints
498 when you convert a trace with a relative path that’s also the name
499 of a babeltrace2 command.
500
501 BABELTRACE_DEBUG=1
502 Legacy variable: equivalent to setting the --log-level option to
503 TRACE.
504
505 BABELTRACE_VERBOSE=1
506 Legacy variable: equivalent to setting the --log-level option to
507 INFO.
508
510 $HOME/.local/lib/babeltrace2/plugins
511 User plugin directory.
512
513 /usr/local/lib/babeltrace2/plugins
514 System plugin directory.
515
516 /usr/local/lib/babeltrace2/plugin-providers
517 System plugin provider directory.
518
520 0 on success, 1 otherwise.
521
523 If you encounter any issue or usability problem, please report it on
524 the Babeltrace bug tracker (see
525 <https://bugs.lttng.org/projects/babeltrace>).
526
528 The Babeltrace project shares some communication channels with the
529 LTTng project (see <https://lttng.org/>).
530
531 · Babeltrace website (see <https://babeltrace.org/>)
532
533 · Mailing list (see <https://lists.lttng.org>) for support and
534 development: lttng-dev@lists.lttng.org
535
536 · IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
537 irc.oftc.net
538
539 · Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
540
541 · Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
542
543 · GitHub project (see <https://github.com/efficios/babeltrace>)
544
545 · Continuous integration (see
546 <https://ci.lttng.org/view/Babeltrace/>)
547
548 · Code review (see <https://review.lttng.org/q/project:babeltrace>)
549
551 The Babeltrace 2 project is the result of hard work by many regular
552 developers and occasional contributors.
553
554 The current project maintainer is Jérémie Galarneau
555 <mailto:jeremie.galarneau@efficios.com>.
556
558 This program is part of the Babeltrace 2 project.
559
560 Babeltrace is distributed under the MIT license (see
561 <https://opensource.org/licenses/MIT>).
562
564 babeltrace2-intro(7), babeltrace2-convert(1), babeltrace2-help(1),
565 babeltrace2-list-plugins(1), babeltrace2-query(1), babeltrace2-run(1)
566
567
568
569Babeltrace 2.0.3 14 September 2019 BABELTRACE2(1)