babeltrace2-source.ctf.fs — Babeltrace 2's file system CTF source component class
A Babeltrace 2 source.ctf.fs message iterator reads one or more CTF 1.8 streams on the file system and emits corresponding messages.
CTF 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.
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
One or more data stream files, that is, any file with a name that does not start with
.and which is not
Optional: One LTTng index directory named
If the logical CTF trace to handle contains more than one physical CTF trace, then all the physical CTF traces must have a trace UUID and all UUIDs 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).
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 does not 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
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, 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 with a single source.ctf.fs component and silently discard the duplicated packets.
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.
timestamp_endpacket context field class exists, but it is not mapped to a clock class, and there’s only one clock class at this point in the metadata stream, the component maps the field class to this unique clock class.
- All LTTng versions
The component sets the
monotonicclock class’s origin to the Unix epoch so that different LTTng traces are always correlatable.
This is the equivalent of setting the
force-clock-class-origin-unix-epochparameter to true.
For a given data stream, for all the contiguous last packets of which the
timestamp_endcontext field is 0, the message iterator uses the packet’s last event record’s time as the packet end message’s time.
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 packet’s last event record’s time as the packet end message’s time, ignoring the packet context’s
- barectf up to, but excluding, 2.3.1
For a given packet, the message iterator uses the packet’s first event record’s time as the packet beginning message’s time, ignoring the packet context’s
NS[optional signed integer]
NSnanoseconds to the offset of all the clock classes that the component creates.
You can combine this parameter with the
SEC[optional signed integer]
SECseconds to the offset of all the clock classes that the component creates.
You can combine this parameter with the
Force the origin of all clock classes that the component creates to have a Unix epoch origin, whatever the detected tracer.
DIRS[array of strings]
Open and read the physical CTF traces located in
Each element of
DIRSis the path to a physical CTF trace directory containing the trace’s 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.
Set the name of the trace object that the component creates to
+--------------------+ | src.ctf.fs | | | | ...5c847 | 0 | 1 @ | ... @ +--------------------+
A source.ctf.fs component creates one output port for each logical CTF data stream. See Input to learn more about logical and physical CTF data streams.
Each output port’s name has one of the following forms:
The component uses the second form when the stream class ID is not available.
Trace’s UUID if available, otherwise trace’s absolute directory path.
Stream class ID.
Stream ID if available, otherwise stream’s absolute file path.
See babeltrace2-query-babeltrace.support-info(7) to learn more about this query object.
For a directory input which is the path to a CTF trace directory, the result object contains:
Trace’s UUID if available, otherwise the entry does not exist.
You can leverage this query object’s
group entry to assemble many
physical CTF traces as a single logical CTF trace (see
Input to learn more about logical and physical CTF
traces). This is how the babeltrace2-convert(1) command makes it
possible to specify as non-option arguments the paths to multiple
physical CTF traces which belong to the same logical CTF trace and
create a single source.ctf.fs component.
See babeltrace2-query-babeltrace.trace-infos(7) to learn more about this query object.
You can query the
metadata-info object for a specific CTF trace to get
its plain text metadata stream as well as whether or not it is
Path to the physical CTF trace directory which contains the
Result object (map):
True if the metadata stream file is packetized.
Plain text metadata stream.