X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=doc%2Fman%2Fbabeltrace2-convert.1.txt;h=d20862a97a69b90b5949eeb3d50e3441f4c293a4;hb=59b3e31ded241ad159dbc618cc84a039f34f6e19;hp=ad196de0525cb5834848daba5ba1a240e6cfb54a;hpb=1a29b831f3389a6f28a571fca01eee5c750cd86b;p=babeltrace.git diff --git a/doc/man/babeltrace2-convert.1.txt b/doc/man/babeltrace2-convert.1.txt index ad196de0..d20862a9 100644 --- a/doc/man/babeltrace2-convert.1.txt +++ b/doc/man/babeltrace2-convert.1.txt @@ -1,57 +1,61 @@ -babeltrace2-convert(1) -===================== += babeltrace2-convert(1) :manpagetype: command -:revdate: 5 October 2017 +:revdate: 14 September 2019 -NAME ----- -babeltrace2-convert - Convert one or more traces +== NAME + +babeltrace2-convert - Convert one or more traces to a given format + + +== SYNOPSIS + +Pretty-print (plain text) the events, in order, of one or more traces: + +[verse] +*babeltrace2* [<>] [*convert*] [opt:--retry-duration='TIME-US'] + 'TRACE-PATH'... +Convert one or more traces to a given format: -SYNOPSIS --------- -Convert one or more traces: +[verse] +*babeltrace2* [<>] [*convert*] [opt:--retry-duration='TIME-US'] + 'CONVERSION ARGS' + +Get the equivalent man:babeltrace2-run(1) command arguments to convert +one or more traces to a given format: [verse] -*babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path] - [opt:--omit-system-plugin-path] - [opt:--plugin-path='PATH'[:__PATH__]...] - [opt:--run-args | opt:--run-args-0] [opt:--retry-duration='DURUS'] - 'CONVERSION ARGUMENTS' +*babeltrace2* [<>] [*convert*] [opt:--retry-duration='TIME-US'] + (opt:--run-args | opt:--run-args-0) 'CONVERSION ARGS' Print the metadata text of a CTF trace: [verse] -*babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path] - [opt:--omit-system-plugin-path] - [opt:--plugin-path='PATH'[:__PATH__]...] - [opt:--output='OUTPATH'] - opt:--output-format=`ctf-metadata` 'TRACE-PATH' +*babeltrace2* [<>] [*convert*] [opt:--output='OUTPATH'] + opt:--output-format=`ctf-metadata` 'TRACE-PATH' -Print the available http://lttng.org/docs/#doc-lttng-live[LTTng live] -sessions: +Print the available https://lttng.org/docs/#doc-lttng-live[remote LTTng +tracing sessions]: [verse] -*babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path] - [opt:--omit-system-plugin-path] - [opt:--plugin-path='PATH'[:__PATH__]...] - [opt:--output='OUTPATH'] opt:--input-format=`lttng-live` 'URL' +*babeltrace2* [<>] [*convert*] [opt:--output='OUTPATH'] + opt:--input-format=`lttng-live` 'URL' -DESCRIPTION ------------ -The `convert` command creates a trace conversion graph and runs it. +== DESCRIPTION -See man:babeltrace2-intro(7) to learn more about the Babeltrace -project and its core concepts. +The `convert` command converts one or more traces to a given format, +possibly with filters in the conversion path. + +include::common-see-babeltrace2-intro.txt[] [NOTE] ==== -`convert` is the default man:babeltrace2(1) command: you usually don't -need to specify its name. The following commands are equivalent -if the `...` part does not start with another man:babeltrace2(1) -command's name, like `run` or `list-plugins`: +`convert` is the default man:babeltrace2(1) command: you generally don't +need to specify its name. The following commands are equivalent if the +`...` part does not start with another man:babeltrace2(1) command's +name, like `run` or `list-plugins`: [role="term"] ---- @@ -63,52 +67,69 @@ If you need to make sure that you are executing the `convert` command, use `babeltrace2 convert` explicitly. ==== +More specifically, the `convert` command creates a conversion graph. + A conversion graph is a specialized trace processing graph focused on the conversion of one or more traces to another format, possibly -filtering their events and other notifications in the process. A -conversion graph is a linear chain of components after the source -streams are merged: +filtering or modifying their events and other messages in the process. A +conversion graph is a linear chain of components once the source streams +are merged: ---- +----------+ -| source 1 |-. +| source 1 @-. +----------+ | | +-------+ -+----------+ '->| | +---------+ +------------+ -| source 2 |--->| muxer |--->| trimmer |--->| debug-info |-. -+----------+ .->| | +---------+ +------------+ | ++----------+ '->@ | +---------+ +------------+ +| source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-. ++----------+ .->@ | +---------+ +------------+ | | +-------+ | +----------+ | .----------------------------------------' -| ... |-' | +---------------+ +------+ -+----------+ '->| other filters |--->| sink | +| ... @-' | +---------------+ +------+ ++----------+ '->@ other filters |--->@ sink | +---------------+ +------+ ---- Note that the trimmer, debugging information, and other filters are -optional. See <> to learn -how to enable them. +optional. See <> to learn how to enable them. -If you need another processing graph layout, use the more flexible +If you need another trace processing graph layout, use the more flexible man:babeltrace2-run(1) command. Like with the man:babeltrace2-run(1) command, you can create components explicitly with the opt:--component option (see -<>). You can also use one -of the many specific `convert` command options and arguments to create -implicit components from known component classes (see -<>). For example, you can -specify a single path argument to print the merged events of a CTF trace -on the console: +<>). You can also use +one of the many specific `convert` command options (see +<>) +and non-option arguments (see <>) to create implicit +components. + +An _implicit component_ is a component which is created and added to the +conversion graph without an explicit instantiation through the +opt:--component option. An implicit component is easier to create than +an explicit component: this is why the `convert` command exists, as you +can also create and run a conversion graph with the generic +man:babeltrace2-run(1) command. + +For example, you can specify one or more CTF trace path as non-option +arguments to pretty-print the merged events to the standard output: [role="term"] ---- -$ babeltrace2 /path/to/trace +$ babeltrace2 /path/to/trace /path/to/other/trace ---- This is the equivalent of creating and connecting together: -* A compcls:src.ctf.fs component with its manparam:source.ctf.fs:path - initialization parameter set to `/path/to/trace`. +* One compcls:source.ctf.fs components with its + manparam:source.ctf.fs:inputs initialization parameter set to + `/path/to/trace`. + +* One compcls:source.ctf.fs components with its + manparam:source.ctf.fs:inputs initialization parameter set to + `/path/to/other/trace`. * A compcls:filter.utils.muxer component. @@ -117,33 +138,44 @@ This is the equivalent of creating and connecting together: This creates the following conversion graph: ---- -+------------+ +--------------------+ +------------------+ -| src.ctf.fs | | filter.utils.muxer | | sink.text.pretty | -| [ctf-fs] | | [muxer] | | [pretty] | -| | | | | | -| stream0 @--->@ out @--->@ in | -| stream1 @--->@ | +------------------+ -| stream2 @--->@ | -| stream3 @--->@ | -+------------+ +--------------------+ ++------------+ +-----------------+ +------------------+ +| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty | +| [ctf-fs] | | [muxer] | | [pretty] | +| | | | | | +| stream0 @--->@ in0 out @--->@ in | +| stream1 @--->@ in1 | +------------------+ +| stream2 @--->@ in2 | +| stream3 @--->@ in3 | ++------------+ | | + | | ++------------+ | | +| src.ctf.fs | | | +| [ctf-fs-2] | | | +| | | | +| stream0 @--->@ in4 | +| stream1 @--->@ in5 | ++------------+ @ in6 | + +-----------------+ ---- -It is equivalent to the following command: +It is equivalent to the following man:babeltrace2-run(1) command line: [role="term"] ---- $ babeltrace2 run --component=ctf-fs:src.ctf.fs \ - --params=path=/path/to/trace \ - --component=pretty:sink.text.pretty \ - --component=muxer:filter.utils.muxer \ - --connect=ctf-fs:muxer --connect=muxer:pretty + --params='inputs=["/path/to/trace"] \ + --component=ctf-fs-2:src.ctf.fs \ + --params='inputs=["/path/to/other/trace"] \ + --component=muxer:filter.utils.muxer \ + --component=pretty:sink.text.pretty \ + --connect=ctf*:muxer --connect=muxer:pretty ---- You can use the opt:--run-args option to make the `convert` command -print its equivalent man:babeltrace2-run(1) arguments instead of -creating and running the conversion graph. The printed arguments are -escaped for shells, which means you can use them as is on the command -line and possibly add more options to the `run` command: +print its equivalent `run` command arguments instead of creating and +running the conversion graph. The printed arguments are escaped for +shells, which means you can use them as is on the command line and +possibly add more options to the `run` command: [role="term"] ---- @@ -156,17 +188,16 @@ character instead of a space. This is useful if the resulting arguments are not the direct input of a shell, for example if passed to `xargs -0`. -See <> for usage examples. +See <> for usage examples. [[comp-create-expl]] -Create explicit components -~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Create explicit components + To explicitly create a component, use the opt:--component option. This option specifies: -* **Optional**: The name of the component instance. You can also use the - opt:--name option for this. +* **Optional**: The name of the component. * The type of the component class to instantiate: source, filter, or sink. @@ -182,95 +213,101 @@ multiple times as different component instances. Immediately following a opt:--component option on the command line, the created component is known as the _current component_ (until the next -opt:--component option). +opt:--component option or non-option argument). -The following, optional command-line options apply to the current -component: +The following command-line options apply to the current component: -opt:--name='NAME':: - Set the name of the current component to 'NAME'. +opt:--log-level='LVL':: + Set the log level of the current component to 'LVL'. opt:--params='PARAMS':: Add 'PARAMS' to the initialization parameters of the current - component. If 'PARAMS' contains a key which exists in the current - component's initialization parameters, this parameter is replaced. -+ -See <> for the format of 'PARAMS'. - -opt:--path='PATH':: - Set the nlparam:path initialization parameter of the current - component to 'PATH' (replace the parameter if it exists). + component. + -You can use this option instead of manually specifying `path="PATH"` in -a opt:--params option to use your shell's tilde expansion (`~`). Tilde -expansion requires the tilde to be the first character of the argument, -which is not possible with `path="PATH"`. +If 'PARAMS' contains a key which exists in the current component's +initialization parameters, replace the parameter. -opt:--url='URL':: - Set the nlparam:url initialization parameter of the current - component to 'URL' (replace the parameter if it exists). +See <> for usage examples. -See <> for usage examples. +[[comp-create-impl-non-opt]] +=== Create implicit components from non-option arguments -[[comp-create-impl]] -Create implicit components -~~~~~~~~~~~~~~~~~~~~~~~~~~ -An _implicit component_ is a component which is created and added to the -conversion graph without an explicit instantiation through the -opt:--component option. An implicit component is easier to create than -an explicit component: this is why the `convert` command exists, as you -can also create and run a conversion graph with the generic -man:babeltrace2-run(1) command. +When you specify a non-option argument to the `convert` command, it +tries to find one or more components which can handle this argument. -There are many ways to create implicit components with the `convert` -command: +For example, with this command line: -* To create one or more implicit compcls:src.ctf.fs components (CTF - trace read from the file system), use one or more positional arguments - to specify the paths to the CTF traces to read, and do :not: specify - the opt:--input-format=`lttng-live` option. -+ -Example: -+ [role="term"] ---- -$ babeltrace2 /path/to/trace /path/to/other/trace +$ babeltrace2 /path/to/trace ---- + +If `/path/to/trace` is a CTF trace directory, then the `convert` command +creates a compcls:source.ctf.fs component to handle this specific trace. + +This automatic source component discovery mechanism is possible thanks +to component classes which support the `babeltrace.support-info` query +object (see man:babeltrace2-query-babeltrace.support-info(7)). + +The non-option argument can be a directory. If no component can handle +that specific directory, then the `convert` command traverses that +directory and recursively tries to find compatible components for each +file and subdirectory. This means that a single non-option argument can +lead to the creation of many implicit components. + +The following command-line options apply to :all: the implicit +components created from the last non-option argument: + +opt:--log-level='LVL':: + Set the log level of those implicit components to 'LVL'. + +opt:--params='PARAMS':: + Add 'PARAMS' to the initialization parameters of those implicit + components. + -The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_ -the implicit compcls:src.ctf.fs components. For example: -+ +For a given implicit component, if 'PARAMS' contains a key which exists +in this component's initialization parameters, replace the parameter. + +Note that it's also possible for two non-option arguments to cause the +creation of a single implicit component. For example, if you specify: + [role="term"] ---- -$ babeltrace2 --clock-offset=3 trace1 trace2 +$ babeltrace2 /path/to/chunk1 /path/to/chunk2 ---- -+ -With the command line above, two implicit compcls:src.ctf.fs components -have their manparam:source.ctf.fs:clock-class-offset-s initialization -parameter set to `3`, but they have different -manparam:source.ctf.fs:path parameters (`trace1` and `trace2`). -+ -You cannot create implicit compcls:src.ctf.fs components and an implicit -compcls:src.ctf.lttng-live component. -* To create an implicit compcls:src.ctf.lttng-live component - (http://lttng.org/docs/#doc-lttng-live[LTTng live] input), specify the - opt:--input-format=`lttng-live` option and the LTTng relay daemon's - URL with the positional argument. -+ -Example: -+ +where `/path/to/chunk1` and `/path/to/chunk2` are paths to chunks of the +same logical CTF trace, then the `convert` command creates a single +compcls:source.ctf.fs component which receives both paths at +initialization time. When this happens, any opt:--log-level or +opt:--params option that you specify to one of them applies to the +single implicit component. For example: + [role="term"] ---- -$ babeltrace2 --input-format=lttng-live \ - net://localhost/host/abeille/my-session +$ babeltrace2 /path/to/chunk1 --params=clock-class-offset-s=450 \ + /path/to/chunk2 --params=clock-class-offset-ns=98 \ + --log-level=INFO ---- -+ -You cannot create an implicit compcls:src.ctf.lttng-live component and -implicit compcls:src.ctf.fs components. -* To create an implicit compcls:filter.utils.trimmer component (trace +Here, the single implicit component gets both `clock-class-offset-s` and +`clock-class-offset-ns` initialization parameters, as well as the INFO +log level. + +For backward compatibility with the man:babeltrace(1) program, the +`convert` command ignores any non-option argument which does not cause +the creation of any component. In that case, it emits a warning log +statement and continues. + + +[[comp-create-impl-opt]] +=== Create implicit components from options + +There are many ways to create implicit components from options with the +`convert` command: + +* To create an implicit compcls:filter.utils.trimmer component (stream trimmer), specify the opt:--begin, opt:--end, or opt:--timerange option. + @@ -300,13 +337,13 @@ Examples: + [role="term"] ---- -$ babeltrace2 --debug-info /path/to/trace +$ babeltrace2 /path/to/trace --debug-info ---- + [role="term"] ---- $ babeltrace2 /path/to/trace \ - --debug-info-target-prefix=/tmp/tgt-root + --debug-info-target-prefix=/tmp/tgt-root ---- + [role="term"] @@ -315,24 +352,23 @@ $ babeltrace2 /path/to/trace --debug-info-full-path ---- * To create an implicit compcls:sink.text.pretty component - (pretty-printing text output to the console or to a file), do any of: + (pretty-printing text output to the standard output or to a file), + specify no other sink components, explicit or implicit. + --- -* Specify no other sink components, <> or - implicit. The compcls:sink.text.pretty implicit component is the - _default_ implicit sink component. If any other explicit or implicit - component exists, the default compcls:sink.text.pretty sink component - is not automatically created. - -* Specify any of the opt:--clock-cycles, opt:--clock-date, - opt:--clock-gmt, opt:--clock-seconds, opt:--color, opt:--fields, - opt:--names, or opt:--no-delta options. You can also specify the - opt:--output option without using the opt:--output-format=`ctf` option - (in which case opt:--output applies to the implicit - compcls:sink.ctf.fs component). - -* Specify the opt:--output-format=`text` option. --- +The implicit compcls:sink.text.pretty component exists by default. If +any other explicit or implicit sink component exists, the `convert` +command does not automatically create the implicit +compcls:sink.text.pretty component. ++ +The opt:--clock-cycles, opt:--clock-date, opt:--clock-gmt, +opt:--clock-seconds, opt:--color, opt:--fields, opt:--names, and +opt:--no-delta options all apply to the implicit +compcls:sink.text.pretty component. ++ +The opt:--output option without opt:--output-format=`ctf` makes the +implicit compcls:sink.text.pretty component write its content to a file, +except the warnings for backward compatibility with the +man:babeltrace(1) program. + Examples: + @@ -348,17 +384,11 @@ $ babeltrace2 /path/to/trace --no-delta + [role="term"] ---- -$ babeltrace2 /path/to/trace --output-format=text ----- -+ -[role="term"] ----- $ babeltrace2 /path/to/trace --output=/tmp/pretty-out ---- -* To create an implicit compcls:sink.utils.dummy component (dummy - output), specify the opt:--output-format=`dummy` option. This option - disables the default implicit compcls:sink.text.pretty component. +* To create an implicit compcls:sink.utils.dummy component (no output), + specify the opt:--output-format=`dummy` option. + Example: + @@ -369,26 +399,24 @@ $ babeltrace2 /path/to/trace --output-format=dummy * To create an implicit compcls:sink.ctf.fs component (CTF traces written to the file system), specify the opt:--output-format=`ctf` - option. This option disables the default implicit - compcls:sink.text.pretty component. Use the opt:--output option to - specify the output directory. + and the opt:--output='DIR' (base output directory) options. + Example: + [role="term"] ---- $ babeltrace2 /path/to/input/trace --output-format=ctf \ - --output=my-traces + --output=my-traces ---- -You can combine multiple methods to create implicit components. For -example, you can trim an LTTng (CTF) trace, add debugging information to -it, and write it as another CTF trace: +You can combine multiple methods to create multiple implicit components. +For example, you can trim an LTTng (CTF) trace, add debugging +information to it, and write it as another CTF trace: [role="term"] ---- $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \ - --debug-info --output-format=ctf --output=out-dir + --debug-info --output-format=ctf --output=out-dir ---- The equivalent man:babeltrace2-run(1) command of this `convert` command @@ -396,76 +424,44 @@ is: [role="term"] ---- -$ babeltrace2 run --component=src-ctf-fs:src.ctf.fs \ - --params=path=/path/to/input/trace \ - --component=sink-ctf-fs:sink.ctf.fs \ - --params=path=out-dir \ - --component=muxer:flt.utils.muxer \ - --component=trimmer:flt.utils.trimmer \ - '--params=begin="22:14:38"' \ - '--params=end="22:15:07"' \ - --component=dbginfo:flt.lttng-utils.debug-info \ - --connect=src-ctf-fs:muxer --connect=muxer:trimmer \ - --connect=trimmer:dbg-info \ - --connect=dbginfo:sink-ctf-fs +$ babeltrace2 run --component=auto-disc-source-ctf-fs:source.ctf.fs \ + --params='inputs=["/path/to/input/trace"]' \ + --component=sink-ctf-fs:sink.ctf.fs \ + --params='path="out-dir"' \ + --component=muxer:filter.utils.muxer \ + --component=trimmer:filter.utils.trimmer \ + --params='begin="22:14:38"' \ + --params='end="22:15:07"' \ + --component=debug-info:filter.lttng-utils.debug-info \ + --connect=auto-disc-source-ctf-fs:muxer \ + --connect=muxer:trimmer \ + --connect=trimmer:debug-info \ + --connect=debug-info:sink-ctf-fs ---- -See <> for more examples. - - -include::common-cmd-params-format.txt[] - +The order of the implicit component options documented in this +subsection is not significant. -[[time-fmt]] -Time option format -~~~~~~~~~~~~~~~~~~ -The format of the arguments of the opt:--begin and opt:--end options -is: - -[verse] -$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__] - -'YYYY':: - 4-digit year. - -'MM':: - 2-digit month (January is `01`). - -'DD':: - 2-digit day. - -'hh':: - 2-digit hour (24-hour format). +See <> for more examples. -'mm':: - 2-digit minute. -'ss':: - 2-digit second. +== OPTIONS -'nnnnnnnnn':: - 9-digit nanosecond. - - -include::common-cmd-plugin-path.txt[] - - -OPTIONS -------- include::common-gen-options.txt[] -Explicit component creation -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See <> to learn how to -use the following options. +=== Explicit component creation -opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS':: - Create a component initially named 'NAME' (if specified) from the - component class of type 'TYPE' named 'COMPCLS' found in the plugin - named 'PLUGIN', and set it as the current component. +See <> to learn how to +use the following option. + +opt:-c $$[$$__NAME__:]'COMP-CLS-TYPE'.'PLUGIN-NAME'.'COMP-CLS-NAME':: +opt:--component=$$[$$__NAME__:]'COMP-CLS-TYPE'.'PLUGIN-NAME'.'COMP-CLS-NAME':: + Create a component named 'NAME' (if specified) from the component + class of type 'COMP-CLS-TYPE' named 'COMP-CLS-NAME' found in the + plugin named 'PLUGIN-NAME', and set it as the current component. + -The available values for 'TYPE' are: +The available values for 'COMP-CLS-TYPE' are: + -- `source`:: @@ -480,111 +476,137 @@ The available values for 'TYPE' are: Sink component class. -- -opt:--name='NAME':: - Set the name of the current component to 'NAME'. The names of all - the explicitly created components in the conversion graph must be - unique. -opt:-p 'PARAMS', opt:--params='PARAMS':: - Add 'PARAMS' to the initialization parameters of the current - component. If 'PARAMS' contains a key which exists in the current - component's initialization parameters, replace the parameter. - See <> for the format of 'PARAMS'. +=== Common component creation + +See <> and +<> to learn how to use the following options. -opt:-P 'PATH', opt:--path='PATH':: - Set the nlparam:path initialization parameter of the current - component to 'PATH' (replace the parameter if it exists). +The following options apply to either the current explicit component +(last opt:--component option) or to :all: the implicit components +created from the last non-option argument. + +opt:-l 'LVL':: +opt:--log-level='LVL':: + Set the log level of the current component(s) to 'LVL'. ++ +The available values for 'LVL' are: ++ +-- +include::common-log-levels.txt[] +-- + +opt:-p 'PARAMS':: +opt:--params='PARAMS':: + Add 'PARAMS' to the initialization parameters of the current + component(s). ++ +If 'PARAMS' contains a key which exists in the initialization parameters +of the current component(s), replace the parameter. ++ +-- +include::common-cmd-params-format.txt[] +-- -opt:-u 'URL', opt:--url='URL':: - Set the nlparam:url initialization parameter of the current - component to 'URL' (replace the parameter if it exists). +=== Legacy options to create implicit components -Legacy options to create implicit components -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -opt:-i 'FORMAT', opt:--input-format='FORMAT':: - Create one or more implicit source components. The available values - for 'FORMAT' are: +opt:-i 'FORMAT':: +opt:--input-format='FORMAT':: + Force the `convert` command to create components from a specific + component class for non-option arguments (see + <>), or list available remote LTTng tracing + sessions. ++ +The available values for 'FORMAT' are: + -- `ctf`:: - Create an implicit compcls:src.ctf.fs component for each positional - argument. Each positional argument sets the - manparam:source.ctf.fs:path initialization parameter of an - individual component. See <>. + Use the compcls:source.ctf.fs component class. ++ +Each non-option argument of the command line is a CTF trace or CTF +trace chunk. + See man:babeltrace2-source.ctf.fs(7) to learn more about this component class. `lttng-live`:: - Depending on the format of the positional argument: + Depending on the format of the first non-option argument: + -- -`net[4]://RDHOST[:RDPORT]/host/TGTHOST`:: - Print the available LTTng live sessions of the LTTng relay daemon at - the address `RDHOST` and port `RDPORT`, and then exit. +`net[4]://RDHOST[:RDPORT]`:: + List the available remote LTTng tracing sessions for the LTTng relay + daemon at the address `RDHOST` and port `RDPORT` ({defrdport} if not + specified), and then exit. `net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`:: - Create an implicit compcls:src.ctf.lttng-live component. The - position argument sets the manparam:source.ctf.lttng-live:url - parameter of the component. -+ -Any other format for the positional argument is invalid. + Use the compcls:source.ctf.lttng-live component class. + -See man:babeltrace2-source.ctf.lttng-live(7) to learn more about -this component class. +See man:babeltrace2-source.ctf.lttng-live(7) to learn more about this +component class and the URL format. -- -- + You can specify at most one opt:--input-format option. opt:-o 'FORMAT', opt:--output-format='FORMAT':: - Create an implicit sink component. The available values for 'FORMAT' - are: + Create an implicit sink component with format 'FORMAT' or print + the metadata text of a CTF trace. ++ +The available values for 'FORMAT' are: + -- `text`:: Create an implicit compcls:sink.text.pretty component. - See <>. + -See man:babeltrace2-sink.text.pretty(7) to learn more about -this component class. +See <>. ++ +See man:babeltrace2-sink.text.pretty(7) to learn more about this +component class. `ctf`:: - Create an implicit compcls:sink.ctf.fs component. Specify the output - path with the opt:--output option. + Create an implicit compcls:sink.ctf.fs component. Specify the base + output path with the opt:--output option. + -See man:babeltrace2-sink.ctf.fs(7) to learn more about -this component class. +See man:babeltrace2-sink.ctf.fs(7) to learn more about this component +class. `dummy`:: Create an implicit compcls:sink.utils.dummy component. + -See man:babeltrace2-sink.utils.dummy(7) to learn more about -this component class. +See man:babeltrace2-sink.utils.dummy(7) to learn more about this +component class. `ctf-metadata`:: - Print the metadata text of a CTF trace and exit. The first - positional argument specifies the path to the CTF trace. + Print the metadata text of a CTF trace and exit. ++ +The first non-option argument specifies the path to the CTF trace. -- + You can specify at most one opt:--output-format option. [[impl-opts-ctf]] -Implicit compcls:src.ctf.fs component(s) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is one implicit compcls:src.ctf.fs component per positional -argument (which are trace paths), unless you specify -opt:--input-format=`lttng-live`. +=== Implicit compcls:source.ctf.fs component(s) -See man:babeltrace2-source.ctf.fs(7) to learn more about this -component class. +See man:babeltrace2-source.ctf.fs(7) to learn more about this component +class. + +opt:--clock-force-correlate:: + Set the manparam:source.ctf.fs:force-clock-class-origin-unix-epoch + initialization parameter of all the implicit compcls:source.ctf.fs + components to true. ++ +The manparam:source.ctf.fs:force-clock-class-origin-unix-epoch +initialization parameter makes all the created clock classes have a Unix +epoch origin. This is useful to force the clock classes of multiple +traces to be compatible even if they are not inherently. opt:--clock-offset='SEC':: Set the manparam:source.ctf.fs:clock-class-offset-s initialization - parameter of all the implicit compcls:src.ctf.fs components to + parameter of all the implicit compcls:source.ctf.fs components to 'SEC'. + The manparam:source.ctf.fs:clock-class-offset-s initialization parameter @@ -595,7 +617,7 @@ You can combine this option with opt:--clock-offset-ns. opt:--clock-offset-ns='NS':: Set the manparam:source.ctf.fs:clock-class-offset-ns initialization - parameter of all the implicit compcls:src.ctf.fs components to + parameter of all the implicit compcls:source.ctf.fs components to 'NS'. + The manparam:source.ctf.fs:clock-class-offset-ns initialization @@ -605,44 +627,53 @@ that the component creates. You can combine this option with opt:--clock-offset-s. -Implicit compcls:filter.utils.trimmer component -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Implicit compcls:filter.utils.trimmer component + If you specify at least one of the following options, you create an implicit compcls:filter.utils.trimmer component. See man:babeltrace2-filter.utils.trimmer(7) to learn more about this component class. -See <> for the format of 'BEGIN' and 'END'. - -opt:--begin='BEGIN':: +opt:--begin='TIME':: Set the manparam:filter.utils.trimmer:begin initialization parameter - of the component to 'BEGIN'. You cannot use this option with the - opt:--timerange option. + of the component to 'TIME'. ++ +You cannot use this option with the opt:--timerange option. ++ +The format of 'TIME' is one of: ++ +-- +include::common-trimmer-time-format.txt[] +-- -opt:--end='END':: +opt:--end='TIME':: Set the manparam:filter.utils.trimmer:end initialization parameter - of the component to 'END'. You cannot use this option with the - opt:--timerange option. + of the component to 'TIME'. ++ +You cannot use this option with the opt:--timerange option. ++ +See the opt:--begin option for the format of 'TIME'. opt:--timerange='BEGIN','END':: - Equivalent to opt:--begin='BEGIN' opt:--end='END'. + Equivalent to opt:--begin='BEGIN' and opt:--end='END'. + You can also surround the whole argument with `[` and `]`. -Implicit compcls:filter.lttng-utils.debug-info component -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Implicit compcls:filter.lttng-utils.debug-info component + If you specify at least one of the following options, you create an implicit compcls:filter.lttng-utils.debug-info component. This component only alters compatible LTTng events. -See man:babeltrace2-filter.lttng-utils.debug-info(7) to learn more -about this component class. +See man:babeltrace2-filter.lttng-utils.debug-info(7) to learn more about +this component class. opt:--debug-info:: Create an implicit compcls:filter.lttng-utils.debug-info component. - This option is useless if you specify any of the options below. ++ +This option is useless if you specify any of the options below. opt:--debug-info-dir='DIR':: Set the manparam:filter.lttng-utils.debug-info:debug-info-dir @@ -676,10 +707,9 @@ debugging information. [[impl-opts-text]] === Implicit compcls:sink.text.pretty component -If you specify at least one of the following options, you create an -implicit compcls:sink.text.pretty component. The `convert` command also -creates a default implicit compcls:sink.text.pretty component if no -other sink component exists. +If you specify at least one of the following options, you force the +`convert` command's sink component to be an implicit +compcls:sink.text.pretty component. See man:babeltrace2-sink.text.pretty(7) to learn more about this component class. @@ -710,7 +740,7 @@ opt:--clock-seconds:: parameter of the component to true. + The manparam:sink.text.pretty:clock-seconds parameter makes the -component print the event times in seconds since Epoch. +component print the event times in seconds since the Unix epoch. opt:--color='WHEN':: Set the manparam:sink.text.pretty:color initialization parameter of @@ -720,9 +750,8 @@ The available values for 'WHEN' are: + -- `auto`:: - Automatic color support depending on the capabilities of the - terminal(s) to which the standard output and error streams are - connected. + Only emit terminal color codes when the standard output and error + streams are connected to a color-capable terminal. `never`:: Never emit terminal color codes. @@ -777,229 +806,118 @@ When the manparam:sink.text.pretty:no-delta parameter is true, the component does not print the duration since the last event on the line. -Shared options -~~~~~~~~~~~~~~ -opt:-w 'PATH', opt:--output='PATH':: +=== Shared options + +opt:-w 'PATH':: +opt:--output='PATH':: With opt:--output-format=`ctf-metadata` or - opt:--input-format=`lttng-live` (when printing the available LTTng - live sessions), write the text to the file 'PATH' instead of the - standard output. + opt:--input-format=`lttng-live` (when printing the available remote + LTTng tracing sessions), write the text to the file 'PATH' instead + of the standard output. + When you specify opt:--output-format=`ctf`, set the manparam:sink.ctf.fs:path initialization parameter of the implicit -compcls:sink.ctf.fs component to 'PATH'. Otherwise, create an implicit +compcls:sink.ctf.fs component to 'PATH'. ++ +Without any specified sink component, explicit or implicit, force the +`convert` command's sink component to be an implicit compcls:sink.text.pretty component and set its manparam:sink.text.pretty:path initialization parameter to 'PATH'. + See man:babeltrace2-sink.ctf.fs(7) and -man:babeltrace2-sink.text.pretty(7) to learn more about those -component classes. +man:babeltrace2-sink.text.pretty(7) to learn more about those component +classes. + +=== Equivalent `babeltrace2 run` arguments -Equivalent `babeltrace2 run` arguments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ opt:--run-args:: Print the equivalent man:babeltrace2-run(1) arguments instead of - creating and running the conversion graph. The printed arguments are - space-separated and individually escaped for safe shell input. + creating and running the conversion graph. ++ +The printed arguments are space-separated and individually escaped for +safe shell input. + You cannot use this option with the opt:--run-args-0 or opt:--stream-intersection option. opt:--run-args-0:: Print the equivalent man:babeltrace2-run(1) arguments instead of - creating and running the conversion graph. The printed arguments are - separated with a null character and :not: escaped for safe shell - input. + creating and running the conversion graph. ++ +The printed arguments are separated with a null character and :not: +escaped for safe shell input. + You cannot use this option with the opt:--run-args or opt:--stream-intersection option. -Conversion graph configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -opt:--retry-duration='DURUS':: - Set the duration of a single retry to 'DURUS'{nbsp}µs when a +=== Conversion graph configuration + +opt:--retry-duration='TIME-US':: + Set the duration of a single retry to 'TIME-US'~µs when a sink component reports "try again later" (busy network or file system, for example). + -Default: 100000 (100{nbsp}ms). +Default: 100000 (100~ms). opt:--stream-intersection:: - Enable the stream intersection mode. In this mode, for each trace, - the `convert` command filters out the events and other notifications - which are not in the time range where _all_ the trace's streams are - active. + Enable the stream intersection mode. + -All the source components, <> and -<>, must have classes which support the -`babeltrace.trace-info` query object to use this option. The only -Babeltrace project's component class which supports this query object is -compcls:source.ctf.fs. +In this mode, for each trace, the `convert` command filters out the +events and other messages which are not in the time range where _all_ +the trace's streams are active. + -Because it is not possible to replicate with a single -man:babeltrace2-run(1) command line what the `convert` method does with -the opt:--stream-intersection option, you cannot use this option with -the opt:--run-args or opt:--run-args-0 option. - +To use this option, all the source components, explicit and implicit, +must have classes which support the `babeltrace.trace-infos` query +object (see man:babeltrace2-query-babeltrace.trace-infos(7)). The only +Babeltrace~2 project's component class which supports this query +object is compcls:source.ctf.fs. ++ +You cannot use this option with the opt:--run-args or opt:--run-args-0 +option. -Plugin path -~~~~~~~~~~~ -opt:--omit-home-plugin-path:: - Do not search for plugins in `$HOME/.local/lib/babeltrace2/plugins`. +=== Other legacy options -opt:--omit-system-plugin-path:: - Do not search for plugins in +{system_plugin_path}+. +The following options exist for backward compatibility with the +man:babeltrace(1) program. -opt:--plugin-path='PATH'[:__PATH__]...:: - Add 'PATH' to the list of paths in which dynamic plugins can be - found. +opt:-d:: +opt:--debug:: + Legacy option: this is equivalent to nlopt:--log-level=`TRACE`, + where nlopt:--log-level is the general option (not this command's + opt:--log-level option). +opt:-v:: +opt:--verbose:: + Legacy option: this is equivalent to nlopt:--log-level=`INFO`, where + nlopt:--log-level is the general option (not this command's + opt:--log-level option). ++ +This option also sets the manparam:sink.text.pretty:verbose parameter of +the implicit compcls:sink.text.pretty component (see +man:babeltrace2-sink.text.pretty(7)) to true. -Command information -~~~~~~~~~~~~~~~~~~~ -opt:-h, opt:--help:: - Show command help and quit. +include::common-cmd-info-options.txt[] [[examples]] -EXAMPLES --------- -.Pretty-print the events of one or more CTF traces. -==== -[role="term"] ----- -$ babeltrace2 my-trace ----- +== EXAMPLES -[role="term"] ----- -$ babeltrace2 my-traces ----- - -[role="term"] ----- -$ babeltrace2 my-trace-1 my-trace-2 my-trace-3 ----- -==== - -.Trim a CTF trace and pretty-print the events. -==== -[role="term"] ----- -$ babeltrace2 my-trace --begin=22:55:43.658582931 \ - --end=22:55:46.967687564 ----- - -[role="term"] ----- -$ babeltrace2 my-trace --begin=22:55:43.658582931 ----- - -[role="term"] ----- -$ babeltrace2 my-trace --end=22:55:46.967687564 ----- - -[role="term"] ----- -$ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564 ----- -==== - -.Trim a CTF trace, enable the stream intersection mode, and generate a CTF trace. -==== -[role="term"] ----- -$ babeltrace2 my-trace --stream-intersection \ - --timerange=22:55:43,22:55:46.967687564 \ - --output-format=ctf --output=out-trace ----- -==== - -.Record LTTng live traces to the file system (as CTF traces). -==== -[role="term"] ----- -$ babeltrace2 --input-format=lttng-live \ - net://localhost/host/myhostname/auto-20170411-134512 \ - --output-format=ctf --output=/path/to/generated/traces ----- -==== - -.Read a CTF trace as fast as possible using a dummy output. -==== -[role="term"] ----- -$ babeltrace2 my-trace --output-format=dummy ----- -==== - -.Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file. -==== -[role="term"] ----- -$ babeltrace2 trace1 trace2 trace3 --stream-intersection \ - --debug-info --output=pretty-out ----- -==== - -.Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since Epoch. -==== -[role="term"] ----- -$ babeltrace2 ctf-trace --component=src.my-plugin.my-src \ - --params=output-some-event-type=yes --clock-seconds ----- -==== - -.Send LTTng live events to an explicit sink component. -==== -[role="term"] ----- -$ babeltrace2 --input-format=lttng-live \ - net://localhost/host/myhostname/mysession \ - --component=sink.my-plugin.my-sink ----- -==== - -.Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace. -==== -[role="term"] ----- -$ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07 \ - --debug-info --component=filter.my-plugin.my-filter \ - --params=criteria=xyz,ignore-abc=yes \ - --output-format=ctf --output=out-trace ----- -==== - -.Print the metadata text of a CTF trace. -==== -[role="term"] ----- -$ babeltrace2 /path/to/trace --output-format=ctf-metadata ----- -==== - -.Print the available LTTng live sessions of an LTTng relay daemon. -==== -[role="term"] ----- -$ babeltrace2 --input-format=lttng-live net://localhost ----- -==== +include::common-convert-examples.txt[] include::common-cli-env.txt[] + include::common-cli-files.txt[] + include::common-cmd-footer.txt[] -SEE ALSO --------- +== SEE ALSO + +man:babeltrace2-intro(7), man:babeltrace2(1), -man:babeltrace2-run(1), -man:babeltrace2-intro(7) +man:babeltrace2-run(1)