| 1 | = babeltrace2(1) |
| 2 | :manpagetype: program |
| 3 | :revdate: 14 September 2019 |
| 4 | |
| 5 | |
| 6 | == NAME |
| 7 | |
| 8 | babeltrace2 - Convert or process one or more traces, and more |
| 9 | |
| 10 | |
| 11 | == SYNOPSIS |
| 12 | |
| 13 | [verse] |
| 14 | *babeltrace2* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] |
| 15 | [opt:--omit-home-plugin-path] [opt:--omit-system-plugin-path] |
| 16 | [opt:--plugin-path='PATH'[:__PATH__]...] ['<<commands,CMD>>'] ['CMD ARGS'] |
| 17 | |
| 18 | |
| 19 | == DESCRIPTION |
| 20 | |
| 21 | `babeltrace2` is an open-source trace converter and processor |
| 22 | command-line program. The tool can open one or more traces and convert |
| 23 | between multiple formats, possibly with one or more filters in the |
| 24 | conversion path, and perform other operations depending on the |
| 25 | command 'CMD' (see <<commands,``COMMANDS''>>). |
| 26 | |
| 27 | [NOTE] |
| 28 | -- |
| 29 | You might be looking for the man:babeltrace2-convert(1) command's |
| 30 | manual page; the `convert` command is the default command of |
| 31 | `babeltrace2` and is backward compatible with man:babeltrace(1). |
| 32 | |
| 33 | See <<examples,``EXAMPLES''>> for `convert` command examples. |
| 34 | -- |
| 35 | |
| 36 | include::common-see-babeltrace2-intro.txt[] |
| 37 | |
| 38 | Most of the `babeltrace2` commands load Babeltrace~2 plugins to |
| 39 | perform their operation. The search path for Babeltrace~2 plugins |
| 40 | is, in this order: |
| 41 | |
| 42 | . The colon-separated (or semicolon, on Windows) list of directories in |
| 43 | the `BABELTRACE_PLUGIN_PATH` environment variable. |
| 44 | |
| 45 | . The colon-separated (or semicolon, on Windows) list of directories in |
| 46 | the opt:--plugin-path option. |
| 47 | |
| 48 | . `$HOME/.local/lib/babeltrace2/plugins` |
| 49 | |
| 50 | . +{system_plugin_path}+ |
| 51 | |
| 52 | You can use the man:babeltrace2-list-plugins(1) command to dynamically |
| 53 | list the available plugins and what they offer. See |
| 54 | <<plugins,``PROJECT'S PLUGINS''>> for a list of plugins shipped with |
| 55 | Babeltrace~2. |
| 56 | |
| 57 | |
| 58 | == OPTIONS |
| 59 | |
| 60 | opt:-d:: |
| 61 | opt:--debug:: |
| 62 | Legacy option: this is equivalent to opt:--log-level=`TRACE`. |
| 63 | |
| 64 | opt:-l 'LVL':: |
| 65 | opt:--log-level='LVL':: |
| 66 | Set the log level of all known Babeltrace~2 loggers to 'LVL', |
| 67 | including individual components for the man:babeltrace2-convert(1) |
| 68 | and man:babeltrace2-run(1) commands. |
| 69 | + |
| 70 | You can override the log level of a specific component with the |
| 71 | nlopt:--log-level option of the man:babeltrace2-convert(1) or |
| 72 | man:babeltrace2-run(1) commands. |
| 73 | + |
| 74 | You can override the log level of the library with the |
| 75 | `LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable. |
| 76 | + |
| 77 | You can override the log level of the CLI with the |
| 78 | `BABELTRACE_CLI_LOG_LEVEL` environment variable. |
| 79 | + |
| 80 | You can override the log level of the Babeltrace~2 Python bindings |
| 81 | with the `BABELTRACE_PYTHON_BT2_LOG_LEVEL` environment variable. |
| 82 | + |
| 83 | The available values for 'LVL' are: |
| 84 | + |
| 85 | -- |
| 86 | include::common-log-levels.txt[] |
| 87 | -- |
| 88 | |
| 89 | opt:--omit-home-plugin-path:: |
| 90 | Do not search for plugins in `$HOME/.local/lib/babeltrace2/plugins`. |
| 91 | |
| 92 | opt:--omit-system-plugin-path:: |
| 93 | Do not search for plugins in +{system_plugin_path}+. |
| 94 | |
| 95 | opt:--plugin-path='PATH'[:__PATH__]...:: |
| 96 | Add 'PATH' to the list of paths in which plugins can be found. |
| 97 | |
| 98 | opt:-v:: |
| 99 | opt:--verbose:: |
| 100 | Legacy option: this is equivalent to opt:--log-level=`INFO`. |
| 101 | + |
| 102 | If 'CMD' is `convert` or is missing, then this also sets the |
| 103 | manparam:sink.text.pretty:verbose parameter of the implicit |
| 104 | compcls:sink.text.pretty component (see |
| 105 | man:babeltrace2-sink.text.pretty(7)) to true. |
| 106 | |
| 107 | |
| 108 | opt:-h:: |
| 109 | opt:--help:: |
| 110 | Show help and quit. |
| 111 | |
| 112 | opt:-V:: |
| 113 | opt:--version:: |
| 114 | Show version and quit. |
| 115 | |
| 116 | |
| 117 | [[commands]] |
| 118 | == COMMANDS |
| 119 | |
| 120 | The following commands also have their own nlopt:--help option. |
| 121 | |
| 122 | `convert`:: |
| 123 | Convert one or more traces to a given format, possibly with filters |
| 124 | in the conversion path. |
| 125 | + |
| 126 | This is the default command: you don't need to explicitly specify this |
| 127 | command's name to use it. |
| 128 | + |
| 129 | This command is backward compatible with the man:babeltrace(1) program. |
| 130 | + |
| 131 | See man:babeltrace2-convert(1). |
| 132 | |
| 133 | `help`:: |
| 134 | Get help for a specific plugin or plugin's component class. |
| 135 | + |
| 136 | See man:babeltrace2-help(1). |
| 137 | |
| 138 | `list-plugins`:: |
| 139 | List the available Babeltrace~2 plugins and their component |
| 140 | classes. |
| 141 | + |
| 142 | See man:babeltrace2-list-plugins(1). |
| 143 | |
| 144 | `query`:: |
| 145 | Query an object from a component class. |
| 146 | + |
| 147 | See man:babeltrace2-query(1). |
| 148 | |
| 149 | `run`:: |
| 150 | Build a trace processing graph and run it. |
| 151 | + |
| 152 | See man:babeltrace2-run(1). |
| 153 | |
| 154 | |
| 155 | [[plugins]] |
| 156 | == PROJECT'S PLUGINS |
| 157 | |
| 158 | The following plugins are provided by the Babeltrace~2 project |
| 159 | itself. |
| 160 | |
| 161 | man:babeltrace2-plugin-ctf(7):: |
| 162 | CTF trace input (from the file system and from the LTTng-live |
| 163 | protocol) and output to the file system. |
| 164 | + |
| 165 | Component classes: |
| 166 | + |
| 167 | * man:babeltrace2-source.ctf.fs(7) |
| 168 | * man:babeltrace2-source.ctf.lttng-live(7) |
| 169 | * man:babeltrace2-sink.ctf.fs(7) |
| 170 | |
| 171 | ifeval::[{enable_debug_info} == 1] |
| 172 | man:babeltrace2-plugin-lttng-utils(7):: |
| 173 | Processing graph utilities for LTTng traces. |
| 174 | + |
| 175 | Component class: |
| 176 | + |
| 177 | * man:babeltrace2-filter.lttng-utils.debug-info(7) |
| 178 | endif::[] |
| 179 | |
| 180 | man:babeltrace2-plugin-text(7):: |
| 181 | Plain text input and output. |
| 182 | + |
| 183 | Component classes: |
| 184 | + |
| 185 | * man:babeltrace2-source.text.dmesg(7) |
| 186 | * man:babeltrace2-sink.text.details(7) |
| 187 | * man:babeltrace2-sink.text.pretty(7) |
| 188 | |
| 189 | man:babeltrace2-plugin-utils(7):: |
| 190 | Processing graph utilities. |
| 191 | + |
| 192 | Component classes: |
| 193 | + |
| 194 | * man:babeltrace2-filter.utils.muxer(7) |
| 195 | * man:babeltrace2-filter.utils.trimmer(7) |
| 196 | * man:babeltrace2-sink.utils.counter(7) |
| 197 | * man:babeltrace2-sink.utils.dummy(7) |
| 198 | |
| 199 | |
| 200 | [[examples]] |
| 201 | == EXAMPLES |
| 202 | |
| 203 | The following examples are the same as the man:babeltrace2-convert(1) |
| 204 | manual page's examples because `convert` is the default `babeltrace2` |
| 205 | program's command. |
| 206 | |
| 207 | include::common-convert-examples.txt[] |
| 208 | |
| 209 | |
| 210 | include::common-cli-env.txt[] |
| 211 | |
| 212 | |
| 213 | include::common-cli-files.txt[] |
| 214 | |
| 215 | |
| 216 | include::common-cmd-footer.txt[] |
| 217 | |
| 218 | |
| 219 | == SEE ALSO |
| 220 | |
| 221 | man:babeltrace2-intro(7), |
| 222 | man:babeltrace2-convert(1), |
| 223 | man:babeltrace2-help(1), |
| 224 | man:babeltrace2-list-plugins(1), |
| 225 | man:babeltrace2-query(1), |
| 226 | man:babeltrace2-run(1) |