BABELTRACE2-SOURCE.CTF.FS(7)

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

🌈 babeltrace2-source.ctf.fs(7) 🌈

bestie, welcome to the manual page for the Babeltrace 2 file system CTF source component class 💖 this is part 1, and it is long, so buckle up 🎀

💅 NAME 💅

  • babeltrace2-source.ctf.fs — Babeltrace 2: File system CTF source component class ✨

🦋 DESCRIPTION 🦋

okay so a Babeltrace 2 source.ctf.fs message iterator reads one or more CTF 1.8 (see <https://diamon.org/ctf/v1.8.3/>) or CTF 2 (see <https://diamon.org/ctf/>) data streams on the file system and emits corresponding messages. that's the whole vibe 🫶

CTF data streams on
the file system
  |
  |   +---------------------+
  |   |      src.ctf.fs     |
  |   |                     |
  '-->|    ...5c847 | 0 | 0 @--> Stream 0 messages
      |    ...5c847 | 0 | 1 @--> Stream 1 messages
      |    ...5c847 | 0 | 2 @--> Stream 2 messages
      +---------------------+

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

✨ Input ✨

a source.ctf.fs component opens a single logical CTF trace. a logical CTF trace contains one or more physical CTF traces. a physical CTF trace on the file system is a directory which contains:

  • One metadata stream file named metadata 📄
  • One or more data stream files, that is, any file with a name that does not start with . and which isn’t metadata 🌊
  • Optional: One LTTng (see <https://lttng.org/>) index directory named index 📇

if the logical CTF trace to handle contains more than one physical CTF trace, then all the physical CTF traces, depending on the CTF version:

  • CTF 1.8 — Must have a trace UUID and all UUIDs must be the same 🆔
  • CTF 2 — Must have a trace name and a trace unique ID (UID), and all trace namespaces (if any), names, and UIDs must be the same 🪪

opening more than one physical CTF trace to constitute a single logical CTF trace is needed to support LTTng’s tracing session rotation feature, for example (see lttng-rotate(1) starting from LTTng 2.11) 🔄 in that case, the component elects the largest metadata stream, considering the total count of data stream classes and event record classes, as the one to use to decode the data streams of all the physical traces 👑

you specify which physical CTF traces to open and read with the inputs array parameter. each entry in this array is the path to a physical CTF trace directory, that is, the directory directly containing the stream files 📁

a source.ctf.fs component doesn’t recurse into directories to find CTF traces. however, the component class provides the babeltrace.support-info query object which indicates whether or not a given directory looks like a CTF trace directory (see “babeltrace.support-info”) 🔍

the component creates one output port for each logical CTF data stream. more than one physical CTF data stream file can support a single logical CTF data stream (LTTng’s trace file rotation and tracing session rotation can cause this) 🌀

if two or more data stream files contain the same packets, then a source.ctf.fs message iterator reads each of them only once so that it never emits duplicated messages. this feature makes it possible, for example, to open overlapping LTTng snapshots (see <https://lttng.org/docs/#doc-taking-a-snapshot>) with a single source.ctf.fs component and silently discard the duplicated packets 🙈

🌸 Trace quirks 🌸

many tracers produce CTF traces. a source.ctf.fs component makes some effort to support as many CTF traces as possible, even those with malformed streams 💪

in general, for a CTF 1.8 trace:

  • If the timestamp_begin or timestamp_end packet context field class exists, but it’s not mapped to a clock class, and there’s only one clock class at this point in the metadata stream, then the component maps the field class to this unique clock class ⏰

a source.ctf.fs component has special quirk handling for some LTTng (see <https://lttng.org/>) and barectf (see <https://lttng.org/>) traces, depending on the tracer version:

All LTTng versions

  • For CTF 1.8 traces, the component sets the origin of the monotonic clock class to the Unix epoch so that different LTTng traces are always correlatable 🌍 This is the equivalent of setting the force-clock-class-origin-unix-epoch parameter to true.
  • For a given data stream, for all the contiguous last packets of which the timestamp_end context field is 0, the message iterator uses the time of the last event record of the packet as the time of the packet end message ⏱️ This is useful for the traces which lttng-crash(1) generates.

LTTng-UST up to, but excluding, 2.11.0, LTTng-modules up to, but excluding, 2.9.13, LTTng-modules from 2.10.0 to 2.10.9

  • For a given packet, the message iterator uses the time of the last event record of the packet as the time of the packet end message, ignoring the timestamp_end packet context field 🕰️

barectf up to, but excluding, 2.3.1

  • For a given packet, the message iterator uses the time of the first event record of the packet as the time of the packet beginning message, ignoring the timestamp_begin packet context field ⏳

🧠 Message Interchange Protocol (MIP) specifics 🧠

a source.ctf.fs component can open and decode, depending on the effective MIP version:

  • MIP 0 — CTF 1.8 traces.
  • MIP 1 — CTF 1.8 and CTF 2 traces.

while the CTF 1.8 metadata stream (TSDL) features naturally map to the MIP 0 API and the CTF 2 ones to the MIP 1 API, a source.ctf.fs component makes a best effort to represent CTF 1.8 features when working with MIP 1. in particular, a source.ctf.fs component:

  • For an LTTng trace:
    • Sets the namespace of any libbabeltrace2 trace to lttng.org,2009.
    • Sets the origin of any libbabeltrace2 clock class to the Unix epoch.
  • If the UUID of a CTF trace is available, then sets the UID of the corresponding libbabeltrace2 trace to the textual representation of the trace UUID and its name to an empty string.
  • Sets the UID of a libbabeltrace2 clock class to the textual representation of the UUID of its corresponding CTF clock class, if available.
  • Makes the accuracy of any libbabeltrace2 clock class unknown.

when reading a CTF 2 metadata stream (therefore working with MIP 1), a source.ctf.fs component:

  • Sets the log level of a libbabeltrace2 event class from the value of the log-level attribute, under either the lttng.org,2009 or babeltrace.org,2020 namespace, of its corresponding CTF event record class as such:
    • "emergency" → BT_EVENT_CLASS_LOG_LEVEL_EMERGENCY
    • "alert" → BT_EVENT_CLASS_LOG_LEVEL_ALERT
    • "critical" → BT_EVENT_CLASS_LOG_LEVEL_CRITICAL
    • "error" → BT_EVENT_CLASS_LOG_LEVEL_ERROR
    • "warning" → BT_EVENT_CLASS_LOG_LEVEL_WARNING
    • "notice" → BT_EVENT_CLASS_LOG_LEVEL_NOTICE
    • "info" → BT_EVENT_CLASS_LOG_LEVEL_INFO
    • "debug:system" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_SYSTEM
    • "debug:program" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROGRAM
    • "debug:process" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_PROCESS
    • "debug:module" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_MODULE
    • "debug:unit" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_UNIT
    • "debug:function" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_FUNCTION
    • "debug:line" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG_LINE
    • "debug:debug" → BT_EVENT_CLASS_LOG_LEVEL_DEBUG
  • Sets the EMF URI of a libbabeltrace2 event class from the value of the emf-uri attribute, under either the lttng.org,2009 or babeltrace.org,2020 namespace, of its corresponding CTF event record class.

🎀 CTF compliance 🎀

a source.ctf.fs component decodes traces as per CTF 1.8 (see <https://diamon.org/ctf/v1.8.3/>) or CTF 2 (see <https://diamon.org/ctf/>), except:

  • It only supports fixed-length bit array field classes with sizes from 1 to 64 bits. This includes fixed-length integers and fixed-length floating point numbers:
    • CTF 1.8 (TSDL) — integer, enum, and floating_point blocks.
    • CTF 2 — fixed-length-bit-array, fixed-length-bit-map, fixed-length-boolean, fixed-length-unsigned-integer, fixed-length-signed-integer, and fixed-length-floating-point-number types.
  • It only supports the following CTF 2 variable-length integer field values:
    • variable-length-unsigned-integer — 0 to 18,446,744,073,709,551,615 (unsigned 64-bit integer range).
    • variable-length-signed-integer — -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 (signed 64-bit integer range).
  • It only supports 32-bit and 64-bit fixed-length floating point number classes:
    • CTF 1.8 (TSDL) — floating_point block.
    • CTF 2 — fixed-length-floating-point-number type.
  • It doesn’t support TSDL § 4.1.6 (“GNU/C bitfields”).
  • It doesn’t support TSDL callsite blocks: the CTF 1.8 parser simply ignores them.
  • It only supports a single clock class (TSDL clock block or CTF 2 clock-class fragment) reference per data stream class (TSDL stream block or CTF 2 data-stream-class fragment).
  • It doesn’t support the checksum, compression, and encryption features of CTF 1.8 metadata stream packets.

👑 INITIALIZATION PARAMETERS 👑

  • clock-class-offset-ns=NS [optional signed integer] — Add NS nanoseconds to the offset of all the clock classes that the component creates ⏲️ You can combine this parameter with the clock-class-offset-s parameter.
  • clock-class-offset-s=SEC [optional signed integer] — Add SEC seconds to the offset of all the clock classes that the component creates ⏱️ You can combine this parameter with the clock-class-offset-ns parameter.
  • force-clock-class-origin-unix-epoch=VAL [optional boolean] — If VAL is true, then force the origin of all clock classes that the component creates to have a Unix epoch origin, whatever the detected tracer 🌍 Default: false.
  • inputs=DIRS [array of strings] — Open and read the physical CTF traces located in DIRS 📂 Each element of DIRS is the path to a physical CTF trace directory containing the trace stream files. All the specified physical CTF traces must belong to the same logical CTF trace. See “Input” to learn more about logical and physical CTF traces.
  • trace-name=NAME [optional string] — Set the name of the trace object that the component creates to NAME 🏷️

🦋 PORTS 🦋

okay so picture the whole component as this lil diagram and everything clicks:

           +--------------------+
           |     src.ctf.fs     |
           |                    |
           |   ...5c847 | 0 | 1 @
           |                ... @
           +--------------------+

Output

One output port per logical CTF data stream. That's the whole rule. If you're sitting there like "bestie what is a logical CTF data stream vs a physical one", scroll on up to "Input" — it's all explained there. 💖

Every output port name comes in one of these two shapes:

TRACE-ID | STREAM-CLASS-ID | STREAM-ID
TRACE-ID | STREAM-ID

The component picks the second form whenever the stream class ID just isn't there to be had. it adapts, it's flexible, we love that for it. 💅

TRACE-ID

If the namespace NS, the name NAME, and the UID UID of the trace are all available, you get this exact string, no cap:

{namespace: `NS`, name: `NAME`, uid: `UID`}

If the namespace of the trace isn't available, but the name NAME and the UID UID are, then it's this exact string instead:

{name: `NAME`, uid: `UID`}

And otherwise? You get the absolute directory path of the trace. That's the fallback, that's the vibe. 🫶

Note — The namespace of any LTTng trace is lttng.org,2009. And if a CTF 1.8 trace has a UUID, then its corresponding libbabeltrace2 trace always has a name and a UID (the textual representation of the UUID). always. every time. 🔥

STREAM-CLASS-ID

Stream class ID. Yeah. That's the entire description, she's lowkey mysterious like that. 🎀

STREAM-ID

The stream ID if it's available — and otherwise, the absolute file path of the stream. 🌸

🔍 QUERY OBJECTS 🔍

babeltrace.support-info

Go read babeltrace2-query-babeltrace.support-info(7) if you want the full tea on this query object. ☕

For a directory input which is the path to a CTF trace directory, the result object contains:

  • weight — 0.75
  • group — if the namespace NS, the name NAME, and the UID UID of the trace are available, then this exact string:
namespace: NS, name: NAME, uid: UID

If the namespace of the trace isn't available, but the name NAME and the UID UID are, then this exact string:

name: NAME, uid: UID

Otherwise, the entry doesn't exist. gone. not there. 💀

Note — The namespace of any LTTng trace is lttng.org,2009. And if a CTF 1.8 trace has a UUID, then its corresponding libbabeltrace2 trace always has a name and a UID (the textual representation of the UUID).

You can absolutely leverage the group entry of this query object to assemble a whole bunch of physical CTF traces into a single logical CTF trace (again, "Input" up top has the logical vs physical lore). This is exactly how the babeltrace2-convert(1) command pulls off letting you pass, as non-option arguments, the paths to multiple physical CTF traces that belong to the same logical CTF trace — and end up with a single source.ctf.fs component. iconic behavior honestly. 👑

babeltrace.trace-infos

Go read babeltrace2-query-babeltrace.trace-infos(7) to learn more about this query object. 🦋

metadata-info

You can query the metadata-info object for a specific CTF trace to get its plain text metadata stream, plus whether or not it's packetized. two-for-one. 🍓

Parameters:

  • path=PATH [string] — Path to the physical CTF trace directory which contains the metadata file.

Result object (map):

  • is-packetized [boolean] — True if the metadata stream file is packetized. This is only relevant for a CTF 1.8 metadata stream. It's always false with a CTF 2 metadata stream.
  • text [string] — Plain text metadata stream. The exact contents of the metadata stream file for a CTF 2 metadata stream.

🐛 BUGS 🐛

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

💜 RESOURCES 💜

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

✨ AUTHORS ✨

The Babeltrace 2 project is the result of hard work by many regular developers and occasional contributors. shoutout to every single one of them, genuinely. 🫶

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

🌈 SEE ALSO 🌈

babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-crash(1)

and that's the whole page, bestie, you made it to the end 💖 the footer down there just reads BABELTRACE2-SOURCE() for the source/version — the date slot is sitting there empty, which honestly is such a main character move. go forth and trace some streams. 👑✨

📦 where this page comes from