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