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='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 *babeltrace 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:babeltrace-intro(7) to learn more about the Babeltrace
  47 project and its core concepts.
  48
  49 [NOTE]
  50 ====
  51 `convert` is the default man:babeltrace(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:babeltrace(1)
  54 command's name, like `run` or `list-plugins`:
  55
  56 [role="term"]
  57 ----
  58 $ babeltrace convert ...
  59 $ babeltrace ...
  60 ----
  61
  62 If you need to make sure that you are executing the `convert` command,
  63 use `babeltrace 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:babeltrace-run(1) command.
  93
  94 Like with the man:babeltrace-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 $ babeltrace /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 $ babeltrace 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:babeltrace-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 $ babeltrace run $(babeltrace --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:babeltrace-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 $ babeltrace /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 $ babeltrace --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 $ babeltrace --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 $ babeltrace /path/to/trace --begin=22:14:38 --end=22:15:07
 282 ----
 283 +
 284 [role="term"]
 285 ----
 286 $ babeltrace /path/to/trace --timerange=22:14:38,22:15:07
 287 ----
 288 +
 289 [role="term"]
 290 ----
 291 $ babeltrace /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 $ babeltrace --debug-info /path/to/trace
 304 ----
 305 +
 306 [role="term"]
 307 ----
 308 $ babeltrace /path/to/trace \
 309              --debug-info-target-prefix=/tmp/tgt-root
 310 ----
 311 +
 312 [role="term"]
 313 ----
 314 $ babeltrace /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 $ babeltrace /path/to/trace
 342 ----
 343 +
 344 [role="term"]
 345 ----
 346 $ babeltrace /path/to/trace --no-delta
 347 ----
 348 +
 349 [role="term"]
 350 ----
 351 $ babeltrace /path/to/trace --output-format=text
 352 ----
 353 +
 354 [role="term"]
 355 ----
 356 $ babeltrace /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 $ babeltrace /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 $ babeltrace /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 $ babeltrace /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:babeltrace-run(1) command of this `convert` command
 395 is:
 396
 397 [role="term"]
 398 ----
 399 $ babeltrace 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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-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:babeltrace-sink.ctf.fs(7) and
 795 man:babeltrace-sink.text.pretty(7) to learn more about those
 796 component classes.
 797
 798
 799 Equivalent `babeltrace run` arguments
 800 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 801 opt:--run-args::
 802     Print the equivalent man:babeltrace-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:babeltrace-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 `trace-info` query object to use this option. The only Babeltrace
 837 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:babeltrace-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/babeltrace/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 $ babeltrace my-trace
 873 ----
 874
 875 [role="term"]
 876 ----
 877 $ babeltrace my-traces
 878 ----
 879
 880 [role="term"]
 881 ----
 882 $ babeltrace 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 $ babeltrace my-trace --begin=22:55:43.658582931 \
 891              --end=22:55:46.967687564
 892 ----
 893
 894 [role="term"]
 895 ----
 896 $ babeltrace my-trace --begin=22:55:43.658582931
 897 ----
 898
 899 [role="term"]
 900 ----
 901 $ babeltrace my-trace --end=22:55:46.967687564
 902 ----
 903
 904 [role="term"]
 905 ----
 906 $ babeltrace 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 $ babeltrace 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 $ babeltrace --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 $ babeltrace 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 $ babeltrace 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 $ babeltrace 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 $ babeltrace --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 $ babeltrace /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 $ babeltrace /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 $ babeltrace --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:babeltrace(1),
1004 man:babeltrace-run(1),
1005 man:babeltrace-intro(7)