doc/man/babeltrace-convert.1.txt

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