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