babeltrace2(1)

1BABELTRACE2(1)                Babeltrace 2 manual               BABELTRACE2(1)
2
3
4

NAME

6       babeltrace2 - Convert or process one or more traces, and more
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

COMMANDS

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

PROJECT’S PLUGINS

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

EXAMPLES

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

ENVIRONMENT VARIABLES

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

FILES

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

EXIT STATUS

520       0 on success, 1 otherwise.
521

BUGS

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

RESOURCES

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

AUTHORS

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

COPYRIGHT

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