BABELTRACE2-SINK.(7)

📦
version 2.1.2 · 6 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 babeltrace2-sink.ctf.fs — Babeltrace 2: File system CTF sink component class 💖

(that's a mouthful bestie, but we move — this is a Babeltrace 2 manual page and it's all about the sink that writes your traces to disk)

🌸 NAME 🌸

babeltrace2-sink.ctf.fs — Babeltrace 2: File system CTF sink component class

✨ DESCRIPTION ✨

Okay so picture this: a sink.ctf.fs component? It's the one that takes all the messages it consumes and writes them out as one or more CTF traces on the file system. (CTF = the Common Trace Format, peep <https://diamon.org/ctf/> for the lore.) Version 1.8 or 2, we got both. 👑

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

If you wanna actually understand the Babeltrace 2 project and its core concepts, go read babeltrace2-intro(7). It's giving required reading. 📚

The ctf-version parameter is the one calling the shots on which CTF version your resulting traces end up being.

As of this version, a sink.ctf.fs component may only write:

  • CTF 1.8 traces — when working under version 0 of the Message Interchange Protocol (MIP).
  • CTF 2 traces — when working under version 1 of the MIP.

So therefore, the "get supported MIP versions" method of a sink.ctf.fs component class reports that it supports only MIP 0 when the ctf-version parameter is set to 1, and only MIP 1 when ctf-version is set to 2. No mixing, no matching. Periodt.

Also, a sink.ctf.fs component doesn't merge traces — it writes the messages of different input traces to different output traces. Each trace stays in its own lane, main character energy only. 💅

🦋 Trace IR to CTF 1.8 translation 🦋

A sink.ctf.fs component makes a best effort to write CTF 1.8 traces that are semantically equivalent to the input traces. As of this version, with the ctf-version parameter set to 1, these are the field class translations that can occur:

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

The value of the unsigned integer field is 0 when the value of the boolean field is false and 1 when it's 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. (So future you knows what went down. 🫶)

The component doesn't translate any user attribute — a CTF 1.8 metadata stream has no way to represent them. It's just not built for that, ngl.

🌈 Trace IR to CTF 2 translation 🌈

As of this version, with the ctf-version parameter set to 2:

  • The component sets the sink.ctf.fs attribute, under the babeltrace.org,2020 namespace, of the preamble fragment to true.
  • The structure member class names of packet context field classes having a CTF 2 role have the metadata stream UUID as a prefix, so they don't clash with user member classes.

For example, the packet content length member class could be named afe9ed0e-ce73-413f-8956-83663bab2047-content_size. (Iconic UUID tbh.)

  • The component translates an event class log level to the log-level attribute under the babeltrace.org,2020 namespace as such:
    • BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY → "emergency"
    • BT_EVENT_CLASS_LOG_LEVEL_ALERT → "alert"
    • BT_EVENT_CLASS_LOG_LEVEL_CRITICAL → "critical"
    • BT_EVENT_CLASS_LOG_LEVEL_ERROR → "error"
    • BT_EVENT_CLASS_LOG_LEVEL_WARNING → "warning"
    • BT_EVENT_CLASS_LOG_LEVEL_NOTICE → "notice"
    • BT_EVENT_CLASS_LOG_LEVEL_INFO → "info"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM → "debug:system"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM → "debug:program"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS → "debug:process"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE → "debug:module"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT → "debug:unit"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION → "debug:function"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE → "debug:line"
    • BT_EVENT_CLASS_LOG_LEVEL_DEBUG → "debug:debug"
  • The component translates an event class EMF URI to the emf-uri attribute under the babeltrace.org,2020 namespace as a JSON string.
  • When the component needs to generate a length/selector field class F for dynamic field classes without a length/selector field:
    • The structure member name of F is unspecified.
    • F contains the is-key-only attribute, under the babeltrace.org,2020 namespace, set to true.
  • The component doesn't translate trace and stream user attributes — a CTF 2 metadata stream has no way to represent them.

🎀 Input message constraints 🎀

Because of limitations in CTF regarding how discarded events and packets are encoded, we got rules bestie. Listen up:

  • 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.

Good news: the messages which a source.ctf.fs component creates satisfy all the requirements above. So if that's your source, you're chilling. 😌

And if a discarded events or packets message has no events/packets count, then the sink.ctf.fs component adds 1 to the counter of the corresponding CTF stream.

💜 Alignment and byte order 💜

A sink.ctf.fs component always aligns data fields as such:

  • Fixed-length bit array fields with a size which isn't a multiple of 8 — 1-bit.
  • All other scalar fields (fixed-length bit array, null-terminated string, BLOB) — 8-bit.

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

🍓 Output path 🍓

The path of a CTF trace is the directory which directly contains the metadata and data stream files. Keep that in mind.

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 hostname.
  • SNAME — Tracing session name.
  • STIME — Tracing session creation date/time.
  • UID — User ID.
  • ARCHW — Architecture width (32 or 64).
  • PNAME — Process name.
  • PID — Process ID.
  • PTIME — Process date/time.
  1. 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.
  1. 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, then the component appends a numeric suffix to the name of the last subdirectory. The suffix starts at 0 and increments until the path doesn't exist. (Yes bestie it will keep going until it finds a free spot. Persistent queen. 👑)

⭐ INITIALIZATION PARAMETERS ⭐

  • 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.

  • ctf-version=VERSION [optional string] — Write traces following version VERSION of CTF, where VERSION is one of:
    • 1, 1.8 — CTF 1.8.
    • 2, 2.0 — CTF 2.

Default: 2.

  • 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 don't write anything to the standard output. (Shhh. 🤫)

Default: false.

🧚 PORTS 🧚

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

💖 Input 💖

  • in — Single input port. Just the one, she's exclusive. 💅

💀 BUGS 💀

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

🌈 RESOURCES

The Babeltrace project is literally in a situationship with the LTTng project when it comes to communication channels — they share them 💞 (peep <https://lttng.org/> if you wanna know more).

Here's where you can find your people, bestie:

💖 AUTHORS

The Babeltrace 2 project is the result of hard work by many regular developers and occasional contributors — it's giving group project where everyone actually did their part, no cap 🫡✨

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

This component class is part of the Babeltrace 2 project.

Babeltrace is distributed under the MIT license (see <https://opensource.org/licenses/MIT>). Yes bestie, the permissive one, go wild 💅

👀 SEE ALSO

okay that's the whole page, you made it to the end and honestly? iconic behavior 🎀 This was Babeltrace 2.1.2, dated 16 October 2024, and the page is BABELTRACE2-SINK.(7) — now go forth and slay your sinks, bestie 💖🦋✨

📦 where this page comes from