Add `babeltrace.` prefix to `trace-info` and `support-info` query objects
[babeltrace.git] / doc / man / babeltrace2-convert.1.txt
1 babeltrace2-convert(1)
2 =====================
3 :manpagetype: command
4 :revdate: 5 October 2017
5
6
7 NAME
8 ----
9 babeltrace2-convert - Convert one or more traces
10
11
12 SYNOPSIS
13 --------
14 Convert one or more traces:
15
16 [verse]
17 *babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
18 [opt:--omit-system-plugin-path]
19 [opt:--plugin-path='PATH'[:__PATH__]...]
20 [opt:--run-args | opt:--run-args-0] [opt:--retry-duration='DURUS']
21 'CONVERSION ARGUMENTS'
22
23 Print the metadata text of a CTF trace:
24
25 [verse]
26 *babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
27 [opt:--omit-system-plugin-path]
28 [opt:--plugin-path='PATH'[:__PATH__]...]
29 [opt:--output='OUTPATH']
30 opt:--output-format=`ctf-metadata` 'TRACE-PATH'
31
32 Print the available http://lttng.org/docs/#doc-lttng-live[LTTng live]
33 sessions:
34
35 [verse]
36 *babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
37 [opt:--omit-system-plugin-path]
38 [opt:--plugin-path='PATH'[:__PATH__]...]
39 [opt:--output='OUTPATH'] opt:--input-format=`lttng-live` 'URL'
40
41
42 DESCRIPTION
43 -----------
44 The `convert` command creates a trace conversion graph and runs it.
45
46 See man:babeltrace2-intro(7) to learn more about the Babeltrace
47 project and its core concepts.
48
49 [NOTE]
50 ====
51 `convert` is the default man:babeltrace2(1) command: you usually don't
52 need to specify its name. The following commands are equivalent
53 if the `...` part does not start with another man:babeltrace2(1)
54 command's name, like `run` or `list-plugins`:
55
56 [role="term"]
57 ----
58 $ babeltrace2 convert ...
59 $ babeltrace2 ...
60 ----
61
62 If you need to make sure that you are executing the `convert` command,
63 use `babeltrace2 convert` explicitly.
64 ====
65
66 A conversion graph is a specialized trace processing graph focused on
67 the conversion of one or more traces to another format, possibly
68 filtering their events and other notifications in the process. A
69 conversion graph is a linear chain of components after the source
70 streams are merged:
71
72 ----
73 +----------+
74 | source 1 |-.
75 +----------+ |
76 | +-------+
77 +----------+ '->| | +---------+ +------------+
78 | source 2 |--->| muxer |--->| trimmer |--->| debug-info |-.
79 +----------+ .->| | +---------+ +------------+ |
80 | +-------+ |
81 +----------+ | .----------------------------------------'
82 | ... |-' | +---------------+ +------+
83 +----------+ '->| other filters |--->| sink |
84 +---------------+ +------+
85 ----
86
87 Note that the trimmer, debugging information, and other filters are
88 optional. See <<comp-create-impl,Create implicit components>> to learn
89 how to enable them.
90
91 If you need another processing graph layout, use the more flexible
92 man:babeltrace2-run(1) command.
93
94 Like with the man:babeltrace2-run(1) command, you can create components
95 explicitly with the opt:--component option (see
96 <<comp-create-expl,Create explicit components>>). You can also use one
97 of the many specific `convert` command options and arguments to create
98 implicit components from known component classes (see
99 <<comp-create-impl,Create implicit components>>). For example, you can
100 specify a single path argument to print the merged events of a CTF trace
101 on the console:
102
103 [role="term"]
104 ----
105 $ babeltrace2 /path/to/trace
106 ----
107
108 This is the equivalent of creating and connecting together:
109
110 * A compcls:src.ctf.fs component with its manparam:source.ctf.fs:path
111 initialization parameter set to `/path/to/trace`.
112
113 * A compcls:filter.utils.muxer component.
114
115 * A compcls:sink.text.pretty component.
116
117 This creates the following conversion graph:
118
119 ----
120 +------------+ +--------------------+ +------------------+
121 | src.ctf.fs | | filter.utils.muxer | | sink.text.pretty |
122 | [ctf-fs] | | [muxer] | | [pretty] |
123 | | | | | |
124 | stream0 @--->@ out @--->@ in |
125 | stream1 @--->@ | +------------------+
126 | stream2 @--->@ |
127 | stream3 @--->@ |
128 +------------+ +--------------------+
129 ----
130
131 It is equivalent to the following command:
132
133 [role="term"]
134 ----
135 $ babeltrace2 run --component=ctf-fs:src.ctf.fs \
136 --params=path=/path/to/trace \
137 --component=pretty:sink.text.pretty \
138 --component=muxer:filter.utils.muxer \
139 --connect=ctf-fs:muxer --connect=muxer:pretty
140 ----
141
142 You can use the opt:--run-args option to make the `convert` command
143 print its equivalent man:babeltrace2-run(1) arguments instead of
144 creating and running the conversion graph. The printed arguments are
145 escaped for shells, which means you can use them as is on the command
146 line and possibly add more options to the `run` command:
147
148 [role="term"]
149 ----
150 $ babeltrace2 run $(babeltrace2 --run-args /path/to/trace) ...
151 ----
152
153 The opt:--run-args-0 option is like the opt:--run-args option, but the
154 printed arguments are :not: escaped and they are separated by a null
155 character instead of a space. This is useful if the resulting arguments
156 are not the direct input of a shell, for example if passed to
157 `xargs -0`.
158
159 See <<examples,EXAMPLES>> for usage examples.
160
161
162 [[comp-create-expl]]
163 Create explicit components
164 ~~~~~~~~~~~~~~~~~~~~~~~~~~
165 To explicitly create a component, use the opt:--component option. This
166 option specifies:
167
168 * **Optional**: The name of the component instance. You can also use the
169 opt:--name option for this.
170
171 * The type of the component class to instantiate: source, filter, or
172 sink.
173
174 * The name of the plugin in which to find the component class to
175 instantiate.
176
177 * The name of the component class to instantiate.
178
179 You can use the opt:--component option multiple times to create
180 multiple components. You can instantiate the same component class
181 multiple times as different component instances.
182
183 Immediately following a opt:--component option on the command line, the
184 created component is known as the _current component_ (until the next
185 opt:--component option).
186
187 The following, optional command-line options apply to the current
188 component:
189
190 opt:--name='NAME'::
191 Set the name of the current component to 'NAME'.
192
193 opt:--params='PARAMS'::
194 Add 'PARAMS' to the initialization parameters of the current
195 component. If 'PARAMS' contains a key which exists in the current
196 component's initialization parameters, this parameter is replaced.
197 +
198 See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
199
200 opt:--path='PATH'::
201 Set the nlparam:path initialization parameter of the current
202 component to 'PATH' (replace the parameter if it exists).
203 +
204 You can use this option instead of manually specifying `path="PATH"` in
205 a opt:--params option to use your shell's tilde expansion (`~`). Tilde
206 expansion requires the tilde to be the first character of the argument,
207 which is not possible with `path="PATH"`.
208
209 opt:--url='URL'::
210 Set the nlparam:url initialization parameter of the current
211 component to 'URL' (replace the parameter if it exists).
212
213 See <<examples,EXAMPLES>> for usage examples.
214
215
216 [[comp-create-impl]]
217 Create implicit components
218 ~~~~~~~~~~~~~~~~~~~~~~~~~~
219 An _implicit component_ is a component which is created and added to the
220 conversion graph without an explicit instantiation through the
221 opt:--component option. An implicit component is easier to create than
222 an explicit component: this is why the `convert` command exists, as you
223 can also create and run a conversion graph with the generic
224 man:babeltrace2-run(1) command.
225
226 There are many ways to create implicit components with the `convert`
227 command:
228
229 * To create one or more implicit compcls:src.ctf.fs components (CTF
230 trace read from the file system), use one or more positional arguments
231 to specify the paths to the CTF traces to read, and do :not: specify
232 the opt:--input-format=`lttng-live` option.
233 +
234 Example:
235 +
236 [role="term"]
237 ----
238 $ babeltrace2 /path/to/trace /path/to/other/trace
239 ----
240 +
241 The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_
242 the implicit compcls:src.ctf.fs components. For example:
243 +
244 [role="term"]
245 ----
246 $ babeltrace2 --clock-offset=3 trace1 trace2
247 ----
248 +
249 With the command line above, two implicit compcls:src.ctf.fs components
250 have their manparam:source.ctf.fs:clock-class-offset-s initialization
251 parameter set to `3`, but they have different
252 manparam:source.ctf.fs:path parameters (`trace1` and `trace2`).
253 +
254 You cannot create implicit compcls:src.ctf.fs components and an implicit
255 compcls:src.ctf.lttng-live component.
256
257 * To create an implicit compcls:src.ctf.lttng-live component
258 (http://lttng.org/docs/#doc-lttng-live[LTTng live] input), specify the
259 opt:--input-format=`lttng-live` option and the LTTng relay daemon's
260 URL with the positional argument.
261 +
262 Example:
263 +
264 [role="term"]
265 ----
266 $ babeltrace2 --input-format=lttng-live \
267 net://localhost/host/abeille/my-session
268 ----
269 +
270 You cannot create an implicit compcls:src.ctf.lttng-live component and
271 implicit compcls:src.ctf.fs components.
272
273 * To create an implicit compcls:filter.utils.trimmer component (trace
274 trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
275 option.
276 +
277 Examples:
278 +
279 [role="term"]
280 ----
281 $ babeltrace2 /path/to/trace --begin=22:14:38 --end=22:15:07
282 ----
283 +
284 [role="term"]
285 ----
286 $ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07
287 ----
288 +
289 [role="term"]
290 ----
291 $ babeltrace2 /path/to/trace --end=12:31:04.882928015
292 ----
293
294 * To create an implicit compcls:filter.lttng-utils.debug-info (add
295 debugging information to compatible LTTng events), specify any of the
296 opt:--debug-info, opt:--debug-info-dir, opt:--debug-info-full-path, or
297 opt:--debug-info-target-prefix options.
298 +
299 Examples:
300 +
301 [role="term"]
302 ----
303 $ babeltrace2 --debug-info /path/to/trace
304 ----
305 +
306 [role="term"]
307 ----
308 $ babeltrace2 /path/to/trace \
309 --debug-info-target-prefix=/tmp/tgt-root
310 ----
311 +
312 [role="term"]
313 ----
314 $ babeltrace2 /path/to/trace --debug-info-full-path
315 ----
316
317 * To create an implicit compcls:sink.text.pretty component
318 (pretty-printing text output to the console or to a file), do any of:
319 +
320 --
321 * Specify no other sink components, <<comp-create-expl,explicit>> or
322 implicit. The compcls:sink.text.pretty implicit component is the
323 _default_ implicit sink component. If any other explicit or implicit
324 component exists, the default compcls:sink.text.pretty sink component
325 is not automatically created.
326
327 * Specify any of the opt:--clock-cycles, opt:--clock-date,
328 opt:--clock-gmt, opt:--clock-seconds, opt:--color, opt:--fields,
329 opt:--names, or opt:--no-delta options. You can also specify the
330 opt:--output option without using the opt:--output-format=`ctf` option
331 (in which case opt:--output applies to the implicit
332 compcls:sink.ctf.fs component).
333
334 * Specify the opt:--output-format=`text` option.
335 --
336 +
337 Examples:
338 +
339 [role="term"]
340 ----
341 $ babeltrace2 /path/to/trace
342 ----
343 +
344 [role="term"]
345 ----
346 $ babeltrace2 /path/to/trace --no-delta
347 ----
348 +
349 [role="term"]
350 ----
351 $ babeltrace2 /path/to/trace --output-format=text
352 ----
353 +
354 [role="term"]
355 ----
356 $ babeltrace2 /path/to/trace --output=/tmp/pretty-out
357 ----
358
359 * To create an implicit compcls:sink.utils.dummy component (dummy
360 output), specify the opt:--output-format=`dummy` option. This option
361 disables the default implicit compcls:sink.text.pretty component.
362 +
363 Example:
364 +
365 [role="term"]
366 ----
367 $ babeltrace2 /path/to/trace --output-format=dummy
368 ----
369
370 * To create an implicit compcls:sink.ctf.fs component (CTF traces
371 written to the file system), specify the opt:--output-format=`ctf`
372 option. This option disables the default implicit
373 compcls:sink.text.pretty component. Use the opt:--output option to
374 specify the output directory.
375 +
376 Example:
377 +
378 [role="term"]
379 ----
380 $ babeltrace2 /path/to/input/trace --output-format=ctf \
381 --output=my-traces
382 ----
383
384 You can combine multiple methods to create implicit components. For
385 example, you can trim an LTTng (CTF) trace, add debugging information to
386 it, and write it as another CTF trace:
387
388 [role="term"]
389 ----
390 $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \
391 --debug-info --output-format=ctf --output=out-dir
392 ----
393
394 The equivalent man:babeltrace2-run(1) command of this `convert` command
395 is:
396
397 [role="term"]
398 ----
399 $ babeltrace2 run --component=src-ctf-fs:src.ctf.fs \
400 --params=path=/path/to/input/trace \
401 --component=sink-ctf-fs:sink.ctf.fs \
402 --params=path=out-dir \
403 --component=muxer:flt.utils.muxer \
404 --component=trimmer:flt.utils.trimmer \
405 '--params=begin="22:14:38"' \
406 '--params=end="22:15:07"' \
407 --component=dbginfo:flt.lttng-utils.debug-info \
408 --connect=src-ctf-fs:muxer --connect=muxer:trimmer \
409 --connect=trimmer:dbg-info \
410 --connect=dbginfo:sink-ctf-fs
411 ----
412
413 See <<examples,EXAMPLES>> for more examples.
414
415
416 include::common-cmd-params-format.txt[]
417
418
419 [[time-fmt]]
420 Time option format
421 ~~~~~~~~~~~~~~~~~~
422 The format of the arguments of the opt:--begin and opt:--end options
423 is:
424
425 [verse]
426 $$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
427
428 'YYYY'::
429 4-digit year.
430
431 'MM'::
432 2-digit month (January is `01`).
433
434 'DD'::
435 2-digit day.
436
437 'hh'::
438 2-digit hour (24-hour format).
439
440 'mm'::
441 2-digit minute.
442
443 'ss'::
444 2-digit second.
445
446 'nnnnnnnnn'::
447 9-digit nanosecond.
448
449
450 include::common-cmd-plugin-path.txt[]
451
452
453 OPTIONS
454 -------
455 include::common-gen-options.txt[]
456
457
458 Explicit component creation
459 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
460 See <<comp-create-expl,Create explicit components>> to learn how to
461 use the following options.
462
463 opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
464 Create a component initially named 'NAME' (if specified) from the
465 component class of type 'TYPE' named 'COMPCLS' found in the plugin
466 named 'PLUGIN', and set it as the current component.
467 +
468 The available values for 'TYPE' are:
469 +
470 --
471 `source`::
472 `src`::
473 Source component class.
474
475 `filter`::
476 `flt`::
477 Filter component class.
478
479 `sink`::
480 Sink component class.
481 --
482
483 opt:--name='NAME'::
484 Set the name of the current component to 'NAME'. The names of all
485 the explicitly created components in the conversion graph must be
486 unique.
487
488 opt:-p 'PARAMS', opt:--params='PARAMS'::
489 Add 'PARAMS' to the initialization parameters of the current
490 component. If 'PARAMS' contains a key which exists in the current
491 component's initialization parameters, replace the parameter.
492 See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
493
494 opt:-P 'PATH', opt:--path='PATH'::
495 Set the nlparam:path initialization parameter of the current
496 component to 'PATH' (replace the parameter if it exists).
497
498 opt:-u 'URL', opt:--url='URL'::
499 Set the nlparam:url initialization parameter of the current
500 component to 'URL' (replace the parameter if it exists).
501
502
503 Legacy options to create implicit components
504 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
505 opt:-i 'FORMAT', opt:--input-format='FORMAT'::
506 Create one or more implicit source components. The available values
507 for 'FORMAT' are:
508 +
509 --
510 `ctf`::
511 Create an implicit compcls:src.ctf.fs component for each positional
512 argument. Each positional argument sets the
513 manparam:source.ctf.fs:path initialization parameter of an
514 individual component. See <<impl-opts-ctf,Implicit
515 compcls:src.ctf.fs component>>.
516 +
517 See man:babeltrace2-source.ctf.fs(7) to learn more about this
518 component class.
519
520 `lttng-live`::
521 Depending on the format of the positional argument:
522 +
523 --
524 `net[4]://RDHOST[:RDPORT]/host/TGTHOST`::
525 Print the available LTTng live sessions of the LTTng relay daemon at
526 the address `RDHOST` and port `RDPORT`, and then exit.
527
528 `net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`::
529 Create an implicit compcls:src.ctf.lttng-live component. The
530 position argument sets the manparam:source.ctf.lttng-live:url
531 parameter of the component.
532 +
533 Any other format for the positional argument is invalid.
534 +
535 See man:babeltrace2-source.ctf.lttng-live(7) to learn more about
536 this component class.
537 --
538 --
539 +
540 You can specify at most one opt:--input-format option.
541
542 opt:-o 'FORMAT', opt:--output-format='FORMAT'::
543 Create an implicit sink component. The available values for 'FORMAT'
544 are:
545 +
546 --
547 `text`::
548 Create an implicit compcls:sink.text.pretty component.
549 See <<impl-opts-text,Implicit compcls:sink.text.pretty component>>.
550 +
551 See man:babeltrace2-sink.text.pretty(7) to learn more about
552 this component class.
553
554 `ctf`::
555 Create an implicit compcls:sink.ctf.fs component. Specify the output
556 path with the opt:--output option.
557 +
558 See man:babeltrace2-sink.ctf.fs(7) to learn more about
559 this component class.
560
561 `dummy`::
562 Create an implicit compcls:sink.utils.dummy component.
563 +
564 See man:babeltrace2-sink.utils.dummy(7) to learn more about
565 this component class.
566
567 `ctf-metadata`::
568 Print the metadata text of a CTF trace and exit. The first
569 positional argument specifies the path to the CTF trace.
570 --
571 +
572 You can specify at most one opt:--output-format option.
573
574
575 [[impl-opts-ctf]]
576 Implicit compcls:src.ctf.fs component(s)
577 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
578 There is one implicit compcls:src.ctf.fs component per positional
579 argument (which are trace paths), unless you specify
580 opt:--input-format=`lttng-live`.
581
582 See man:babeltrace2-source.ctf.fs(7) to learn more about this
583 component class.
584
585 opt:--clock-offset='SEC'::
586 Set the manparam:source.ctf.fs:clock-class-offset-s initialization
587 parameter of all the implicit compcls:src.ctf.fs components to
588 'SEC'.
589 +
590 The manparam:source.ctf.fs:clock-class-offset-s initialization parameter
591 adds 'SEC' seconds to the offsets of all the clock classes that the
592 component creates.
593 +
594 You can combine this option with opt:--clock-offset-ns.
595
596 opt:--clock-offset-ns='NS'::
597 Set the manparam:source.ctf.fs:clock-class-offset-ns initialization
598 parameter of all the implicit compcls:src.ctf.fs components to
599 'NS'.
600 +
601 The manparam:source.ctf.fs:clock-class-offset-ns initialization
602 parameter adds 'NS' nanoseconds to the offsets of all the clock classes
603 that the component creates.
604 +
605 You can combine this option with opt:--clock-offset-s.
606
607
608 Implicit compcls:filter.utils.trimmer component
609 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
610 If you specify at least one of the following options, you create an
611 implicit compcls:filter.utils.trimmer component.
612
613 See man:babeltrace2-filter.utils.trimmer(7) to learn more about
614 this component class.
615
616 See <<time-fmt,Time option format>> for the format of 'BEGIN' and 'END'.
617
618 opt:--begin='BEGIN'::
619 Set the manparam:filter.utils.trimmer:begin initialization parameter
620 of the component to 'BEGIN'. You cannot use this option with the
621 opt:--timerange option.
622
623 opt:--end='END'::
624 Set the manparam:filter.utils.trimmer:end initialization parameter
625 of the component to 'END'. You cannot use this option with the
626 opt:--timerange option.
627
628 opt:--timerange='BEGIN','END'::
629 Equivalent to opt:--begin='BEGIN' opt:--end='END'.
630 +
631 You can also surround the whole argument with `[` and `]`.
632
633
634 Implicit compcls:filter.lttng-utils.debug-info component
635 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
636 If you specify at least one of the following options, you create an
637 implicit compcls:filter.lttng-utils.debug-info component. This component
638 only alters compatible LTTng events.
639
640 See man:babeltrace2-filter.lttng-utils.debug-info(7) to learn more
641 about this component class.
642
643 opt:--debug-info::
644 Create an implicit compcls:filter.lttng-utils.debug-info component.
645 This option is useless if you specify any of the options below.
646
647 opt:--debug-info-dir='DIR'::
648 Set the manparam:filter.lttng-utils.debug-info:debug-info-dir
649 initialization parameter of the component to 'DIR'.
650 +
651 The manparam:filter.lttng-utils.debug-info:debug-info-dir parameter
652 indicates where the component should find the debugging information it
653 needs if it's not found in the actual executable files.
654
655 opt:--debug-info-full-path::
656 Set the manparam:filter.lttng-utils.debug-info:full-path
657 initialization parameter of the component to true.
658 +
659 When the manparam:filter.lttng-utils.debug-info:full-path parameter is
660 true, the component writes the full (absolute) paths to files in its
661 debugging information fields instead of just the short names.
662
663 opt:--debug-info-target-prefix='PREFIX'::
664 Set the manparam:filter.lttng-utils.debug-info:target-prefix
665 initialization parameter of the component to 'PREFIX'.
666 +
667 The manparam:filter.lttng-utils.debug-info:target-prefix parameter is a
668 path to prepend to the paths to executables recorded in the trace. For
669 example, if a trace contains the executable path `/usr/bin/ls` in its
670 state dump events, and you specify
671 opt:--debug-info-target-prefix=`/home/user/boards/xyz/root`, then the
672 component opens the `/home/user/boards/xyz/root/usr/bin/ls` file to find
673 debugging information.
674
675
676 [[impl-opts-text]]
677 === Implicit compcls:sink.text.pretty component
678
679 If you specify at least one of the following options, you create an
680 implicit compcls:sink.text.pretty component. The `convert` command also
681 creates a default implicit compcls:sink.text.pretty component if no
682 other sink component exists.
683
684 See man:babeltrace2-sink.text.pretty(7) to learn more about this
685 component class.
686
687 opt:--clock-cycles::
688 Set the manparam:sink.text.pretty:clock-seconds initialization
689 parameter of the component to true.
690 +
691 The manparam:sink.text.pretty:clock-cycles parameter makes the component
692 print the event time in clock cycles.
693
694 opt:--clock-date::
695 Set the manparam:sink.text.pretty:clock-date initialization
696 parameter of the component to true.
697 +
698 The manparam:sink.text.pretty:clock-date parameter makes the component
699 print the date and the time of events.
700
701 opt:--clock-gmt::
702 Set the manparam:sink.text.pretty:clock-gmt initialization parameter
703 of the component to true.
704 +
705 The manparam:sink.text.pretty:clock-gmt parameter makes the component
706 not apply the local timezone to the printed times.
707
708 opt:--clock-seconds::
709 Set the manparam:sink.text.pretty:clock-seconds initialization
710 parameter of the component to true.
711 +
712 The manparam:sink.text.pretty:clock-seconds parameter makes the
713 component print the event times in seconds since Epoch.
714
715 opt:--color='WHEN'::
716 Set the manparam:sink.text.pretty:color initialization parameter of
717 the component to 'WHEN'.
718 +
719 The available values for 'WHEN' are:
720 +
721 --
722 `auto`::
723 Automatic color support depending on the capabilities of the
724 terminal(s) to which the standard output and error streams are
725 connected.
726
727 `never`::
728 Never emit terminal color codes.
729
730 `always`::
731 Always emit terminal color codes.
732 --
733 +
734 The `auto` and `always` values have no effect if the
735 `BABELTRACE_TERM_COLOR` environment variable is set to `NEVER`.
736
737 opt:--fields='FIELD'[,'FIELD']...::
738 For each 'FIELD', set the nlparam:field-FIELD initialization
739 parameter of the component to true.
740 +
741 For example, opt:--fields=`trace,loglevel,emf` sets the
742 manparam:sink.text.pretty:field-trace,
743 manparam:sink.text.pretty:field-loglevel, and
744 manparam:sink.text.pretty:field-emf initialization parameters to true.
745 +
746 The available value for 'FIELD' are:
747 +
748 * `trace`
749 * `trace:hostname`
750 * `trace:domain`
751 * `trace:procname`
752 * `trace:vpid`
753 * `loglevel`
754 * `emf`
755 * `callsite`
756
757 opt:--names='NAME'[,'NAME']...::
758 For each 'NAME', set the nlparam:name-NAME initialization parameter
759 of the component to true.
760 +
761 For example, opt:--names=`payload,scope` sets the
762 manparam:sink.text.pretty:name-payload and
763 manparam:sink.text.pretty:name-scope initialization parameters to true.
764 +
765 The available value for 'NAME' are:
766 +
767 * `payload`
768 * `context`
769 * `scope`
770 * `header`
771
772 opt:--no-delta::
773 Set the manparam:sink.text.pretty:no-delta initialization parameter
774 of the component to true.
775 +
776 When the manparam:sink.text.pretty:no-delta parameter is true, the
777 component does not print the duration since the last event on the line.
778
779
780 Shared options
781 ~~~~~~~~~~~~~~
782 opt:-w 'PATH', opt:--output='PATH'::
783 With opt:--output-format=`ctf-metadata` or
784 opt:--input-format=`lttng-live` (when printing the available LTTng
785 live sessions), write the text to the file 'PATH' instead of the
786 standard output.
787 +
788 When you specify opt:--output-format=`ctf`, set the
789 manparam:sink.ctf.fs:path initialization parameter of the implicit
790 compcls:sink.ctf.fs component to 'PATH'. Otherwise, create an implicit
791 compcls:sink.text.pretty component and set its
792 manparam:sink.text.pretty:path initialization parameter to 'PATH'.
793 +
794 See man:babeltrace2-sink.ctf.fs(7) and
795 man:babeltrace2-sink.text.pretty(7) to learn more about those
796 component classes.
797
798
799 Equivalent `babeltrace2 run` arguments
800 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
801 opt:--run-args::
802 Print the equivalent man:babeltrace2-run(1) arguments instead of
803 creating and running the conversion graph. The printed arguments are
804 space-separated and individually escaped for safe shell input.
805 +
806 You cannot use this option with the opt:--run-args-0 or
807 opt:--stream-intersection option.
808
809 opt:--run-args-0::
810 Print the equivalent man:babeltrace2-run(1) arguments instead of
811 creating and running the conversion graph. The printed arguments are
812 separated with a null character and :not: escaped for safe shell
813 input.
814 +
815 You cannot use this option with the opt:--run-args or
816 opt:--stream-intersection option.
817
818
819 Conversion graph configuration
820 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
821 opt:--retry-duration='DURUS'::
822 Set the duration of a single retry to 'DURUS'{nbsp}µs when a
823 component reports "try again later" (busy network or file system,
824 for example).
825 +
826 Default: 100000 (100{nbsp}ms).
827
828 opt:--stream-intersection::
829 Enable the stream intersection mode. In this mode, for each trace,
830 the `convert` command filters out the events and other notifications
831 which are not in the time range where _all_ the trace's streams are
832 active.
833 +
834 All the source components, <<comp-create-expl,explicit>> and
835 <<comp-create-impl,implicit>>, must have classes which support the
836 `babeltrace.trace-info` query object to use this option. The only
837 Babeltrace project's component class which supports this query object is
838 compcls:source.ctf.fs.
839 +
840 Because it is not possible to replicate with a single
841 man:babeltrace2-run(1) command line what the `convert` method does with
842 the opt:--stream-intersection option, you cannot use this option with
843 the opt:--run-args or opt:--run-args-0 option.
844
845
846 Plugin path
847 ~~~~~~~~~~~
848 opt:--omit-home-plugin-path::
849 Do not search for plugins in `$HOME/.local/lib/babeltrace2/plugins`.
850
851 opt:--omit-system-plugin-path::
852 Do not search for plugins in +{system_plugin_path}+.
853
854 opt:--plugin-path='PATH'[:__PATH__]...::
855 Add 'PATH' to the list of paths in which dynamic plugins can be
856 found.
857
858
859 Command information
860 ~~~~~~~~~~~~~~~~~~~
861 opt:-h, opt:--help::
862 Show command help and quit.
863
864
865 [[examples]]
866 EXAMPLES
867 --------
868 .Pretty-print the events of one or more CTF traces.
869 ====
870 [role="term"]
871 ----
872 $ babeltrace2 my-trace
873 ----
874
875 [role="term"]
876 ----
877 $ babeltrace2 my-traces
878 ----
879
880 [role="term"]
881 ----
882 $ babeltrace2 my-trace-1 my-trace-2 my-trace-3
883 ----
884 ====
885
886 .Trim a CTF trace and pretty-print the events.
887 ====
888 [role="term"]
889 ----
890 $ babeltrace2 my-trace --begin=22:55:43.658582931 \
891 --end=22:55:46.967687564
892 ----
893
894 [role="term"]
895 ----
896 $ babeltrace2 my-trace --begin=22:55:43.658582931
897 ----
898
899 [role="term"]
900 ----
901 $ babeltrace2 my-trace --end=22:55:46.967687564
902 ----
903
904 [role="term"]
905 ----
906 $ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564
907 ----
908 ====
909
910 .Trim a CTF trace, enable the stream intersection mode, and generate a CTF trace.
911 ====
912 [role="term"]
913 ----
914 $ babeltrace2 my-trace --stream-intersection \
915 --timerange=22:55:43,22:55:46.967687564 \
916 --output-format=ctf --output=out-trace
917 ----
918 ====
919
920 .Record LTTng live traces to the file system (as CTF traces).
921 ====
922 [role="term"]
923 ----
924 $ babeltrace2 --input-format=lttng-live \
925 net://localhost/host/myhostname/auto-20170411-134512 \
926 --output-format=ctf --output=/path/to/generated/traces
927 ----
928 ====
929
930 .Read a CTF trace as fast as possible using a dummy output.
931 ====
932 [role="term"]
933 ----
934 $ babeltrace2 my-trace --output-format=dummy
935 ----
936 ====
937
938 .Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file.
939 ====
940 [role="term"]
941 ----
942 $ babeltrace2 trace1 trace2 trace3 --stream-intersection \
943 --debug-info --output=pretty-out
944 ----
945 ====
946
947 .Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since Epoch.
948 ====
949 [role="term"]
950 ----
951 $ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
952 --params=output-some-event-type=yes --clock-seconds
953 ----
954 ====
955
956 .Send LTTng live events to an explicit sink component.
957 ====
958 [role="term"]
959 ----
960 $ babeltrace2 --input-format=lttng-live \
961 net://localhost/host/myhostname/mysession \
962 --component=sink.my-plugin.my-sink
963 ----
964 ====
965
966 .Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace.
967 ====
968 [role="term"]
969 ----
970 $ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07 \
971 --debug-info --component=filter.my-plugin.my-filter \
972 --params=criteria=xyz,ignore-abc=yes \
973 --output-format=ctf --output=out-trace
974 ----
975 ====
976
977 .Print the metadata text of a CTF trace.
978 ====
979 [role="term"]
980 ----
981 $ babeltrace2 /path/to/trace --output-format=ctf-metadata
982 ----
983 ====
984
985 .Print the available LTTng live sessions of an LTTng relay daemon.
986 ====
987 [role="term"]
988 ----
989 $ babeltrace2 --input-format=lttng-live net://localhost
990 ----
991 ====
992
993
994 include::common-cli-env.txt[]
995
996 include::common-cli-files.txt[]
997
998 include::common-cmd-footer.txt[]
999
1000
1001 SEE ALSO
1002 --------
1003 man:babeltrace2(1),
1004 man:babeltrace2-run(1),
1005 man:babeltrace2-intro(7)
This page took 0.051636 seconds and 4 git commands to generate.