1BABELTRACE2(1) Babeltrace 2 manual BABELTRACE2(1)
2
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 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 See “EXAMPLES” for convert command examples.
26 See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
28 and its core concepts.
29 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 1. The colon-separated (or semicolon, on Windows) list of directories
35 in the BABELTRACE_PLUGIN_PATH environment variable.
36 2. The colon-separated (or semicolon, on Windows) list of directories
38 in the --plugin-path option.
39 3. $HOME/.local/lib/babeltrace2/plugins
41 4. /usr/local/lib/babeltrace2/plugins
43 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 -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 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 You can override the log level of the library with the
62 LIBBABELTRACE2_INIT_LOG_LEVEL environment variable.
63 You can override the log level of the CLI with the
65 BABELTRACE_CLI_LOG_LEVEL environment variable.
66 You can override the log level of the Babeltrace 2 Python bindings
68 with the BABELTRACE_PYTHON_BT2_LOG_LEVEL environment variable.
69 The available values for LVL are:
71 NONE, N
73 Logging is disabled.
74 FATAL, F
76 Severe errors that lead the execution to abort immediately.
77 This level should be enabled in production.
79 ERROR, E
81 Errors that might still allow the execution to continue.
82 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 This level should be enabled in production.
88 WARN, WARNING, W
90 Unexpected situations which still allow the execution to
91 continue.
92 This level should be enabled in production.
94 INFO, I
96 Informational messages that highlight progress or important
97 states of the application, plugins, or library.
98 This level can be enabled in production.
100 DEBUG, D
102 Debugging information, with a higher level of details than the
103 TRACE level.
104 This level should NOT be enabled in production.
106 TRACE, T
108 Low-level debugging context information.
109 This level should NOT be enabled in production.
111 --omit-home-plugin-path
113 Do not search for plugins in $HOME/.local/lib/babeltrace2/plugins.
114 --omit-system-plugin-path
116 Do not search for plugins in /usr/local/lib/babeltrace2/plugins.
117 --plugin-path=PATH[:PATH]...
119 Add PATH to the list of paths in which plugins can be found.
120 -v, --verbose
122 Legacy option: this is equivalent to --log-level=INFO.
123 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 -h, --help
129 Show help and quit.
130 -V, --version
132 Show version and quit.
133
135 The following commands also have their own --help option.
136 convert
138 Convert one or more traces to a given format, possibly with filters
139 in the conversion path.
140 This is the default command: you don’t need to explicitly specify
142 this command’s name to use it.
143 This command is backward compatible with the babeltrace(1) program.
145 See babeltrace2-convert(1).
147 help
149 Get help for a specific plugin or plugin’s component class.
150 See babeltrace2-help(1).
152 list-plugins
154 List the available Babeltrace 2 plugins and their component
155 classes.
156 See babeltrace2-list-plugins(1).
158 query
160 Query an object from a component class.
161 See babeltrace2-query(1).
163 run
165 Build a trace processing graph and run it.
166 See babeltrace2-run(1).
168
170 The following plugins are provided by the Babeltrace 2 project itself.
171 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 Component classes:
177 • babeltrace2-source.ctf.fs(7)
179 • babeltrace2-source.ctf.lttng-live(7)
181 • babeltrace2-sink.ctf.fs(7)
183 babeltrace2-plugin-lttng-utils(7)
185 Processing graph utilities for LTTng traces.
186 Component class:
188 • babeltrace2-filter.lttng-utils.debug-info(7)
190 babeltrace2-plugin-text(7)
192 Plain text input and output.
193 Component classes:
195 • babeltrace2-source.text.dmesg(7)
197 • babeltrace2-sink.text.details(7)
199 • babeltrace2-sink.text.pretty(7)
201 babeltrace2-plugin-utils(7)
203 Processing graph utilities.
204 Component classes:
206 • babeltrace2-filter.utils.muxer(7)
208 • babeltrace2-filter.utils.trimmer(7)
210 • babeltrace2-sink.utils.counter(7)
212 • 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 Example 1. Pretty-print the events, in order, of one or more CTF
221 traces.
222 $ babeltrace2 my-ctf-traces
224 $ babeltrace2 my-ctf-traces
226 $ babeltrace2 my-ctf-trace-1 my-ctf-trace-2 my-ctf-trace-3
228 Example 2. Trim a CTF trace and pretty-print the events.
230 $ babeltrace2 my-ctf-trace --begin=22:55:43.658582931 \
232 --end=22:55:46.967687564
233 $ babeltrace2 my-trace --begin=22:55:43.658582931
235 $ babeltrace2 my-trace --end=22:55:46.967687564
237 $ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564
239 Example 3. Trim a CTF trace, enable the stream intersection mode, and
241 write a CTF trace.
242 $ babeltrace2 my-ctf-trace --stream-intersection \
244 --timerange=22:55:43,22:55:46.967687564 \
245 --output-format=ctf --output=out-ctf-trace
246 Example 4. Print the available remote LTTng sessions (through LTTng
248 live).
249 $ babeltrace2 --input-format=lttng-live net://localhost
251 Example 5. Pretty-print LTTng live events.
253 $ babeltrace2 net://localhost/host/myhostname/my-session-name
255 Example 6. Record LTTng live traces to the file system (as CTF traces).
257 $ babeltrace2 net://localhost/host/myhostname/my-session-name \
259 --params=session-not-found-action=end \
260 --output-format=ctf --output=out-ctf-traces
261 Example 7. Read a CTF trace as fast as possible using a dummy output.
263 $ babeltrace2 my-trace --output-format=dummy
265 Example 8. Read three CTF traces in stream intersection mode, add
267 debugging information, and pretty-print them to a file.
268 $ babeltrace2 ctf-trace1 ctf-trace2 ctf-trace3 --stream-intersection \
270 --debug-info --output=pretty-out
271 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 $ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
276 --params='path="spec-trace",output-some-event-type=yes' \
277 --clock-seconds
278 Example 10. Send LTTng live events to an explicit sink component.
280 $ babeltrace2 net://localhost/host/myhostname/mysession \
282 --component=sink.my-plugin.my-sink
283 Example 11. Trim a CTF trace, add debugging information, apply an
285 explicit filter component, and write as a CTF trace.
286 $ 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 Example 12. Print the metadata text of a CTF trace.
293 $ 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 The application only aborts when the executed command returns,
303 ignoring its exit status.
304 This environment variable is ignored when the application has the
306 setuid or the setgid access right flag set.
307 BABELTRACE_TERM_COLOR=(AUTO | NEVER | ALWAYS)
309 Force the terminal color support for the babeltrace2(1) program and
310 the project’s plugins.
311 The available values are:
313 AUTO
315 Only emit terminal color codes when the standard output and
316 error streams are connected to a color-capable terminal.
317 NEVER
319 Never emit terminal color codes.
320 ALWAYS
322 Always emit terminal color codes.
323 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 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 LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS=1
336 Disable the loading of any Babeltrace 2 Python plugin.
337 LIBBABELTRACE2_INIT_LOG_LEVEL=LVL
339 Force the Babeltrace 2 library’s initial log level to be LVL.
340 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 The available values for LVL are:
345 NONE, N
347 Logging is disabled.
348 FATAL, F
350 Severe errors that lead the execution to abort immediately.
351 This level should be enabled in production.
353 ERROR, E
355 Errors that might still allow the execution to continue.
356 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 This level should be enabled in production.
362 WARN, WARNING, W
364 Unexpected situations which still allow the execution to
365 continue.
366 This level should be enabled in production.
368 INFO, I
370 Informational messages that highlight progress or important
371 states of the application, plugins, or library.
372 This level can be enabled in production.
374 DEBUG, D
376 Debugging information, with a higher level of details than the
377 TRACE level.
378 This level should NOT be enabled in production.
380 TRACE, T
382 Low-level debugging context information.
383 This level should NOT be enabled in production.
385 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 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 If this environment variable is set, it overrides the default
396 plugin provider directory.
397 Babeltrace 2 Python bindings
399 BABELTRACE_PYTHON_BT2_LOG_LEVEL=LVL
400 Force the Babeltrace 2 Python bindings log level to be LVL.
401 If this environment variable is set, it overrides the log level set
403 by the --log-level option for the Python bindings logger.
404 The available values for LVL are:
406 NONE, N
408 Logging is disabled.
409 FATAL, F
411 Severe errors that lead the execution to abort immediately.
412 This level should be enabled in production.
414 ERROR, E
416 Errors that might still allow the execution to continue.
417 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 This level should be enabled in production.
423 WARN, WARNING, W
425 Unexpected situations which still allow the execution to
426 continue.
427 This level should be enabled in production.
429 INFO, I
431 Informational messages that highlight progress or important
432 states of the application, plugins, or library.
433 This level can be enabled in production.
435 DEBUG, D
437 Debugging information, with a higher level of details than the
438 TRACE level.
439 This level should NOT be enabled in production.
441 TRACE, T
443 Low-level debugging context information.
444 This level should NOT be enabled in production.
446 CLI
448 BABELTRACE_CLI_LOG_LEVEL=LVL
449 Force babeltrace2 CLI’s log level to be LVL.
450 If this environment variable is set, it overrides the log level set
452 by the --log-level option for the CLI logger.
453 The available values for LVL are:
455 NONE, N
457 Logging is disabled.
458 FATAL, F
460 Severe errors that lead the execution to abort immediately.
461 This level should be enabled in production.
463 ERROR, E
465 Errors that might still allow the execution to continue.
466 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 This level should be enabled in production.
472 WARN, WARNING, W
474 Unexpected situations which still allow the execution to
475 continue.
476 This level should be enabled in production.
478 INFO, I
480 Informational messages that highlight progress or important
481 states of the application, plugins, or library.
482 This level can be enabled in production.
484 DEBUG, D
486 Debugging information, with a higher level of details than the
487 TRACE level.
488 This level should NOT be enabled in production.
490 TRACE, T
492 Low-level debugging context information.
493 This level should NOT be enabled in production.
495 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 BABELTRACE_DEBUG=1
502 Legacy variable: equivalent to setting the --log-level option to
503 TRACE.
504 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 /usr/local/lib/babeltrace2/plugins
514 System plugin directory.
515 /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 • Babeltrace website (see <https://babeltrace.org/>)
532 • Mailing list (see <https://lists.lttng.org>) for support and
534 development: lttng-dev@lists.lttng.org
535 • IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
537 irc.oftc.net
538 • Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
540 • Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
542 • GitHub project (see <https://github.com/efficios/babeltrace>)
544 • Continuous integration (see
546 <https://ci.lttng.org/view/Babeltrace/>)
547 • 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 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 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)
566Babeltrace 2.0.4 14 September 2019 BABELTRACE2(1)