Provided by: babeltrace2_2.0.5-1_amd64 bug

NAME

       babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component class

DESCRIPTION

       A Babeltrace 2 sink.ctf.fs component writes the messages it consumes to one or more CTF
       (see <https://diamon.org/ctf/>) 1.8 traces on the file system.

                       +-------------+
                       | sink.ctf.fs |
                       |             +--> CTF trace(s) on
           Messages -->@ in          |    the file system
                       +-------------+

       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project and its core
       concepts.

       A sink.ctf.fs component does not merge traces: it writes the messages of different input
       traces to different output traces.

   Special trace IR to CTF translations
       A sink.ctf.fs component makes a best effort to write CTF traces that are semantically
       equivalent to the input traces. As of this version, the component writes CTF 1.8 traces,
       so the following field class translations can occur:

       •   The component translates a boolean field class to a CTF unsigned 8-bit integer field
           class.

           The unsigned integer field’s value is 0 when the boolean field’s value is false and 1
           when the boolean field’s value is true.

       •   The component translates a bit array field to a CTF unsigned integer field class
           having the same length.

       •   The component translates an option field class to a CTF variant field class where the
           options are an empty structure field class and the optional field class itself.

           The empty structure field is selected when the option field has no field.

       In all the cases above, the component adds a comment in the metadata stream, above the
       field class, to indicate that a special translation occurred.

   Input message constraints
       Because of limitations in CTF 1.8 regarding how discarded events and packets are encoded:

       •   If a stream class supports discarded events and the ignore-discarded-events parameter
           is NOT true:

           •   The stream class must support packets.

           •   Discarded events messages must have times.

           •   Any discarded events message must occur between a packet end and a packet
               beginning message.

           •   The beginning time of a discarded events message must be the same as the time of
               the last packet end message.

           •   The end time of a discarded events message must be the same as the time of the
               next packet end message.

           •   Time ranges of discarded events messages must not overlap.

       •   If a stream class supports discarded packets and the ignore-discarded-packets
           parameter is NOT true:

           •   The stream class must support packets.

           •   Discarded packets messages must have times.

           •   The beginning time of a discarded events message must be the same as the time of
               the last packet end message.

           •   The end time of a discarded events message must be the same as the time of the
               next packet beginning message.

           •   Time ranges of discarded packets messages must not overlap.

       The messages which a source.ctf.fs component creates satisfy all the requirements above.

       If a discarded events or packets message has no events/packets count, the sink.ctf.fs
       component adds 1 to the corresponding CTF stream’s counter.

   Alignment and byte order
       A sink.ctf.fs component always aligns data fields as such:

       Integer fields with a size which is not a multiple of 8
           1-bit.

       All other scalar fields (integer, enumeration, real, string)
           8-bit.

       The component writes fields using the machine’s native byte order. As of this version,
       there’s no way to force a custom byte order.

   Output path
       The path of a CTF trace is the directory which directly contains the metadata and data
       stream files.

       The current strategy to build a path in which to write the streams of a given input trace
       is, in this order:

        1. If the assume-single-trace parameter is true, then the output trace path to use for
           the single input trace is the directory specified by the path parameter.

        2. If the component recognizes the input trace as an LTTng (2.11 or greater) trace, then
           it checks specific trace environment values to build a trace path relative to the
           directory specified by the path parameter:

           Linux kernel domain

                   HOST/SNAME-STIME/kernel

           User space domain, per-UID buffering

                   HOST/SNAME-STIME/ust/uid/UID/ARCHW-bit

           User space domain, per-PID buffering

                   HOST/SNAME-STIME/ust/pid/PNAME-PID-PTIME

           With:

           HOST
               Target’s hostname.

           SNAME
               Tracing session name.

           STIME
               Tracing session creation date/time.

           UID
               User ID.

           ARCHW
               Architecture’s width (32 or 64).

           PNAME
               Process name.

           PID
               Process ID.

           PTIME
               Process’s date/time.

        3. If the input trace has a name, then the component sanitizes this name and uses it as a
           relative path to the directory specified by the path parameter.

           The trace name sanitization operation:

           •   Replaces .  subdirectories with _.

           •   Replaces ..  subdirectories with __.

           •   Removes any trailing / character.

        4. The component uses the subdirectory trace relative to the directory specified by the
           path parameter.

       In all the cases above, if the effective output trace path already exists on the file
       system, the component appends a numeric suffix to the name of the last subdirectory. The
       suffix starts at 0 and increments until the path does not exist.

INITIALIZATION PARAMETERS

       assume-single-trace=yes [optional boolean]
           Assume that the component only receives messages related to a single input trace.

           This parameter affects how the component builds the output trace path (see “Output
           path”).

       ignore-discarded-events=yes [optional boolean]
           Ignore discarded events messages.

       ignore-discarded-packets=yes [optional boolean]
           Ignore discarded packets messages.

       path=PATH [string]
           Base output path.

           See “Output path” to learn how the component uses this parameter to build the output
           path for a given input trace.

       quiet=yes [optional boolean]
           Do not write anything to the standard output.

PORTS

           +-------------+
           | sink.ctf.fs |
           |             |
           @ in          |
           +-------------+

   Input
       in
           Single input port.

BUGS

       If you encounter any issue or usability problem, please report it on the Babeltrace bug
       tracker (see <https://bugs.lttng.org/projects/babeltrace>).

RESOURCES

       The Babeltrace project shares some communication channels with the LTTng project (see
       <https://lttng.org/>).

       •   Babeltrace website (see <https://babeltrace.org/>)

       •   Mailing list (see <https://lists.lttng.org>) for support and development: lttng-
           dev@lists.lttng.org

       •   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on irc.oftc.net

       •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)

       •   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)

       •   GitHub project (see <https://github.com/efficios/babeltrace>)

       •   Continuous integration (see <https://ci.lttng.org/view/Babeltrace/>)

       •   Code review (see <https://review.lttng.org/q/project:babeltrace>)

AUTHORS

       The Babeltrace 2 project is the result of hard work by many regular developers and
       occasional contributors.

       The current project maintainer is Jérémie Galarneau
       <mailto:jeremie.galarneau@efficios.com>.

COPYRIGHT

       This component class is part of the Babeltrace 2 project.

       Babeltrace is distributed under the MIT license (see
       <https://opensource.org/licenses/MIT>).

SEE ALSO

       babeltrace2-intro(7), babeltrace2-plugin-ctf(7)