--- name: "babeltrace2-convert" section: "1" platform: "linux" package: "babeltrace2" version: "2.1.1-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/babeltrace2-convert" --- # babeltrace2-convert(1) Convert one or more traces to a given format ## NAME babeltrace2-convert - Convert one or more traces to a given format ## SYNOPSIS Pretty-print (plain text) the events, in order, of one or more traces: ``` babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US] [--allowed-mip-versions=VERSION] TRACE-PATH... ``` Convert one or more traces to a given format: ``` babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US] [--allowed-mip-versions=VERSION] CONVERSION ARGS ``` Get the equivalent [**babeltrace2-run**(1)](/babeltrace2-run/1.md) command arguments to convert one or more traces to a given format: ``` babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US] [--allowed-mip-versions=VERSION] (--run-args | --run-args-0) CONVERSION ARGS ``` Print the metadata text of a CTF trace: ``` babeltrace2 [GENERAL OPTIONS] [convert] [--output=OUTPATH] --output-format=ctf-metadata TRACE-PATH ``` Print the available remote LTTng tracing sessions (see \): ``` babeltrace2 [GENERAL OPTIONS] [convert] [--output=OUTPATH] --input-format=lttng-live URL ``` ## DESCRIPTION The **convert** command converts one or more traces to a given format, possibly with filters in the conversion path. See [**babeltrace2-intro**(7)](/babeltrace2-intro/7.md) to learn more about the Babeltrace 2 project and its core concepts. **Note**\ **convert** is the default [**babeltrace2**(1)](/babeltrace2/1.md) command: you generally don’t need to specify its name. The following commands are equivalent if the **...** part doesn’t start with the name of another [**babeltrace2**(1)](/babeltrace2/1.md) command, like **run** or **list-plugins**: ``` $ babeltrace2 convert ... $ babeltrace2 ... ``` If you need to make sure that you are executing the **convert** command, then use **babeltrace2 convert** explicitly. More specifically, the **convert** command creates a conversion graph. A conversion graph is a specialized trace processing graph focused on the conversion of one or more traces to another format, possibly filtering or modifying their events and other messages in the process. A conversion graph is a linear chain of components once the source streams are merged: ``` +----------+ | source 1 @-. +----------+ | | +-------+ +----------+ '->@ | +---------+ +------------+ | source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-. +----------+ .->@ | +---------+ +------------+ | | +-------+ | +----------+ | .----------------------------------------' | ... @-' | +---------------+ +------+ +----------+ '->@ other filters |--->@ sink | +---------------+ +------+ ``` Note that the trimmer, debugging information, and other filters are optional. See “Create implicit components from options” to learn how to enable them. If you need another trace processing graph layout, then use the more flexible [**babeltrace2-run**(1)](/babeltrace2-run/1.md) command. Like with the [**babeltrace2-run**(1)](/babeltrace2-run/1.md) command, you can create components explicitly with the **--component** option (see “Create explicit components”). You can also use one of the many specific **convert** command options (see “Create implicit components from options”) and non-option arguments (see “Create implicit components from non-option arguments”) to create implicit components. An *implicit component* is a component which is created and added to the conversion graph without an explicit instantiation through the **--component** option. An implicit component is easier to create than an explicit component: this is why the **convert** command exists, as you can also create and run a conversion graph with the generic [**babeltrace2-run**(1)](/babeltrace2-run/1.md) command. For example, you can specify one or more CTF trace path as non-option arguments to pretty-print the merged events to the standard output: ``` $ babeltrace2 /path/to/trace /path/to/other/trace ``` This is the equivalent of creating and connecting together: • One **source.ctf.fs** components with its **inputs** initialization parameter set to **/path/to/trace**. • One **source.ctf.fs** components with its **inputs** initialization parameter set to **/path/to/other/trace**. • A **filter.utils.muxer** component. • A **sink.text.pretty** component. This creates the following conversion graph: ``` +------------+ +-----------------+ +------------------+ | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty | | [ctf-fs] | | [muxer] | | [pretty] | | | | | | | | stream0 @--->@ in0 out @--->@ in | | stream1 @--->@ in1 | +------------------+ | stream2 @--->@ in2 | | stream3 @--->@ in3 | +------------+ | | | | +------------+ | | | src.ctf.fs | | | | [ctf-fs-2] | | | | | | | | stream0 @--->@ in4 | | stream1 @--->@ in5 | +------------+ @ in6 | +-----------------+ ``` It’s equivalent to the following [**babeltrace2-run**(1)](/babeltrace2-run/1.md) command line: ``` $ babeltrace2 run --component=ctf-fs:src.ctf.fs \ --params='inputs=["/path/to/trace"] \ --component=ctf-fs-2:src.ctf.fs \ --params='inputs=["/path/to/other/trace"] \ --component=muxer:filter.utils.muxer \ --component=pretty:sink.text.pretty \ --connect=ctf*:muxer --connect=muxer:pretty ``` You can use the **--run-args** option to make the **convert** command print its equivalent **run** command arguments instead of creating and running the conversion graph. The printed arguments are escaped for shells, which means you can use them as is on the command line and possibly add more options to the **run** command: ``` $ babeltrace2 run $(babeltrace2 --run-args /path/to/trace) ... ``` The **--run-args-0** option is like the **--run-args** option, but the printed arguments are NOT escaped and they’re separated by a null character instead of a space. This is useful if the resulting arguments aren’t the direct input of a shell, for example if passed to **xargs -0**. See “EXAMPLES” for usage examples. ### Create explicit components To explicitly create a component, use the **--component** option. This option specifies: • **Optional**: The name of the component. • The type of the component class to instantiate: source, filter, or sink. • The name of the plugin in which to find the component class to instantiate. • The name of the component class to instantiate. You can use the **--component** option multiple times to create multiple components. You can instantiate the same component class multiple times as different component instances. Immediately following a **--component** option on the command line, the created component is known as the *current component* (until the next **--component** option or non-option argument). The following command-line options apply to the current component: - **--log-level**=*LVL* Set the log level of the current component to *LVL*. - **--params**=*PARAMS* Add *PARAMS* to the initialization parameters of the current component. If *PARAMS* contains a key which exists in the initialization parameters of the current component, then replace the parameter. See “EXAMPLES” for usage examples. ### Create implicit components from non-option arguments When you specify a non-option argument to the **convert** command, it tries to find one or more components which can handle this argument. For example, with this command line: ``` $ babeltrace2 /path/to/trace ``` If **/path/to/trace** is a CTF trace directory, then the **convert** command creates a **source.ctf.fs** component to handle this specific trace. This automatic source component discovery mechanism is possible thanks to component classes which support the **babeltrace.support-info** query object (see [**babeltrace2-query-babeltrace.support-info**(7)](/babeltrace2-query-babeltrace.support-info/7.md)). The non-option argument can be a directory. If no component can handle that specific directory, then the **convert** command traverses that directory and recursively tries to find compatible components for each file and subdirectory. This means that a single non-option argument can lead to the creation of many implicit components. The following command-line options apply to ALL the implicit components created from the last non-option argument: - **--log-level**=*LVL* Set the log level of those implicit components to *LVL*. - **--params**=*PARAMS* Add *PARAMS* to the initialization parameters of those implicit components. For a given implicit component, if *PARAMS* contains a key which exists in the initialization parameters of this component, then replace the parameter. Note that it’s also possible for two non-option arguments to cause the creation of a single implicit component. For example, if you specify: ``` $ babeltrace2 /path/to/chunk1 /path/to/chunk2 ``` where **/path/to/chunk1** and **/path/to/chunk2** are paths to chunks of the same logical CTF trace, then the **convert** command creates a single **source.ctf.fs** component which receives both paths at initialization time. When this happens, any **--log-level** or **--params** option that you specify to one of them applies to the single implicit component. For example: ``` $ babeltrace2 /path/to/chunk1 --params=clock-class-offset-s=450 \ /path/to/chunk2 --params=clock-class-offset-ns=98 \ --log-level=INFO ``` Here, the single implicit component gets both **clock-class-offset-s** and **clock-class-offset-ns** initialization parameters, as well as the INFO log level. For backward compatibility with the [**babeltrace**(1)](/babeltrace/1.md) program, the **convert** command ignores any non-option argument which does not cause the creation of any component. In that case, it emits a warning log statement and continues. ### Create implicit components from options There are many ways to create implicit components from options with the **convert** command: • To create an implicit **filter.utils.trimmer** component (stream trimmer), specify the **--begin**, **--end**, or **--timerange** option. Examples: ``` $ babeltrace2 /path/to/trace --begin=22:14:38 --end=22:15:07 ``` ``` $ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07 ``` ``` $ babeltrace2 /path/to/trace --end=12:31:04.882928015 ``` • To create an implicit **filter.lttng-utils.debug-info** (add debugging information to compatible LTTng events), specify any of the **--debug-info**, **--debug-info-dir**, **--debug-info-full-path**, or **--debug-info-target-prefix** options. Examples: ``` $ babeltrace2 /path/to/trace --debug-info ``` ``` $ babeltrace2 /path/to/trace \ --debug-info-target-prefix=/tmp/tgt-root ``` ``` $ babeltrace2 /path/to/trace --debug-info-full-path ``` • To create an implicit **sink.text.pretty** component (pretty-printing text output to the standard output or to a file), specify no other sink components, explicit or implicit. The implicit **sink.text.pretty** component exists by default. If any other explicit or implicit sink component exists, then the **convert** command doesn’t automatically create the implicit **sink.text.pretty** component. The **--clock-cycles**, **--clock-date**, **--clock-gmt**, **--clock-seconds**, **--color**, **--fields**, **--names**, and **--no-delta** options all apply to the implicit **sink.text.pretty** component. The **--output** option without **--output-format**=**ctf** makes the implicit **sink.text.pretty** component write its content to a file, except the warnings for backward compatibility with the [**babeltrace**(1)](/babeltrace/1.md) program. Examples: ``` $ babeltrace2 /path/to/trace ``` ``` $ babeltrace2 /path/to/trace --no-delta ``` ``` $ babeltrace2 /path/to/trace --output=/tmp/pretty-out ``` • To create an implicit **sink.utils.dummy** component (no output), specify the **--output-format**=**dummy** option. Example: ``` $ babeltrace2 /path/to/trace --output-format=dummy ``` • To create an implicit **sink.ctf.fs** component (CTF traces written to the file system), specify the **--output-format**=**ctf** and the **--output**=*DIR* (base output directory) options. Example: ``` $ babeltrace2 /path/to/input/trace --output-format=ctf \ --output=my-traces ``` As of this version, a **sink.ctf.fs** component generates CTF 2 (see \) traces by default. To write CTF 1.8 (see \) traces, create an explicit **sink.ctf.fs** component (see “Create explicit components”) and use the **ctf-version="1"** initialization parameter: ``` $ babeltrace2 /path/to/input/trace --component=sink.ctf.fs \ --params='path="my-traces",ctf-version="1"' ``` You can combine multiple methods to create multiple implicit components. For example, you can trim an LTTng (CTF) trace, add debugging information to it, and write it as another CTF trace: ``` $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \ --debug-info --output-format=ctf --output=out-dir ``` The equivalent [**babeltrace2-run**(1)](/babeltrace2-run/1.md) command of this **convert** command is: ``` $ babeltrace2 run --component=auto-disc-source-ctf-fs:source.ctf.fs \ --params='inputs=["/path/to/input/trace"]' \ --component=sink-ctf-fs:sink.ctf.fs \ --params='path="out-dir"' \ --component=muxer:filter.utils.muxer \ --component=trimmer:filter.utils.trimmer \ --params='begin="22:14:38"' \ --params='end="22:15:07"' \ --component=debug-info:filter.lttng-utils.debug-info \ --connect=auto-disc-source-ctf-fs:muxer \ --connect=muxer:trimmer \ --connect=trimmer:debug-info \ --connect=debug-info:sink-ctf-fs ``` The order of the implicit component options documented in this subsection isn’t significant. See “EXAMPLES” for more examples. ## OPTIONS ### General You can use those options before the command name. See [**babeltrace2**(1)](/babeltrace2/1.md) for more details. - **-d**, **--debug** Legacy option: this is equivalent to **--log-level**=**TRACE**. - **-l** *LVL*, **--log-level**=*LVL* Set the log level of all known Babeltrace 2 loggers to *LVL*. - **--omit-home-plugin-path** Don’t search for plugins in **$HOME/.local/lib/babeltrace2/plugins**. - **--omit-system-plugin-path** Don’t search for plugins in **/usr/lib/babeltrace2/plugins**. - **--plugin-path**=*PATH*\[:*PATH*\]... Add *PATH* to the list of paths in which plugins can be found. - **-v**, **--verbose** Legacy option: this is equivalent to **--log-level**=**INFO**. ### Explicit component creation See “Create explicit components” to learn how to use the following option. - **-c** \[*NAME*:\]*COMP-CLS-TYPE*.*PLUGIN-NAME*.*COMP-CLS-NAME*, **--component**=\[*NAME*:\]*COMP-CLS-TYPE*.*PLUGIN-NAME*.*COMP-CLS-NAME* Create a component named *NAME* (if specified) from the component class of type *COMP-CLS-TYPE* named *COMP-CLS-NAME* found in the plugin named *PLUGIN-NAME*, and set it as the current component. The available values for *COMP-CLS-TYPE* are: **source**, **src** Source component class. **filter**, **flt** Filter component class. **sink** Sink component class. ### Common component creation See “Create explicit components” and “Create implicit components from non-option arguments” to learn how to use the following options. The following options apply to either the current explicit component (last **--component** option) or to ALL the implicit components created from the last non-option argument. - **-l** *LVL*, **--log-level**=*LVL* Set the log level of the current component(s) to *LVL*. The available values for *LVL* are: **NONE**, **N** Logging is disabled. **FATAL**, **F** Severe errors that lead the execution to abort immediately. This level should be enabled in production. **ERROR**, **E** Errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won’t perform any more useful task, but it should still exit cleanly. This level should be enabled in production. **WARN**, **WARNING**, **W** Unexpected situations which still allow the execution to continue. This level should be enabled in production. **INFO**, **I** Informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production. **DEBUG**, **D** Debugging information, with a higher level of details than the **TRACE** level. This level should NOT be enabled in production. **TRACE**, **T** Low-level debugging context information. This level should NOT be enabled in production. - **-p** *PARAMS*, **--params**=*PARAMS* Add *PARAMS* to the initialization parameters of the current component(s). If *PARAMS* contains a key which exists in the initialization parameters of the current component(s), then replace the parameter. The format of *PARAMS* is a comma-separated list of *NAME*=*VALUE* assignments: ``` NAME=VALUE[,NAME=VALUE]... ``` *NAME* Parameter name (C identifier plus the **:**, **.**, and **-** characters). *VALUE* One of: • **null**, **nul**, **NULL**: null value. • **true**, **TRUE**, **yes**, **YES**: true boolean value. • **false**, **FALSE**, **no**, **NO**: false boolean value. • Binary (**0b** prefix), octal (**0** prefix), decimal, or hexadecimal (**0x** prefix) unsigned (with **+** prefix) or signed 64-bit integer. • Double precision floating point number (scientific notation is accepted). • Unquoted string with no special characters, and not matching any of the null and boolean value symbols above. • Double-quoted string (accepts escape characters). • Array, formatted as an opening **\[**, a comma-separated list of *VALUE*, and a closing **\]**. • Map, formatted as an opening **{**, a comma-separated list of *NAME*=*VALUE* assignments, and a closing **}**. You may put whitespaces around the individual **=** (assignment), **,** (separator), **\[** (array beginning), **\]** (array end), **{** (map beginning), and **}** (map end) characters. Example: ``` --params='many=null, fresh=yes, condition=false, squirrel=-782329, play=+23, observe=3.14, simple=beef, needs-quotes="some string", escape.chars-are:allowed="a \" quote", things=[1, "hello", 2.71828], frog={slow=2, bath=[bike, 23], blind=NO}' ``` **Important**\ Like in the example above, make sure to single-quote the whole argument when you run this command from a shell, as it can contain many special characters. ### Legacy options to create implicit components - **-i** *FORMAT*, **--input-format**=*FORMAT* Force the **convert** command to create components from a specific component class for non-option arguments (see “Create implicit components from non-option arguments”), or list available remote LTTng tracing sessions. The available values for *FORMAT* are: **ctf** Use the **source.ctf.fs** component class. Each non-option argument of the command line is a CTF trace or CTF trace chunk. See [**babeltrace2-source.ctf.fs**(7)](/babeltrace2-source.ctf.fs/7.md) to learn more about this component class. **lttng-live** Depending on the format of the first non-option argument: **net\[4\]://RDHOST\[:RDPORT\]** List the available remote LTTng tracing sessions for the LTTng relay daemon at the address **RDHOST** and port **RDPORT** (5344 if not specified), and then exit. **net\[4\]://RDHOST\[:RDPORT\]/host/TGTHOST/SESSION** Use the **source.ctf.lttng-live** component class. See [**babeltrace2-source.ctf.lttng-live**(7)](/babeltrace2-source.ctf.lttng-live/7.md) to learn more about this component class and the URL format. You can specify at most one **--input-format** option. - **-o** *FORMAT*, **--output-format**=*FORMAT* Create an implicit sink component with format *FORMAT* or print the metadata text of a CTF trace. The available values for *FORMAT* are: **text** Create an implicit **sink.text.pretty** component. See “Implicit **sink.text.pretty** component”. See [**babeltrace2-sink.text.pretty**(7)](/babeltrace2-sink.text.pretty/7.md) to learn more about this component class. **ctf** Create an implicit **sink.ctf.fs** component. Specify the base output path with the **--output** option. As of this version, a **sink.ctf.fs** component generates CTF 2 (see \) traces by default. To write CTF 1.8 (see \) traces, create an explicit **sink.ctf.fs** component (see “Create explicit components”) and use the **ctf-version="1"** initialization parameter. See [**babeltrace2-sink.ctf.fs**(7)](/babeltrace2-sink.ctf.fs/7.md) to learn more about this component class. **dummy** Create an implicit **sink.utils.dummy** component. See [**babeltrace2-sink.utils.dummy**(7)](/babeltrace2-sink.utils.dummy/7.md) to learn more about this component class. **ctf-metadata** Print the metadata text of a CTF trace and exit. The first non-option argument specifies the path to the CTF trace. You can specify at most one **--output-format** option. ### Implicit source.ctf.fs component(s) See [**babeltrace2-source.ctf.fs**(7)](/babeltrace2-source.ctf.fs/7.md) to learn more about this component class. - **--clock-force-correlate** Set the **force-clock-class-origin-unix-epoch** initialization parameter of all the implicit **source.ctf.fs** components to true. The **force-clock-class-origin-unix-epoch** initialization parameter makes all the created clock classes have a Unix epoch origin. This is useful to force the clock classes of multiple traces to be compatible even if they’re not inherently. - **--clock-offset**=*SEC* Set the **clock-class-offset-s** initialization parameter of all the implicit **source.ctf.fs** components to *SEC*. The **clock-class-offset-s** initialization parameter adds *SEC* seconds to the offsets of all the clock classes that the component creates. You can combine this option with **--clock-offset-ns**. - **--clock-offset-ns**=*NS* Set the **clock-class-offset-ns** initialization parameter of all the implicit **source.ctf.fs** components to *NS*. The **clock-class-offset-ns** initialization parameter adds *NS* nanoseconds to the offsets of all the clock classes that the component creates. You can combine this option with **--clock-offset-s**. ### Implicit filter.utils.trimmer component If you specify at least one of the following options, you create an implicit **filter.utils.trimmer** component. See [**babeltrace2-filter.utils.trimmer**(7)](/babeltrace2-filter.utils.trimmer/7.md) to learn more about this component class. - **--begin**=*TIME* Set the **begin** initialization parameter of the component to *TIME*. You cannot use this option with the **--timerange** option. The format of *TIME* is one of: ``` YYYY-MM-DD HH:II[:SS[.NANO]] HH:II[:SS[.NANO]] [-]SEC[.NANO] ``` *YYYY* 4-digit year. *MM* 2-digit month (January is **01**). *DD* 2-digit day. *HH* 2-digit hour (24-hour format). *II* 2-digit minute. *SS* 2-digit second. *NANO* Nanoseconds (up to nine digits). *SEC* Seconds since origin. - **--end**=*TIME* Set the **end** initialization parameter of the component to *TIME*. You cannot use this option with the **--timerange** option. See the **--begin** option for the format of *TIME*. - **--timerange**=*BEGIN*,*END* Equivalent to **--begin**=*BEGIN* and **--end**=*END*. You can also surround the whole argument with **\[** and **\]**. ### Implicit filter.lttng-utils.debug-info component If you specify at least one of the following options, you create an implicit **filter.lttng-utils.debug-info** component. This component only alters compatible LTTng events. See [**babeltrace2-filter.lttng-utils.debug-info**(7)](/babeltrace2-filter.lttng-utils.debug-info/7.md) to learn more about this component class. - **--debug-info** Create an implicit **filter.lttng-utils.debug-info** component. This option is useless if you specify any of the options below. - **--debug-info-dir**=*DIR* Set the **debug-info-dir** initialization parameter of the component to *DIR*. The **debug-info-dir** parameter indicates where the component should find the debugging information it needs if it’s not found in the actual executable files. - **--debug-info-full-path** Set the **full-path** initialization parameter of the component to true. When the **full-path** parameter is true, the component writes the full (absolute) paths to files in its debugging information fields instead of just the short names. - **--debug-info-target-prefix**=*PREFIX* Set the **target-prefix** initialization parameter of the component to *PREFIX*. The **target-prefix** parameter is a path to prepend to the paths to executables recorded in the trace. For example, if a trace contains the executable path **/usr/bin/ls** in its state dump events, and you specify **--debug-info-target-prefix**=**/home/user/boards/xyz/root**, then the component opens the **/home/user/boards/xyz/root/usr/bin/ls** file to find debugging information. ### Implicit sink.text.pretty component If you specify at least one of the following options, then you force the sink component of the **convert** command to be an implicit **sink.text.pretty** component. See [**babeltrace2-sink.text.pretty**(7)](/babeltrace2-sink.text.pretty/7.md) to learn more about this component class. - **--clock-cycles** Set the **clock-seconds** initialization parameter of the component to true. The **clock-cycles** parameter makes the component print the event time in clock cycles. - **--clock-date** Set the **clock-date** initialization parameter of the component to true. The **clock-date** parameter makes the component print the date and the time of events. - **--clock-gmt** Set the **clock-gmt** initialization parameter of the component to true. The **clock-gmt** parameter makes the component not apply the local timezone to the printed times. - **--clock-seconds** Set the **clock-seconds** initialization parameter of the component to true. The **clock-seconds** parameter makes the component print the event times in seconds since the Unix epoch. - **--color**=*WHEN* Set the **color** initialization parameter of the component to *WHEN*. The available values for *WHEN* are: **auto** Only emit terminal color codes when the standard output and error streams are connected to a color-capable terminal. **never** Never emit terminal color codes. **always** Always emit terminal color codes. The **auto** and **always** values have no effect if the **BABELTRACE\_TERM\_COLOR** environment variable is set to **NEVER**. - **--fields**=*FIELD*\[,*FIELD*\]... For each *FIELD*, set the **field-FIELD** initialization parameter of the component to true. For example, **--fields**=**trace,loglevel,emf** sets the **field-trace**, **field-loglevel**, and **field-emf** initialization parameters to true. The available value for *FIELD* are: • **trace** • **trace:hostname** • **trace:domain** • **trace:procname** • **trace:vpid** • **loglevel** • **emf** • **callsite** - **--names**=*NAME*\[,*NAME*\]... For each *NAME*, set the **name-NAME** initialization parameter of the component to true. For example, **--names**=**payload,scope** sets the **name-payload** and **name-scope** initialization parameters to true. The available value for *NAME* are: • **payload** • **context** • **scope** • **header** - **--no-delta** Set the **no-delta** initialization parameter of the component to true. When the **no-delta** parameter is true, the component doesn’t print the duration since the last event on the line. ### Shared options - **-w** *PATH*, **--output**=*PATH* With **--output-format**=**ctf-metadata** or **--input-format**=**lttng-live** (when printing the available remote LTTng tracing sessions), write the text to the file *PATH* instead of the standard output. When you specify **--output-format**=**ctf**, set the **path** initialization parameter of the implicit **sink.ctf.fs** component to *PATH*. Without any specified sink component, explicit or implicit, force the sink component of the **convert** command to be an implicit **sink.text.pretty** component and set its **path** initialization parameter to *PATH*. See [**babeltrace2-sink.ctf.fs**(7)](/babeltrace2-sink.ctf.fs/7.md) and [**babeltrace2-sink.text.pretty**(7)](/babeltrace2-sink.text.pretty/7.md) to learn more about those component classes. ### Equivalent babeltrace2 run arguments - **--run-args** Print the equivalent [**babeltrace2-run**(1)](/babeltrace2-run/1.md) arguments instead of creating and running the conversion graph. The printed arguments are space-separated and individually escaped for safe shell input. You cannot use this option with the **--run-args-0** or **--stream-intersection** option. - **--run-args-0** Print the equivalent [**babeltrace2-run**(1)](/babeltrace2-run/1.md) arguments instead of creating and running the conversion graph. The printed arguments are separated with a null character and NOT escaped for safe shell input. You cannot use this option with the **--run-args** or **--stream-intersection** option. ### Conversion graph configuration - **-m** *VERSION*, **--allowed-mip-versions**=*VERSION* Only allow the conversion graph to honour version *VERSION* (0 or 1) of the Message Interchange Protocol (MIP) instead of allowing both versions. - **--retry-duration**=*TIME-US* Set the duration of a single retry to *TIME-US* s when a sink component reports "try again later" (busy network or file system, for example). Default: 100000 (100 ms). - **--stream-intersection** Enable the stream intersection mode. In this mode, for each trace, the **convert** command filters out the events and other messages which aren’t in the time range where *all* the trace streams are active. To use this option, all the source components, explicit and implicit, must have classes which support the **babeltrace.trace-infos** query object (see [**babeltrace2-query-babeltrace.trace-infos**(7)](/babeltrace2-query-babeltrace.trace-infos/7.md)). The only component class of the Babeltrace 2 project which supports this query object is **source.ctf.fs**. You cannot use this option with the **--run-args** or **--run-args-0** option. ### Other legacy options The following options exist for backward compatibility with the [**babeltrace**(1)](/babeltrace/1.md) program. - **-d**, **--debug** Legacy option: this is equivalent to **--log-level**=**TRACE**, where **--log-level** is the general option (not the **--log-level** option of this command). - **-v**, **--verbose** Legacy option: this is equivalent to **--log-level**=**INFO**, where **--log-level** is the general option (not the **--log-level** option of this command). This option also sets the **verbose** parameter of the implicit **sink.text.pretty** component (see [**babeltrace2-sink.text.pretty**(7)](/babeltrace2-sink.text.pretty/7.md)) to true. ### Command information - **-h**, **--help** Show the command help and quit. ## EXAMPLES **Example 1. Pretty-print the events, in order, of one or more CTF traces.** ``` $ babeltrace2 my-ctf-traces ``` ``` $ babeltrace2 my-ctf-traces ``` ``` $ babeltrace2 my-ctf-trace-1 my-ctf-trace-2 my-ctf-trace-3 ``` **Example 2. Trim a CTF trace and pretty-print the events.** ``` $ babeltrace2 my-ctf-trace --begin=22:55:43.658582931 \ --end=22:55:46.967687564 ``` ``` $ babeltrace2 my-trace --begin=22:55:43.658582931 ``` ``` $ babeltrace2 my-trace --end=22:55:46.967687564 ``` ``` $ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564 ``` **Example 3. Trim a CTF trace, enable the stream intersection mode, and write a CTF trace.** ``` $ babeltrace2 my-ctf-trace --stream-intersection \ --timerange=22:55:43,22:55:46.967687564 \ --output-format=ctf --output=out-ctf-trace ``` **Example 4. Print the available remote LTTng sessions (through LTTng live).** ``` $ babeltrace2 --input-format=lttng-live net://localhost ``` **Example 5. Pretty-print LTTng live events.** ``` $ babeltrace2 net://localhost/host/myhostname/my-session-name ``` **Example 6. Record LTTng live traces to the file system (as CTF 1.8 traces).** ``` $ babeltrace2 net://localhost/host/myhostname/my-session-name \ --params=session-not-found-action=end \ --component=sink.ctf.fs \ --params='path="out-ctf-traces",ctf-version="1"' ``` **Example 7. Read a CTF trace as fast as possible using a dummy output.** ``` $ babeltrace2 my-trace --output-format=dummy ``` **Example 8. Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file.** ``` $ babeltrace2 ctf-trace1 ctf-trace2 ctf-trace3 --stream-intersection \ --debug-info --output=pretty-out ``` **Example 9. Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since the Unix epoch.** ``` $ babeltrace2 ctf-trace --component=src.my-plugin.my-src \ --params='path="spec-trace",output-some-event-type=yes' \ --clock-seconds ``` **Example 10. Send LTTng live events to an explicit sink component.** ``` $ babeltrace2 net://localhost/host/myhostname/mysession \ --component=sink.my-plugin.my-sink ``` **Example 11. Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace.** ``` $ babeltrace2 /path/to/ctf/trace --timerange=22:14:38,22:15:07 \ --debug-info --component=filter.my-plugin.my-filter \ --params=criteria=xyz,ignore-abc=yes \ --output-format=ctf --output=out-ctf-trace ``` **Example 12. Print the metadata text of a CTF trace.** ``` $ babeltrace2 /path/to/ctf/trace --output-format=ctf-metadata ``` ## ENVIRONMENT VARIABLES ### Babeltrace 2 library **BABELTRACE\_EXEC\_ON\_ABORT**=*CMDLINE* Execute the command line *CMDLINE*, as parsed like a UNIX 98 shell, when any part of the Babeltrace 2 project unexpectedly aborts. The application only aborts when the executed command returns, ignoring its exit status. This environment variable is ignored when the application has the **setuid** or the **setgid** access right flag set. **BABELTRACE\_TERM\_COLOR**=(**AUTO** \| **NEVER** \| **ALWAYS**) Force the terminal color support for the [**babeltrace2**(1)](/babeltrace2/1.md) program and the project plugins. The available values are: **AUTO** Only emit terminal color codes when the standard output and error streams are connected to a color-capable terminal. **NEVER** Never emit terminal color codes. **ALWAYS** Always emit terminal color codes. **BABELTRACE\_TERM\_COLOR\_BRIGHT\_MEANS\_BOLD**=**0** Set to **0** to emit SGR (see \) codes 90 to 97 for bright colors instead of bold (SGR code 1) and standard color codes (SGR codes 30 to 37). **BABELTRACE\_PLUGIN\_PATH**=*PATHS* Set the list of directories, in order, in which dynamic plugins can be found before other directories are considered to *PATHS* (colon-separated, or semicolon on Windows). **LIBBABELTRACE2\_DISABLE\_PYTHON\_PLUGINS**=**1** Disable the loading of any Babeltrace 2 Python plugin. **LIBBABELTRACE2\_INIT\_LOG\_LEVEL**=*LVL* Force the initial log level of the Babeltrace 2 library to be *LVL*. If this environment variable is set, then it overrides the log level set by the **--log-level** option for the Babeltrace 2 library logger. The available values for *LVL* are: **NONE**, **N** Logging is disabled. **FATAL**, **F** Severe errors that lead the execution to abort immediately. This level should be enabled in production. **ERROR**, **E** Errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won’t perform any more useful task, but it should still exit cleanly. This level should be enabled in production. **WARN**, **WARNING**, **W** Unexpected situations which still allow the execution to continue. This level should be enabled in production. **INFO**, **I** Informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production. **DEBUG**, **D** Debugging information, with a higher level of details than the **TRACE** level. This level should NOT be enabled in production. **TRACE**, **T** Low-level debugging context information. This level should NOT be enabled in production. **LIBBABELTRACE2\_NO\_DLCLOSE**=**1** Make the Babeltrace 2 library leave any dynamically loaded modules (plugins and plugin providers) open at exit. This can be useful for debugging purposes. **LIBBABELTRACE2\_PLUGIN\_PROVIDER\_DIR**=*DIR* Set the directory from which the Babeltrace 2 library dynamically loads plugin provider shared objects to *DIR*. If this environment variable is set, then it overrides the default plugin provider directory. ### Babeltrace 2 Python bindings **BABELTRACE\_PYTHON\_BT2\_LOG\_LEVEL**=*LVL* Force the Babeltrace 2 Python bindings log level to be *LVL*. If this environment variable is set, then it overrides the log level set by the **--log-level** option for the Python bindings logger. The available values for *LVL* are: **NONE**, **N** Logging is disabled. **FATAL**, **F** Severe errors that lead the execution to abort immediately. This level should be enabled in production. **ERROR**, **E** Errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won’t perform any more useful task, but it should still exit cleanly. This level should be enabled in production. **WARN**, **WARNING**, **W** Unexpected situations which still allow the execution to continue. This level should be enabled in production. **INFO**, **I** Informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production. **DEBUG**, **D** Debugging information, with a higher level of details than the **TRACE** level. This level should NOT be enabled in production. **TRACE**, **T** Low-level debugging context information. This level should NOT be enabled in production. ### CLI **BABELTRACE\_CLI\_LOG\_LEVEL**=*LVL* Force the log level of the log level **babeltrace2** CLI to be *LVL*. If this environment variable is set, then it overrides the log level set by the **--log-level** option for the CLI logger. The available values for *LVL* are: **NONE**, **N** Logging is disabled. **FATAL**, **F** Severe errors that lead the execution to abort immediately. This level should be enabled in production. **ERROR**, **E** Errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won’t perform any more useful task, but it should still exit cleanly. This level should be enabled in production. **WARN**, **WARNING**, **W** Unexpected situations which still allow the execution to continue. This level should be enabled in production. **INFO**, **I** Informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production. **DEBUG**, **D** Debugging information, with a higher level of details than the **TRACE** level. This level should NOT be enabled in production. **TRACE**, **T** Low-level debugging context information. This level should NOT be enabled in production. **BABELTRACE\_CLI\_WARN\_COMMAND\_NAME\_DIRECTORY\_CLASH**=**0** Disable the warning message which [**babeltrace2-convert**(1)](/babeltrace2-convert/1.md) prints when you convert a trace with a relative path that’s also the name of a **babeltrace2** command. **BABELTRACE\_DEBUG**=**1** Legacy variable: equivalent to setting the **--log-level** option to **TRACE**. **BABELTRACE\_VERBOSE**=**1** Legacy variable: equivalent to setting the **--log-level** option to **INFO**. ## FILES **$HOME/.local/lib/babeltrace2/plugins** User plugin directory. **/usr/lib/babeltrace2/plugins** System plugin directory. **/usr/lib/babeltrace2/plugin-providers** System plugin provider directory. ## EXIT STATUS **0** on success, **1** otherwise. ## BUGS If you encounter any issue or usability problem, please report it on the Babeltrace bug tracker (see \). ## RESOURCES The Babeltrace project shares some communication channels with the LTTng project (see \). • Babeltrace website (see \) • Mailing list (see \) for support and development: **lttng-dev@lists.lttng.org** • IRC channel (see \): **#lttng** on **irc.oftc.net** • Bug tracker (see \) • Git repository (see \) • GitHub project (see \) • Continuous integration (see \) • Code review (see \) ## AUTHORS The Babeltrace 2 project is the result of hard work by many regular developers and occasional contributors. The current project maintainer is Jérémie Galarneau \. ## COPYRIGHT This command is part of the Babeltrace 2 project. Babeltrace is distributed under the MIT license (see \). ## SEE ALSO [**babeltrace2-intro**(7)](/babeltrace2-intro/7.md), [**babeltrace2**(1)](/babeltrace2/1.md), [**babeltrace2-run**(1)](/babeltrace2-run/1.md)