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