Commit | Line | Data |
---|---|---|
e70712b3 | 1 | = babeltrace2-convert(1) |
0659f3af | 2 | :manpagetype: command |
e70712b3 | 3 | :revdate: 14 September 2019 |
0659f3af PP |
4 | |
5 | ||
e70712b3 PP |
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'... | |
0659f3af | 18 | |
e70712b3 | 19 | Convert one or more traces to a given format: |
0659f3af | 20 | |
e70712b3 PP |
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: | |
0659f3af PP |
27 | |
28 | [verse] | |
e70712b3 PP |
29 | *babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--retry-duration='TIME-US'] |
30 | (opt:--run-args | opt:--run-args-0) 'CONVERSION ARGS' | |
0659f3af PP |
31 | |
32 | Print the metadata text of a CTF trace: | |
33 | ||
34 | [verse] | |
e70712b3 PP |
35 | *babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--output='OUTPATH'] |
36 | opt:--output-format=`ctf-metadata` 'TRACE-PATH' | |
0659f3af | 37 | |
e70712b3 PP |
38 | Print the available https://lttng.org/docs/#doc-lttng-live[remote LTTng |
39 | tracing sessions]: | |
0659f3af PP |
40 | |
41 | [verse] | |
e70712b3 PP |
42 | *babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--output='OUTPATH'] |
43 | opt:--input-format=`lttng-live` 'URL' | |
0659f3af PP |
44 | |
45 | ||
e70712b3 | 46 | == DESCRIPTION |
0659f3af | 47 | |
e70712b3 PP |
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[] | |
0659f3af PP |
52 | |
53 | [NOTE] | |
54 | ==== | |
e70712b3 PP |
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`: | |
0659f3af PP |
59 | |
60 | [role="term"] | |
61 | ---- | |
a8be4294 MJ |
62 | $ babeltrace2 convert ... |
63 | $ babeltrace2 ... | |
0659f3af PP |
64 | ---- |
65 | ||
66 | If you need to make sure that you are executing the `convert` command, | |
a8be4294 | 67 | use `babeltrace2 convert` explicitly. |
0659f3af PP |
68 | ==== |
69 | ||
e70712b3 PP |
70 | More specifically, the `convert` command creates a conversion graph. |
71 | ||
0659f3af PP |
72 | A conversion graph is a specialized trace processing graph focused on |
73 | the conversion of one or more traces to another format, possibly | |
e70712b3 PP |
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: | |
0659f3af PP |
77 | |
78 | ---- | |
79 | +----------+ | |
e70712b3 | 80 | | source 1 @-. |
0659f3af PP |
81 | +----------+ | |
82 | | +-------+ | |
e70712b3 PP |
83 | +----------+ '->@ | +---------+ +------------+ |
84 | | source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-. | |
85 | +----------+ .->@ | +---------+ +------------+ | | |
0659f3af PP |
86 | | +-------+ | |
87 | +----------+ | .----------------------------------------' | |
e70712b3 PP |
88 | | ... @-' | +---------------+ +------+ |
89 | +----------+ '->@ other filters |--->@ sink | | |
0659f3af PP |
90 | +---------------+ +------+ |
91 | ---- | |
92 | ||
93 | Note that the trimmer, debugging information, and other filters are | |
e70712b3 PP |
94 | optional. See <<comp-create-impl-opt,``Create implicit components from |
95 | options''>> to learn how to enable them. | |
0659f3af | 96 | |
e70712b3 | 97 | If you need another trace processing graph layout, use the more flexible |
a8be4294 | 98 | man:babeltrace2-run(1) command. |
0659f3af | 99 | |
a8be4294 | 100 | Like with the man:babeltrace2-run(1) command, you can create components |
0659f3af | 101 | explicitly with the opt:--component option (see |
e70712b3 PP |
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: | |
0659f3af PP |
118 | |
119 | [role="term"] | |
120 | ---- | |
e70712b3 | 121 | $ babeltrace2 /path/to/trace /path/to/other/trace |
0659f3af PP |
122 | ---- |
123 | ||
124 | This is the equivalent of creating and connecting together: | |
125 | ||
e70712b3 PP |
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`. | |
0659f3af PP |
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 | ---- | |
e70712b3 PP |
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 | +-----------------+ | |
0659f3af PP |
159 | ---- |
160 | ||
e70712b3 | 161 | It is equivalent to the following man:babeltrace2-run(1) command line: |
0659f3af PP |
162 | |
163 | [role="term"] | |
164 | ---- | |
a8be4294 | 165 | $ babeltrace2 run --component=ctf-fs:src.ctf.fs \ |
e70712b3 PP |
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 | |
0659f3af PP |
172 | ---- |
173 | ||
174 | You can use the opt:--run-args option to make the `convert` command | |
e70712b3 PP |
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: | |
0659f3af PP |
179 | |
180 | [role="term"] | |
181 | ---- | |
a8be4294 | 182 | $ babeltrace2 run $(babeltrace2 --run-args /path/to/trace) ... |
0659f3af PP |
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 | ||
e70712b3 | 191 | See <<examples,``EXAMPLES''>> for usage examples. |
0659f3af PP |
192 | |
193 | ||
194 | [[comp-create-expl]] | |
e70712b3 PP |
195 | === Create explicit components |
196 | ||
0659f3af PP |
197 | To explicitly create a component, use the opt:--component option. This |
198 | option specifies: | |
199 | ||
e70712b3 | 200 | * **Optional**: The name of the component. |
0659f3af PP |
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 | |
e70712b3 | 216 | opt:--component option or non-option argument). |
0659f3af | 217 | |
e70712b3 | 218 | The following command-line options apply to the current component: |
0659f3af | 219 | |
e70712b3 PP |
220 | opt:--log-level='LVL':: |
221 | Set the log level of the current component to 'LVL'. | |
0659f3af PP |
222 | |
223 | opt:--params='PARAMS':: | |
224 | Add 'PARAMS' to the initialization parameters of the current | |
e70712b3 | 225 | component. |
0659f3af | 226 | + |
e70712b3 PP |
227 | If 'PARAMS' contains a key which exists in the current component's |
228 | initialization parameters, replace the parameter. | |
0659f3af | 229 | |
e70712b3 | 230 | See <<examples,``EXAMPLES''>> for usage examples. |
0659f3af PP |
231 | |
232 | ||
e70712b3 PP |
233 | [[comp-create-impl-non-opt]] |
234 | === Create implicit components from non-option arguments | |
0659f3af | 235 | |
e70712b3 PP |
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: | |
0659f3af | 240 | |
0659f3af PP |
241 | [role="term"] |
242 | ---- | |
e70712b3 | 243 | $ babeltrace2 /path/to/trace |
0659f3af | 244 | ---- |
e70712b3 PP |
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. | |
0659f3af | 268 | + |
e70712b3 PP |
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 | ||
0659f3af PP |
275 | [role="term"] |
276 | ---- | |
e70712b3 | 277 | $ babeltrace2 /path/to/chunk1 /path/to/chunk2 |
0659f3af | 278 | ---- |
0659f3af | 279 | |
e70712b3 PP |
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 | ||
0659f3af PP |
287 | [role="term"] |
288 | ---- | |
e70712b3 PP |
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 | |
0659f3af | 292 | ---- |
0659f3af | 293 | |
e70712b3 PP |
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 | |
0659f3af PP |
311 | trimmer), specify the opt:--begin, opt:--end, or opt:--timerange |
312 | option. | |
313 | + | |
314 | Examples: | |
315 | + | |
316 | [role="term"] | |
317 | ---- | |
a8be4294 | 318 | $ babeltrace2 /path/to/trace --begin=22:14:38 --end=22:15:07 |
0659f3af PP |
319 | ---- |
320 | + | |
321 | [role="term"] | |
322 | ---- | |
a8be4294 | 323 | $ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07 |
0659f3af PP |
324 | ---- |
325 | + | |
326 | [role="term"] | |
327 | ---- | |
a8be4294 | 328 | $ babeltrace2 /path/to/trace --end=12:31:04.882928015 |
0659f3af PP |
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 | ---- | |
e70712b3 | 340 | $ babeltrace2 /path/to/trace --debug-info |
0659f3af PP |
341 | ---- |
342 | + | |
343 | [role="term"] | |
344 | ---- | |
a8be4294 | 345 | $ babeltrace2 /path/to/trace \ |
e70712b3 | 346 | --debug-info-target-prefix=/tmp/tgt-root |
0659f3af PP |
347 | ---- |
348 | + | |
349 | [role="term"] | |
350 | ---- | |
a8be4294 | 351 | $ babeltrace2 /path/to/trace --debug-info-full-path |
0659f3af PP |
352 | ---- |
353 | ||
354 | * To create an implicit compcls:sink.text.pretty component | |
e70712b3 PP |
355 | (pretty-printing text output to the standard output or to a file), |
356 | specify no other sink components, explicit or implicit. | |
0659f3af | 357 | + |
e70712b3 PP |
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. | |
0659f3af PP |
372 | + |
373 | Examples: | |
374 | + | |
375 | [role="term"] | |
376 | ---- | |
a8be4294 | 377 | $ babeltrace2 /path/to/trace |
0659f3af PP |
378 | ---- |
379 | + | |
380 | [role="term"] | |
381 | ---- | |
a8be4294 | 382 | $ babeltrace2 /path/to/trace --no-delta |
0659f3af PP |
383 | ---- |
384 | + | |
385 | [role="term"] | |
386 | ---- | |
a8be4294 | 387 | $ babeltrace2 /path/to/trace --output=/tmp/pretty-out |
0659f3af PP |
388 | ---- |
389 | ||
e70712b3 PP |
390 | * To create an implicit compcls:sink.utils.dummy component (no output), |
391 | specify the opt:--output-format=`dummy` option. | |
0659f3af PP |
392 | + |
393 | Example: | |
394 | + | |
395 | [role="term"] | |
396 | ---- | |
a8be4294 | 397 | $ babeltrace2 /path/to/trace --output-format=dummy |
0659f3af PP |
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` | |
e70712b3 | 402 | and the opt:--output='DIR' (base output directory) options. |
0659f3af PP |
403 | + |
404 | Example: | |
405 | + | |
406 | [role="term"] | |
407 | ---- | |
a8be4294 | 408 | $ babeltrace2 /path/to/input/trace --output-format=ctf \ |
e70712b3 | 409 | --output=my-traces |
0659f3af PP |
410 | ---- |
411 | ||
e70712b3 PP |
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: | |
0659f3af PP |
415 | |
416 | [role="term"] | |
417 | ---- | |
a8be4294 | 418 | $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \ |
e70712b3 | 419 | --debug-info --output-format=ctf --output=out-dir |
0659f3af PP |
420 | ---- |
421 | ||
a8be4294 | 422 | The equivalent man:babeltrace2-run(1) command of this `convert` command |
0659f3af PP |
423 | is: |
424 | ||
425 | [role="term"] | |
426 | ---- | |
e70712b3 PP |
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 | |
0659f3af PP |
440 | ---- |
441 | ||
e70712b3 PP |
442 | The order of the implicit component options documented in this |
443 | subsection is not significant. | |
0659f3af | 444 | |
e70712b3 | 445 | See <<examples,``EXAMPLES''>> for more examples. |
0659f3af | 446 | |
0659f3af | 447 | |
e70712b3 | 448 | == OPTIONS |
0659f3af | 449 | |
0659f3af PP |
450 | include::common-gen-options.txt[] |
451 | ||
452 | ||
e70712b3 PP |
453 | === Explicit component creation |
454 | ||
455 | See <<comp-create-expl,``Create explicit components''>> to learn how to | |
456 | use the following option. | |
0659f3af | 457 | |
e70712b3 PP |
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. | |
0659f3af | 463 | + |
e70712b3 | 464 | The available values for 'COMP-CLS-TYPE' are: |
0659f3af PP |
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 | ||
0659f3af | 479 | |
e70712b3 PP |
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':: | |
0659f3af | 502 | Add 'PARAMS' to the initialization parameters of the current |
e70712b3 PP |
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 | -- | |
0659f3af | 511 | |
0659f3af | 512 | |
e70712b3 PP |
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: | |
0659f3af PP |
524 | + |
525 | -- | |
526 | `ctf`:: | |
e70712b3 PP |
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. | |
0659f3af | 531 | + |
a8be4294 | 532 | See man:babeltrace2-source.ctf.fs(7) to learn more about this |
0659f3af PP |
533 | component class. |
534 | ||
535 | `lttng-live`:: | |
e70712b3 | 536 | Depending on the format of the first non-option argument: |
0659f3af PP |
537 | + |
538 | -- | |
e70712b3 PP |
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. | |
0659f3af PP |
543 | |
544 | `net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`:: | |
e70712b3 | 545 | Use the compcls:source.ctf.lttng-live component class. |
0659f3af | 546 | + |
e70712b3 PP |
547 | See man:babeltrace2-source.ctf.lttng-live(7) to learn more about this |
548 | component class and the URL format. | |
0659f3af PP |
549 | -- |
550 | -- | |
551 | + | |
552 | You can specify at most one opt:--input-format option. | |
553 | ||
554 | opt:-o 'FORMAT', opt:--output-format='FORMAT':: | |
e70712b3 PP |
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: | |
0659f3af PP |
559 | + |
560 | -- | |
561 | `text`:: | |
562 | Create an implicit compcls:sink.text.pretty component. | |
0659f3af | 563 | + |
e70712b3 PP |
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. | |
0659f3af PP |
568 | |
569 | `ctf`:: | |
e70712b3 PP |
570 | Create an implicit compcls:sink.ctf.fs component. Specify the base |
571 | output path with the opt:--output option. | |
0659f3af | 572 | + |
e70712b3 PP |
573 | See man:babeltrace2-sink.ctf.fs(7) to learn more about this component |
574 | class. | |
0659f3af PP |
575 | |
576 | `dummy`:: | |
577 | Create an implicit compcls:sink.utils.dummy component. | |
578 | + | |
e70712b3 PP |
579 | See man:babeltrace2-sink.utils.dummy(7) to learn more about this |
580 | component class. | |
0659f3af PP |
581 | |
582 | `ctf-metadata`:: | |
e70712b3 PP |
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. | |
0659f3af PP |
586 | -- |
587 | + | |
588 | You can specify at most one opt:--output-format option. | |
589 | ||
590 | ||
591 | [[impl-opts-ctf]] | |
e70712b3 | 592 | === Implicit compcls:source.ctf.fs component(s) |
0659f3af | 593 | |
e70712b3 PP |
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. | |
0659f3af PP |
606 | |
607 | opt:--clock-offset='SEC':: | |
608 | Set the manparam:source.ctf.fs:clock-class-offset-s initialization | |
e70712b3 | 609 | parameter of all the implicit compcls:source.ctf.fs components to |
0659f3af PP |
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 | |
e70712b3 | 620 | parameter of all the implicit compcls:source.ctf.fs components to |
0659f3af PP |
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 | ||
e70712b3 PP |
630 | === Implicit compcls:filter.utils.trimmer component |
631 | ||
0659f3af PP |
632 | If you specify at least one of the following options, you create an |
633 | implicit compcls:filter.utils.trimmer component. | |
634 | ||
a8be4294 | 635 | See man:babeltrace2-filter.utils.trimmer(7) to learn more about |
0659f3af PP |
636 | this component class. |
637 | ||
e70712b3 | 638 | opt:--begin='TIME':: |
0659f3af | 639 | Set the manparam:filter.utils.trimmer:begin initialization parameter |
e70712b3 PP |
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 | -- | |
0659f3af | 649 | |
e70712b3 | 650 | opt:--end='TIME':: |
0659f3af | 651 | Set the manparam:filter.utils.trimmer:end initialization parameter |
e70712b3 PP |
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'. | |
0659f3af PP |
657 | |
658 | opt:--timerange='BEGIN','END':: | |
e70712b3 | 659 | Equivalent to opt:--begin='BEGIN' and opt:--end='END'. |
0659f3af PP |
660 | + |
661 | You can also surround the whole argument with `[` and `]`. | |
662 | ||
663 | ||
e70712b3 PP |
664 | === Implicit compcls:filter.lttng-utils.debug-info component |
665 | ||
0659f3af PP |
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 | ||
e70712b3 PP |
670 | See man:babeltrace2-filter.lttng-utils.debug-info(7) to learn more about |
671 | this component class. | |
0659f3af PP |
672 | |
673 | opt:--debug-info:: | |
674 | Create an implicit compcls:filter.lttng-utils.debug-info component. | |
e70712b3 PP |
675 | + |
676 | This option is useless if you specify any of the options below. | |
0659f3af PP |
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 | ||
e70712b3 PP |
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. | |
0659f3af | 713 | |
a8be4294 | 714 | See man:babeltrace2-sink.text.pretty(7) to learn more about this |
0659f3af PP |
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 | |
e70712b3 | 743 | component print the event times in seconds since the Unix epoch. |
0659f3af PP |
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`:: | |
e70712b3 PP |
753 | Only emit terminal color codes when the standard output and error |
754 | streams are connected to a color-capable terminal. | |
0659f3af PP |
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 | ||
e70712b3 PP |
809 | === Shared options |
810 | ||
811 | opt:-w 'PATH':: | |
812 | opt:--output='PATH':: | |
c327e427 | 813 | With opt:--output-format=`ctf-metadata` or |
e70712b3 PP |
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. | |
c327e427 PP |
817 | + |
818 | When you specify opt:--output-format=`ctf`, set the | |
819 | manparam:sink.ctf.fs:path initialization parameter of the implicit | |
e70712b3 PP |
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 | |
c327e427 PP |
824 | compcls:sink.text.pretty component and set its |
825 | manparam:sink.text.pretty:path initialization parameter to 'PATH'. | |
0659f3af | 826 | + |
a8be4294 | 827 | See man:babeltrace2-sink.ctf.fs(7) and |
e70712b3 PP |
828 | man:babeltrace2-sink.text.pretty(7) to learn more about those component |
829 | classes. | |
830 | ||
0659f3af | 831 | |
e70712b3 | 832 | === Equivalent `babeltrace2 run` arguments |
0659f3af | 833 | |
0659f3af | 834 | opt:--run-args:: |
a8be4294 | 835 | Print the equivalent man:babeltrace2-run(1) arguments instead of |
e70712b3 PP |
836 | creating and running the conversion graph. |
837 | + | |
838 | The printed arguments are space-separated and individually escaped for | |
839 | safe shell input. | |
0659f3af PP |
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:: | |
a8be4294 | 845 | Print the equivalent man:babeltrace2-run(1) arguments instead of |
e70712b3 PP |
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. | |
0659f3af PP |
850 | + |
851 | You cannot use this option with the opt:--run-args or | |
852 | opt:--stream-intersection option. | |
853 | ||
854 | ||
e70712b3 PP |
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 | |
0659f3af PP |
859 | component reports "try again later" (busy network or file system, |
860 | for example). | |
861 | + | |
e70712b3 | 862 | Default: 100000 (100~ms). |
0659f3af PP |
863 | |
864 | opt:--stream-intersection:: | |
e70712b3 | 865 | Enable the stream intersection mode. |
0659f3af | 866 | + |
e70712b3 PP |
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. | |
0659f3af | 870 | + |
e70712b3 PP |
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. | |
0659f3af | 879 | |
e70712b3 | 880 | === Other legacy options |
0659f3af | 881 | |
e70712b3 PP |
882 | The following options exist for backward compatibility with the |
883 | man:babeltrace(1) program. | |
0659f3af | 884 | |
e70712b3 PP |
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). | |
0659f3af | 890 | |
e70712b3 PP |
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. | |
0659f3af | 900 | |
e70712b3 | 901 | include::common-cmd-info-options.txt[] |
0659f3af PP |
902 | |
903 | ||
904 | [[examples]] | |
e70712b3 | 905 | == EXAMPLES |
0659f3af | 906 | |
e70712b3 | 907 | include::common-convert-examples.txt[] |
0659f3af PP |
908 | |
909 | ||
910 | include::common-cli-env.txt[] | |
911 | ||
e70712b3 | 912 | |
0659f3af PP |
913 | include::common-cli-files.txt[] |
914 | ||
e70712b3 | 915 | |
0659f3af PP |
916 | include::common-cmd-footer.txt[] |
917 | ||
918 | ||
e70712b3 PP |
919 | == SEE ALSO |
920 | ||
921 | man:babeltrace2-intro(7), | |
a8be4294 | 922 | man:babeltrace2(1), |
e70712b3 | 923 | man:babeltrace2-run(1) |