babeltrace2-sink.ctf.fs(7) — Linux manual page

NAME | DESCRIPTION | INITIALIZATION PARAMETERS | PORTS | BUGS | RESOURCES | AUTHORS | COPYRIGHT | SEE ALSO | COLOPHON

BABELTRACE2-SINK.(7)       Babeltrace 2 manual      BABELTRACE2-SINK.(7)

NAME         top

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

DESCRIPTION         top

       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         top

       assume-single-trace=VAL [optional boolean]
           If VAL is true, then 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”).

           Default: false.

       ignore-discarded-events=VAL [optional boolean]
           If VAL is true, then ignore discarded events messages.

           Default: false.

       ignore-discarded-packets=VAL [optional boolean]
           If VAL is true, then ignore discarded packets messages.

           Default: false.

       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=VAL [optional boolean]
           If VAL is true, then do not write anything to the standard
           output.

           Default: false.

PORTS         top

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

   Input
       in
           Single input port.

BUGS         top

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

RESOURCES         top

       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         top

       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         top

       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         top

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

COLOPHON         top

       This page is part of the babeltrace (trace read and write
       libraries and a trace converter) project.  Information about the
       project can be found at ⟨http://www.efficios.com/babeltrace⟩.  If
       you have a bug report for this manual page, send it to
       lttng-dev@lists.lttng.org.  This page was obtained from the
       project's upstream Git repository
       ⟨git://git.efficios.com/babeltrace.git⟩ on 2023-12-22.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-12-15.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Babeltrace 2.1.0-rc1        1 September 2023        BABELTRACE2-SINK.(7)

Pages that refer to this page: babeltrace2(1)babeltrace2-convert(1)babeltrace2-plugin-ctf(7)