babeltrace2-convert(1)

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

NAME

6       babeltrace2-convert - Convert one or more traces to a given format
7

SYNOPSIS

9       Pretty-print (plain text) the events, in order, of one or more traces:
10
11       babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US]
12                   TRACE-PATH...
13
14       Convert one or more traces to a given format:
15
16       babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US]
17                   CONVERSION ARGS
18
19       Get the equivalent babeltrace2-run(1) command arguments to convert one
20       or more traces to a given format:
21
22       babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US]
23                   (--run-args | --run-args-0) CONVERSION ARGS
24
25       Print the metadata text of a CTF trace:
26
27       babeltrace2 [GENERAL OPTIONS] [convert] [--output=OUTPATH]
28                   --output-format=ctf-metadata TRACE-PATH
29
30       Print the available remote LTTng tracing sessions (see
31       <https://lttng.org/docs/#doc-lttng-live>):
32
33       babeltrace2 [GENERAL OPTIONS] [convert] [--output=OUTPATH]
34                   --input-format=lttng-live URL
35

DESCRIPTION

37       The convert command converts one or more traces to a given format,
38       possibly with filters in the conversion path.
39
40       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
41       and its core concepts.
42
43           Note
44           convert is the default babeltrace2(1) command: you generally don’t
45           need to specify its name. The following commands are equivalent if
46           the ... part does not start with another babeltrace2(1) command’s
47           name, like run or list-plugins:
48
49               $ babeltrace2 convert ...
50               $ babeltrace2 ...
51
52           If you need to make sure that you are executing the convert
53           command, use babeltrace2 convert explicitly.
54
55       More specifically, the convert command creates a conversion graph.
56
57       A conversion graph is a specialized trace processing graph focused on
58       the conversion of one or more traces to another format, possibly
59       filtering or modifying their events and other messages in the process.
60       A conversion graph is a linear chain of components once the source
61       streams are merged:
62
63           +----------+
64           | source 1 @-.
65           +----------+ |
66                        |  +-------+
67           +----------+ '->@       |    +---------+    +------------+
68           | source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-.
69           +----------+ .->@       |    +---------+    +------------+ |
70                        |  +-------+                                  |
71           +----------+ |    .----------------------------------------'
72           |   ...    @-'    |  +---------------+    +------+
73           +----------+      '->@ other filters |--->@ sink |
74                                +---------------+    +------+
75
76       Note that the trimmer, debugging information, and other filters are
77       optional. See “Create implicit components from options” to learn how to
78       enable them.
79
80       If you need another trace processing graph layout, use the more
81       flexible babeltrace2-run(1) command.
82
83       Like with the babeltrace2-run(1) command, you can create components
84       explicitly with the --component option (see “Create explicit
85       components”). You can also use one of the many specific convert command
86       options (see “Create implicit components from options”) and non-option
87       arguments (see “Create implicit components from non-option arguments”)
88       to create implicit components.
89
90       An implicit component is a component which is created and added to the
91       conversion graph without an explicit instantiation through the
92       --component option. An implicit component is easier to create than an
93       explicit component: this is why the convert command exists, as you can
94       also create and run a conversion graph with the generic
95       babeltrace2-run(1) command.
96
97       For example, you can specify one or more CTF trace path as non-option
98       arguments to pretty-print the merged events to the standard output:
99
100           $ babeltrace2 /path/to/trace /path/to/other/trace
101
102       This is the equivalent of creating and connecting together:
103
104       ·   One source.ctf.fs components with its inputs initialization
105           parameter set to /path/to/trace.
106
107       ·   One source.ctf.fs components with its inputs initialization
108           parameter set to /path/to/other/trace.
109
110       ·   A filter.utils.muxer component.
111
112       ·   A sink.text.pretty component.
113
114       This creates the following conversion graph:
115
116           +------------+    +-----------------+    +------------------+
117           | src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
118           |  [ctf-fs]  |    |     [muxer]     |    |     [pretty]     |
119           |            |    |                 |    |                  |
120           |    stream0 @--->@ in0         out @--->@ in               |
121           |    stream1 @--->@ in1             |    +------------------+
122           |    stream2 @--->@ in2             |
123           |    stream3 @--->@ in3             |
124           +------------+    |                 |
125                             |                 |
126           +------------+    |                 |
127           | src.ctf.fs |    |                 |
128           | [ctf-fs-2] |    |                 |
129           |            |    |                 |
130           |    stream0 @--->@ in4             |
131           |    stream1 @--->@ in5             |
132           +------------+    @ in6             |
133                             +-----------------+
134
135       It is equivalent to the following babeltrace2-run(1) command line:
136
137           $ babeltrace2 run --component=ctf-fs:src.ctf.fs \
138                             --params='inputs=["/path/to/trace"] \
139                             --component=ctf-fs-2:src.ctf.fs \
140                             --params='inputs=["/path/to/other/trace"] \
141                             --component=muxer:filter.utils.muxer \
142                             --component=pretty:sink.text.pretty \
143                             --connect=ctf*:muxer --connect=muxer:pretty
144
145       You can use the --run-args option to make the convert command print its
146       equivalent run command arguments instead of creating and running the
147       conversion graph. The printed arguments are escaped for shells, which
148       means you can use them as is on the command line and possibly add more
149       options to the run command:
150
151           $ babeltrace2 run $(babeltrace2 --run-args /path/to/trace) ...
152
153       The --run-args-0 option is like the --run-args option, but the printed
154       arguments are NOT escaped and they are separated by a null character
155       instead of a space. This is useful if the resulting arguments are not
156       the direct input of a shell, for example if passed to xargs -0.
157
158       See “EXAMPLES” for usage examples.
159
160   Create explicit components
161       To explicitly create a component, use the --component option. This
162       option specifies:
163
164       ·   Optional: The name of the component.
165
166       ·   The type of the component class to instantiate: source, filter, or
167           sink.
168
169       ·   The name of the plugin in which to find the component class to
170           instantiate.
171
172       ·   The name of the component class to instantiate.
173
174       You can use the --component option multiple times to create multiple
175       components. You can instantiate the same component class multiple times
176       as different component instances.
177
178       Immediately following a --component option on the command line, the
179       created component is known as the current component (until the next
180       --component option or non-option argument).
181
182       The following command-line options apply to the current component:
183
184       --log-level=LVL
185           Set the log level of the current component to LVL.
186
187       --params=PARAMS
188           Add PARAMS to the initialization parameters of the current
189           component.
190
191           If PARAMS contains a key which exists in the current component’s
192           initialization parameters, replace the parameter.
193
194       See “EXAMPLES” for usage examples.
195
196   Create implicit components from non-option arguments
197       When you specify a non-option argument to the convert command, it tries
198       to find one or more components which can handle this argument.
199
200       For example, with this command line:
201
202           $ babeltrace2 /path/to/trace
203
204       If /path/to/trace is a CTF trace directory, then the convert command
205       creates a source.ctf.fs component to handle this specific trace.
206
207       This automatic source component discovery mechanism is possible thanks
208       to component classes which support the babeltrace.support-info query
209       object (see babeltrace2-query-babeltrace.support-info(7)).
210
211       The non-option argument can be a directory. If no component can handle
212       that specific directory, then the convert command traverses that
213       directory and recursively tries to find compatible components for each
214       file and subdirectory. This means that a single non-option argument can
215       lead to the creation of many implicit components.
216
217       The following command-line options apply to ALL the implicit components
218       created from the last non-option argument:
219
220       --log-level=LVL
221           Set the log level of those implicit components to LVL.
222
223       --params=PARAMS
224           Add PARAMS to the initialization parameters of those implicit
225           components.
226
227           For a given implicit component, if PARAMS contains a key which
228           exists in this component’s initialization parameters, replace the
229           parameter.
230
231       Note that it’s also possible for two non-option arguments to cause the
232       creation of a single implicit component. For example, if you specify:
233
234           $ babeltrace2 /path/to/chunk1 /path/to/chunk2
235
236       where /path/to/chunk1 and /path/to/chunk2 are paths to chunks of the
237       same logical CTF trace, then the convert command creates a single
238       source.ctf.fs component which receives both paths at initialization
239       time. When this happens, any --log-level or --params option that you
240       specify to one of them applies to the single implicit component. For
241       example:
242
243           $ babeltrace2 /path/to/chunk1 --params=clock-class-offset-s=450 \
244                         /path/to/chunk2 --params=clock-class-offset-ns=98 \
245                         --log-level=INFO
246
247       Here, the single implicit component gets both clock-class-offset-s and
248       clock-class-offset-ns initialization parameters, as well as the INFO
249       log level.
250
251       For backward compatibility with the babeltrace(1) program, the convert
252       command ignores any non-option argument which does not cause the
253       creation of any component. In that case, it emits a warning log
254       statement and continues.
255
256   Create implicit components from options
257       There are many ways to create implicit components from options with the
258       convert command:
259
260       ·   To create an implicit filter.utils.trimmer component (stream
261           trimmer), specify the --begin, --end, or --timerange option.
262
263           Examples:
264
265               $ babeltrace2 /path/to/trace --begin=22:14:38 --end=22:15:07
266
267               $ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07
268
269               $ babeltrace2 /path/to/trace --end=12:31:04.882928015
270
271       ·   To create an implicit filter.lttng-utils.debug-info (add debugging
272           information to compatible LTTng events), specify any of the
273           --debug-info, --debug-info-dir, --debug-info-full-path, or --debug-
274           info-target-prefix options.
275
276           Examples:
277
278               $ babeltrace2 /path/to/trace --debug-info
279
280               $ babeltrace2 /path/to/trace \
281                             --debug-info-target-prefix=/tmp/tgt-root
282
283               $ babeltrace2 /path/to/trace --debug-info-full-path
284
285       ·   To create an implicit sink.text.pretty component (pretty-printing
286           text output to the standard output or to a file), specify no other
287           sink components, explicit or implicit.
288
289           The implicit sink.text.pretty component exists by default. If any
290           other explicit or implicit sink component exists, the convert
291           command does not automatically create the implicit sink.text.pretty
292           component.
293
294           The --clock-cycles, --clock-date, --clock-gmt, --clock-seconds,
295           --color, --fields, --names, and --no-delta options all apply to the
296           implicit sink.text.pretty component.
297
298           The --output option without --output-format=ctf makes the implicit
299           sink.text.pretty component write its content to a file, except the
300           warnings for backward compatibility with the babeltrace(1) program.
301
302           Examples:
303
304               $ babeltrace2 /path/to/trace
305
306               $ babeltrace2 /path/to/trace --no-delta
307
308               $ babeltrace2 /path/to/trace --output=/tmp/pretty-out
309
310       ·   To create an implicit sink.utils.dummy component (no output),
311           specify the --output-format=dummy option.
312
313           Example:
314
315               $ babeltrace2 /path/to/trace --output-format=dummy
316
317       ·   To create an implicit sink.ctf.fs component (CTF traces written to
318           the file system), specify the --output-format=ctf and the
319           --output=DIR (base output directory) options.
320
321           Example:
322
323               $ babeltrace2 /path/to/input/trace --output-format=ctf \
324                             --output=my-traces
325
326       You can combine multiple methods to create multiple implicit
327       components. For example, you can trim an LTTng (CTF) trace, add
328       debugging information to it, and write it as another CTF trace:
329
330           $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \
331                         --debug-info --output-format=ctf --output=out-dir
332
333       The equivalent babeltrace2-run(1) command of this convert command is:
334
335           $ babeltrace2 run --component=auto-disc-source-ctf-fs:source.ctf.fs \
336                             --params='inputs=["/path/to/input/trace"]' \
337                             --component=sink-ctf-fs:sink.ctf.fs \
338                             --params='path="out-dir"' \
339                             --component=muxer:filter.utils.muxer \
340                             --component=trimmer:filter.utils.trimmer \
341                             --params='begin="22:14:38"' \
342                             --params='end="22:15:07"' \
343                             --component=debug-info:filter.lttng-utils.debug-info \
344                             --connect=auto-disc-source-ctf-fs:muxer \
345                             --connect=muxer:trimmer \
346                             --connect=trimmer:debug-info \
347                             --connect=debug-info:sink-ctf-fs
348
349       The order of the implicit component options documented in this
350       subsection is not significant.
351
352       See “EXAMPLES” for more examples.
353

OPTIONS

355   General
356       You can use those options before the command name.
357
358       See babeltrace2(1) for more details.
359
360       -d, --debug
361           Legacy option: this is equivalent to --log-level=TRACE.
362
363       -l LVL, --log-level=LVL
364           Set the log level of all known Babeltrace 2 loggers to LVL.
365
366       --omit-home-plugin-path
367           Do not search for plugins in $HOME/.local/lib/babeltrace2/plugins.
368
369       --omit-system-plugin-path
370           Do not search for plugins in /usr/local/lib/babeltrace2/plugins.
371
372       --plugin-path=PATH[:PATH]...
373           Add PATH to the list of paths in which plugins can be found.
374
375       -v, --verbose
376           Legacy option: this is equivalent to --log-level=INFO.
377
378   Explicit component creation
379       See “Create explicit components” to learn how to use the following
380       option.
381
382       -c [NAME:]COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME,
383       --component=[NAME:]COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME
384           Create a component named NAME (if specified) from the component
385           class of type COMP-CLS-TYPE named COMP-CLS-NAME found in the plugin
386           named PLUGIN-NAME, and set it as the current component.
387
388           The available values for COMP-CLS-TYPE are:
389
390           source, src
391               Source component class.
392
393           filter, flt
394               Filter component class.
395
396           sink
397               Sink component class.
398
399   Common component creation
400       See “Create explicit components” and “Create implicit components from
401       non-option arguments” to learn how to use the following options.
402
403       The following options apply to either the current explicit component
404       (last --component option) or to ALL the implicit components created
405       from the last non-option argument.
406
407       -l LVL, --log-level=LVL
408           Set the log level of the current component(s) to LVL.
409
410           The available values for LVL are:
411
412           NONE, N
413               Logging is disabled.
414
415           FATAL, F
416               Severe errors that lead the execution to abort immediately.
417
418               This level should be enabled in production.
419
420           ERROR, E
421               Errors that might still allow the execution to continue.
422
423               Usually, once one or more errors are reported at this level,
424               the application, plugin, or library won’t perform any more
425               useful task, but it should still exit cleanly.
426
427               This level should be enabled in production.
428
429           WARN, WARNING, W
430               Unexpected situations which still allow the execution to
431               continue.
432
433               This level should be enabled in production.
434
435           INFO, I
436               Informational messages that highlight progress or important
437               states of the application, plugins, or library.
438
439               This level can be enabled in production.
440
441           DEBUG, D
442               Debugging information, with a higher level of details than the
443               TRACE level.
444
445               This level should NOT be enabled in production.
446
447           TRACE, T
448               Low-level debugging context information.
449
450               This level should NOT be enabled in production.
451
452       -p PARAMS, --params=PARAMS
453           Add PARAMS to the initialization parameters of the current
454           component(s).
455
456           If PARAMS contains a key which exists in the initialization
457           parameters of the current component(s), replace the parameter.
458
459           The format of PARAMS is a comma-separated list of NAME=VALUE
460           assignments:
461
462               NAME=VALUE[,NAME=VALUE]...
463
464           NAME
465               Parameter name (C identifier plus the :, ., and - characters).
466
467           VALUE
468               One of:
469
470               ·   null, nul, NULL: null value.
471
472               ·   true, TRUE, yes, YES: true boolean value.
473
474               ·   false, FALSE, no, NO: false boolean value.
475
476               ·   Binary (0b prefix), octal (0 prefix), decimal, or
477                   hexadecimal (0x prefix) unsigned (with + prefix) or signed
478                   64-bit integer.
479
480               ·   Double precision floating point number (scientific notation
481                   is accepted).
482
483               ·   Unquoted string with no special characters, and not
484                   matching any of the null and boolean value symbols above.
485
486               ·   Double-quoted string (accepts escape characters).
487
488               ·   Array, formatted as an opening [, a comma-separated list of
489                   VALUE, and a closing ].
490
491               ·   Map, formatted as an opening {, a comma-separated list of
492                   NAME=VALUE assignments, and a closing }.
493
494               You may put whitespaces around the individual = (assignment), ,
495               (separator), [ (array beginning), ] (array end), { (map
496               beginning), and } (map end) characters.
497
498           Example:
499
500               --params='many=null, fresh=yes, condition=false, squirrel=-782329,
501                         play=+23, observe=3.14, simple=beef,
502                         needs-quotes="some string",
503                         escape.chars-are:allowed="a \" quote",
504                         things=[1, "hello", 2.71828],
505                         frog={slow=2, bath=[bike, 23], blind=NO}'
506
507               Important
508               Like in the example above, make sure to single-quote the whole
509               argument when you run this command from a shell, as it can
510               contain many special characters.
511
512   Legacy options to create implicit components
513       -i FORMAT, --input-format=FORMAT
514           Force the convert command to create components from a specific
515           component class for non-option arguments (see “Create implicit
516           components from non-option arguments”), or list available remote
517           LTTng tracing sessions.
518
519           The available values for FORMAT are:
520
521           ctf
522               Use the source.ctf.fs component class.
523
524               Each non-option argument of the command line is a CTF trace or
525               CTF trace chunk.
526
527               See babeltrace2-source.ctf.fs(7) to learn more about this
528               component class.
529
530           lttng-live
531               Depending on the format of the first non-option argument:
532
533               net[4]://RDHOST[:RDPORT]
534                   List the available remote LTTng tracing sessions for the
535                   LTTng relay daemon at the address RDHOST and port RDPORT
536                   (5344 if not specified), and then exit.
537
538               net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION
539                   Use the source.ctf.lttng-live component class.
540
541                   See babeltrace2-source.ctf.lttng-live(7) to learn more
542                   about this component class and the URL format.
543
544           You can specify at most one --input-format option.
545
546       -o FORMAT, --output-format=FORMAT
547           Create an implicit sink component with format FORMAT or print the
548           metadata text of a CTF trace.
549
550           The available values for FORMAT are:
551
552           text
553               Create an implicit sink.text.pretty component.
554
555               See “Implicit sink.text.pretty component”.
556
557               See babeltrace2-sink.text.pretty(7) to learn more about this
558               component class.
559
560           ctf
561               Create an implicit sink.ctf.fs component. Specify the base
562               output path with the --output option.
563
564               See babeltrace2-sink.ctf.fs(7) to learn more about this
565               component class.
566
567           dummy
568               Create an implicit sink.utils.dummy component.
569
570               See babeltrace2-sink.utils.dummy(7) to learn more about this
571               component class.
572
573           ctf-metadata
574               Print the metadata text of a CTF trace and exit.
575
576               The first non-option argument specifies the path to the CTF
577               trace.
578
579           You can specify at most one --output-format option.
580
581   Implicit source.ctf.fs component(s)
582       See babeltrace2-source.ctf.fs(7) to learn more about this component
583       class.
584
585       --clock-force-correlate
586           Set the force-clock-class-origin-unix-epoch initialization
587           parameter of all the implicit source.ctf.fs components to true.
588
589           The force-clock-class-origin-unix-epoch initialization parameter
590           makes all the created clock classes have a Unix epoch origin. This
591           is useful to force the clock classes of multiple traces to be
592           compatible even if they are not inherently.
593
594       --clock-offset=SEC
595           Set the clock-class-offset-s initialization parameter of all the
596           implicit source.ctf.fs components to SEC.
597
598           The clock-class-offset-s initialization parameter adds SEC seconds
599           to the offsets of all the clock classes that the component creates.
600
601           You can combine this option with --clock-offset-ns.
602
603       --clock-offset-ns=NS
604           Set the clock-class-offset-ns initialization parameter of all the
605           implicit source.ctf.fs components to NS.
606
607           The clock-class-offset-ns initialization parameter adds NS
608           nanoseconds to the offsets of all the clock classes that the
609           component creates.
610
611           You can combine this option with --clock-offset-s.
612
613   Implicit filter.utils.trimmer component
614       If you specify at least one of the following options, you create an
615       implicit filter.utils.trimmer component.
616
617       See babeltrace2-filter.utils.trimmer(7) to learn more about this
618       component class.
619
620       --begin=TIME
621           Set the begin initialization parameter of the component to TIME.
622
623           You cannot use this option with the --timerange option.
624
625           The format of TIME is one of:
626
627               YYYY-MM-DD HH:II[:SS[.NANO]]
628               HH:II[:SS[.NANO]]
629               [-]SEC[.NANO]
630
631           YYYY
632               4-digit year.
633
634           MM
635               2-digit month (January is 01).
636
637           DD
638               2-digit day.
639
640           HH
641               2-digit hour (24-hour format).
642
643           II
644               2-digit minute.
645
646           SS
647               2-digit second.
648
649           NANO
650               Nanoseconds (up to nine digits).
651
652           SEC
653               Seconds since origin.
654
655       --end=TIME
656           Set the end initialization parameter of the component to TIME.
657
658           You cannot use this option with the --timerange option.
659
660           See the --begin option for the format of TIME.
661
662       --timerange=BEGIN,END
663           Equivalent to --begin=BEGIN and --end=END.
664
665           You can also surround the whole argument with [ and ].
666
667   Implicit filter.lttng-utils.debug-info component
668       If you specify at least one of the following options, you create an
669       implicit filter.lttng-utils.debug-info component. This component only
670       alters compatible LTTng events.
671
672       See babeltrace2-filter.lttng-utils.debug-info(7) to learn more about
673       this component class.
674
675       --debug-info
676           Create an implicit filter.lttng-utils.debug-info component.
677
678           This option is useless if you specify any of the options below.
679
680       --debug-info-dir=DIR
681           Set the debug-info-dir initialization parameter of the component to
682           DIR.
683
684           The debug-info-dir parameter indicates where the component should
685           find the debugging information it needs if it’s not found in the
686           actual executable files.
687
688       --debug-info-full-path
689           Set the full-path initialization parameter of the component to
690           true.
691
692           When the full-path parameter is true, the component writes the full
693           (absolute) paths to files in its debugging information fields
694           instead of just the short names.
695
696       --debug-info-target-prefix=PREFIX
697           Set the target-prefix initialization parameter of the component to
698           PREFIX.
699
700           The target-prefix parameter is a path to prepend to the paths to
701           executables recorded in the trace. For example, if a trace contains
702           the executable path /usr/bin/ls in its state dump events, and you
703           specify --debug-info-target-prefix=/home/user/boards/xyz/root, then
704           the component opens the /home/user/boards/xyz/root/usr/bin/ls file
705           to find debugging information.
706
707   Implicit sink.text.pretty component
708       If you specify at least one of the following options, you force the
709       convert command’s sink component to be an implicit sink.text.pretty
710       component.
711
712       See babeltrace2-sink.text.pretty(7) to learn more about this component
713       class.
714
715       --clock-cycles
716           Set the clock-seconds initialization parameter of the component to
717           true.
718
719           The clock-cycles parameter makes the component print the event time
720           in clock cycles.
721
722       --clock-date
723           Set the clock-date initialization parameter of the component to
724           true.
725
726           The clock-date parameter makes the component print the date and the
727           time of events.
728
729       --clock-gmt
730           Set the clock-gmt initialization parameter of the component to
731           true.
732
733           The clock-gmt parameter makes the component not apply the local
734           timezone to the printed times.
735
736       --clock-seconds
737           Set the clock-seconds initialization parameter of the component to
738           true.
739
740           The clock-seconds parameter makes the component print the event
741           times in seconds since the Unix epoch.
742
743       --color=WHEN
744           Set the color initialization parameter of the component to WHEN.
745
746           The available values for WHEN are:
747
748           auto
749               Only emit terminal color codes when the standard output and
750               error streams are connected to a color-capable terminal.
751
752           never
753               Never emit terminal color codes.
754
755           always
756               Always emit terminal color codes.
757
758           The auto and always values have no effect if the
759           BABELTRACE_TERM_COLOR environment variable is set to NEVER.
760
761       --fields=FIELD[,FIELD]...
762           For each FIELD, set the field-FIELD initialization parameter of the
763           component to true.
764
765           For example, --fields=trace,loglevel,emf sets the field-trace,
766           field-loglevel, and field-emf initialization parameters to true.
767
768           The available value for FIELD are:
769
770           ·   trace
771
772           ·   trace:hostname
773
774           ·   trace:domain
775
776           ·   trace:procname
777
778           ·   trace:vpid
779
780           ·   loglevel
781
782           ·   emf
783
784           ·   callsite
785
786       --names=NAME[,NAME]...
787           For each NAME, set the name-NAME initialization parameter of the
788           component to true.
789
790           For example, --names=payload,scope sets the name-payload and name-
791           scope initialization parameters to true.
792
793           The available value for NAME are:
794
795           ·   payload
796
797           ·   context
798
799           ·   scope
800
801           ·   header
802
803       --no-delta
804           Set the no-delta initialization parameter of the component to true.
805
806           When the no-delta parameter is true, the component does not print
807           the duration since the last event on the line.
808
809   Shared options
810       -w PATH, --output=PATH
811           With --output-format=ctf-metadata or --input-format=lttng-live
812           (when printing the available remote LTTng tracing sessions), write
813           the text to the file PATH instead of the standard output.
814
815           When you specify --output-format=ctf, set the path initialization
816           parameter of the implicit sink.ctf.fs component to PATH.
817
818           Without any specified sink component, explicit or implicit, force
819           the convert command’s sink component to be an implicit
820           sink.text.pretty component and set its path initialization
821           parameter to PATH.
822
823           See babeltrace2-sink.ctf.fs(7) and babeltrace2-sink.text.pretty(7)
824           to learn more about those component classes.
825
826   Equivalent babeltrace2 run arguments
827       --run-args
828           Print the equivalent babeltrace2-run(1) arguments instead of
829           creating and running the conversion graph.
830
831           The printed arguments are space-separated and individually escaped
832           for safe shell input.
833
834           You cannot use this option with the --run-args-0 or --stream-
835           intersection option.
836
837       --run-args-0
838           Print the equivalent babeltrace2-run(1) arguments instead of
839           creating and running the conversion graph.
840
841           The printed arguments are separated with a null character and NOT
842           escaped for safe shell input.
843
844           You cannot use this option with the --run-args or --stream-
845           intersection option.
846
847   Conversion graph configuration
848       --retry-duration=TIME-US
849           Set the duration of a single retry to TIME-US µs when a sink
850           component reports "try again later" (busy network or file system,
851           for example).
852
853           Default: 100000 (100 ms).
854
855       --stream-intersection
856           Enable the stream intersection mode.
857
858           In this mode, for each trace, the convert command filters out the
859           events and other messages which are not in the time range where all
860           the trace’s streams are active.
861
862           To use this option, all the source components, explicit and
863           implicit, must have classes which support the babeltrace.trace-
864           infos query object (see babeltrace2-query-babeltrace.trace-
865           infos(7)). The only Babeltrace 2 project’s component class which
866           supports this query object is source.ctf.fs.
867
868           You cannot use this option with the --run-args or --run-args-0
869           option.
870
871   Other legacy options
872       The following options exist for backward compatibility with the
873       babeltrace(1) program.
874
875       -d, --debug
876           Legacy option: this is equivalent to --log-level=TRACE, where
877           --log-level is the general option (not this command’s --log-level
878           option).
879
880       -v, --verbose
881           Legacy option: this is equivalent to --log-level=INFO, where --log-
882           level is the general option (not this command’s --log-level
883           option).
884
885           This option also sets the verbose parameter of the implicit
886           sink.text.pretty component (see babeltrace2-sink.text.pretty(7)) to
887           true.
888
889   Command information
890       -h, --help
891           Show the command’s help and quit.
892

EXAMPLES

894       Example 1. Pretty-print the events, in order, of one or more CTF
895       traces.
896
897           $ babeltrace2 my-ctf-traces
898
899           $ babeltrace2 my-ctf-traces
900
901           $ babeltrace2 my-ctf-trace-1 my-ctf-trace-2 my-ctf-trace-3
902
903       Example 2. Trim a CTF trace and pretty-print the events.
904
905           $ babeltrace2 my-ctf-trace --begin=22:55:43.658582931 \
906                                      --end=22:55:46.967687564
907
908           $ babeltrace2 my-trace --begin=22:55:43.658582931
909
910           $ babeltrace2 my-trace --end=22:55:46.967687564
911
912           $ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564
913
914       Example 3. Trim a CTF trace, enable the stream intersection mode, and
915       write a CTF trace.
916
917           $ babeltrace2 my-ctf-trace --stream-intersection \
918                         --timerange=22:55:43,22:55:46.967687564 \
919                         --output-format=ctf --output=out-ctf-trace
920
921       Example 4. Print the available remote LTTng sessions (through LTTng
922       live).
923
924           $ babeltrace2 --input-format=lttng-live net://localhost
925
926       Example 5. Pretty-print LTTng live events.
927
928           $ babeltrace2 net://localhost/host/myhostname/my-session-name
929
930       Example 6. Record LTTng live traces to the file system (as CTF traces).
931
932           $ babeltrace2 net://localhost/host/myhostname/my-session-name \
933                         --params=session-not-found-action=end \
934                         --output-format=ctf --output=out-ctf-traces
935
936       Example 7. Read a CTF trace as fast as possible using a dummy output.
937
938           $ babeltrace2 my-trace --output-format=dummy
939
940       Example 8. Read three CTF traces in stream intersection mode, add
941       debugging information, and pretty-print them to a file.
942
943           $ babeltrace2 ctf-trace1 ctf-trace2 ctf-trace3 --stream-intersection \
944                         --debug-info --output=pretty-out
945
946       Example 9. Pretty-print a CTF trace and traces from an explicit source
947       component, with the event times showed in seconds since the Unix epoch.
948
949           $ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
950                         --params='path="spec-trace",output-some-event-type=yes' \
951                         --clock-seconds
952
953       Example 10. Send LTTng live events to an explicit sink component.
954
955           $ babeltrace2 net://localhost/host/myhostname/mysession \
956                         --component=sink.my-plugin.my-sink
957
958       Example 11. Trim a CTF trace, add debugging information, apply an
959       explicit filter component, and write as a CTF trace.
960
961           $ babeltrace2 /path/to/ctf/trace --timerange=22:14:38,22:15:07 \
962                         --debug-info --component=filter.my-plugin.my-filter \
963                         --params=criteria=xyz,ignore-abc=yes \
964                         --output-format=ctf --output=out-ctf-trace
965
966       Example 12. Print the metadata text of a CTF trace.
967
968           $ babeltrace2 /path/to/ctf/trace --output-format=ctf-metadata
969

ENVIRONMENT VARIABLES

971   Babeltrace 2 library
972       BABELTRACE_EXEC_ON_ABORT=CMDLINE
973           Execute the command line CMDLINE, as parsed like a UNIX 98 shell,
974           when any part of the Babeltrace 2 project unexpectedly aborts.
975
976           The application only aborts when the executed command returns,
977           ignoring its exit status.
978
979           This environment variable is ignored when the application has the
980           setuid or the setgid access right flag set.
981
982       BABELTRACE_TERM_COLOR=(AUTO | NEVER | ALWAYS)
983           Force the terminal color support for the babeltrace2(1) program and
984           the project’s plugins.
985
986           The available values are:
987
988           AUTO
989               Only emit terminal color codes when the standard output and
990               error streams are connected to a color-capable terminal.
991
992           NEVER
993               Never emit terminal color codes.
994
995           ALWAYS
996               Always emit terminal color codes.
997
998       BABELTRACE_TERM_COLOR_BRIGHT_MEANS_BOLD=0
999           Set to 0 to emit SGR (see
1000           <https://en.wikipedia.org/wiki/ANSI_escape_code>) codes 90 to 97
1001           for bright colors instead of bold (SGR code 1) and standard color
1002           codes (SGR codes 30 to 37).
1003
1004       BABELTRACE_PLUGIN_PATH=PATHS
1005           Set the list of directories, in order, in which dynamic plugins can
1006           be found before other directories are considered to PATHS
1007           (colon-separated, or semicolon on Windows).
1008
1009       LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS=1
1010           Disable the loading of any Babeltrace 2 Python plugin.
1011
1012       LIBBABELTRACE2_INIT_LOG_LEVEL=LVL
1013           Force the Babeltrace 2 library’s initial log level to be LVL.
1014
1015           If this environment variable is set, it overrides the log level set
1016           by the --log-level option for the Babeltrace 2 library logger.
1017
1018           The available values for LVL are:
1019
1020           NONE, N
1021               Logging is disabled.
1022
1023           FATAL, F
1024               Severe errors that lead the execution to abort immediately.
1025
1026               This level should be enabled in production.
1027
1028           ERROR, E
1029               Errors that might still allow the execution to continue.
1030
1031               Usually, once one or more errors are reported at this level,
1032               the application, plugin, or library won’t perform any more
1033               useful task, but it should still exit cleanly.
1034
1035               This level should be enabled in production.
1036
1037           WARN, WARNING, W
1038               Unexpected situations which still allow the execution to
1039               continue.
1040
1041               This level should be enabled in production.
1042
1043           INFO, I
1044               Informational messages that highlight progress or important
1045               states of the application, plugins, or library.
1046
1047               This level can be enabled in production.
1048
1049           DEBUG, D
1050               Debugging information, with a higher level of details than the
1051               TRACE level.
1052
1053               This level should NOT be enabled in production.
1054
1055           TRACE, T
1056               Low-level debugging context information.
1057
1058               This level should NOT be enabled in production.
1059
1060       LIBBABELTRACE2_NO_DLCLOSE=1
1061           Make the Babeltrace 2 library leave any dynamically loaded modules
1062           (plugins and plugin providers) open at exit. This can be useful for
1063           debugging purposes.
1064
1065       LIBBABELTRACE2_PLUGIN_PROVIDER_DIR=DIR
1066           Set the directory from which the Babeltrace 2 library dynamically
1067           loads plugin provider shared objects to DIR.
1068
1069           If this environment variable is set, it overrides the default
1070           plugin provider directory.
1071
1072   Babeltrace 2 Python bindings
1073       BABELTRACE_PYTHON_BT2_LOG_LEVEL=LVL
1074           Force the Babeltrace 2 Python bindings log level to be LVL.
1075
1076           If this environment variable is set, it overrides the log level set
1077           by the --log-level option for the Python bindings logger.
1078
1079           The available values for LVL are:
1080
1081           NONE, N
1082               Logging is disabled.
1083
1084           FATAL, F
1085               Severe errors that lead the execution to abort immediately.
1086
1087               This level should be enabled in production.
1088
1089           ERROR, E
1090               Errors that might still allow the execution to continue.
1091
1092               Usually, once one or more errors are reported at this level,
1093               the application, plugin, or library won’t perform any more
1094               useful task, but it should still exit cleanly.
1095
1096               This level should be enabled in production.
1097
1098           WARN, WARNING, W
1099               Unexpected situations which still allow the execution to
1100               continue.
1101
1102               This level should be enabled in production.
1103
1104           INFO, I
1105               Informational messages that highlight progress or important
1106               states of the application, plugins, or library.
1107
1108               This level can be enabled in production.
1109
1110           DEBUG, D
1111               Debugging information, with a higher level of details than the
1112               TRACE level.
1113
1114               This level should NOT be enabled in production.
1115
1116           TRACE, T
1117               Low-level debugging context information.
1118
1119               This level should NOT be enabled in production.
1120
1121   CLI
1122       BABELTRACE_CLI_LOG_LEVEL=LVL
1123           Force babeltrace2 CLI’s log level to be LVL.
1124
1125           If this environment variable is set, it overrides the log level set
1126           by the --log-level option for the CLI logger.
1127
1128           The available values for LVL are:
1129
1130           NONE, N
1131               Logging is disabled.
1132
1133           FATAL, F
1134               Severe errors that lead the execution to abort immediately.
1135
1136               This level should be enabled in production.
1137
1138           ERROR, E
1139               Errors that might still allow the execution to continue.
1140
1141               Usually, once one or more errors are reported at this level,
1142               the application, plugin, or library won’t perform any more
1143               useful task, but it should still exit cleanly.
1144
1145               This level should be enabled in production.
1146
1147           WARN, WARNING, W
1148               Unexpected situations which still allow the execution to
1149               continue.
1150
1151               This level should be enabled in production.
1152
1153           INFO, I
1154               Informational messages that highlight progress or important
1155               states of the application, plugins, or library.
1156
1157               This level can be enabled in production.
1158
1159           DEBUG, D
1160               Debugging information, with a higher level of details than the
1161               TRACE level.
1162
1163               This level should NOT be enabled in production.
1164
1165           TRACE, T
1166               Low-level debugging context information.
1167
1168               This level should NOT be enabled in production.
1169
1170       BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH=0
1171           Disable the warning message which babeltrace2-convert(1) prints
1172           when you convert a trace with a relative path that’s also the name
1173           of a babeltrace2 command.
1174
1175       BABELTRACE_DEBUG=1
1176           Legacy variable: equivalent to setting the --log-level option to
1177           TRACE.
1178
1179       BABELTRACE_VERBOSE=1
1180           Legacy variable: equivalent to setting the --log-level option to
1181           INFO.
1182

FILES

1184       $HOME/.local/lib/babeltrace2/plugins
1185           User plugin directory.
1186
1187       /usr/local/lib/babeltrace2/plugins
1188           System plugin directory.
1189
1190       /usr/local/lib/babeltrace2/plugin-providers
1191           System plugin provider directory.
1192

EXIT STATUS

1194       0 on success, 1 otherwise.
1195

BUGS

1197       If you encounter any issue or usability problem, please report it on
1198       the Babeltrace bug tracker (see
1199       <https://bugs.lttng.org/projects/babeltrace>).
1200

RESOURCES

1202       The Babeltrace project shares some communication channels with the
1203       LTTng project (see <https://lttng.org/>).
1204
1205       ·   Babeltrace website (see <https://babeltrace.org/>)
1206
1207       ·   Mailing list (see <https://lists.lttng.org>) for support and
1208           development: lttng-dev@lists.lttng.org
1209
1210       ·   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
1211           irc.oftc.net
1212
1213       ·   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
1214
1215       ·   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
1216
1217       ·   GitHub project (see <https://github.com/efficios/babeltrace>)
1218
1219       ·   Continuous integration (see
1220           <https://ci.lttng.org/view/Babeltrace/>)
1221
1222       ·   Code review (see <https://review.lttng.org/q/project:babeltrace>)
1223

AUTHORS

1225       The Babeltrace 2 project is the result of hard work by many regular
1226       developers and occasional contributors.
1227
1228       The current project maintainer is Jérémie Galarneau
1229       <mailto:jeremie.galarneau@efficios.com>.
1230

COPYRIGHT

1232       This command is part of the Babeltrace 2 project.
1233
1234       Babeltrace is distributed under the MIT license (see
1235       <https://opensource.org/licenses/MIT>).
1236