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