doc/man/babeltrace2-convert.1.txt

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