= babeltrace2-source.ctf.fs(7) :manpagetype: component class :revdate: 14 September 2019 == NAME babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source component class == DESCRIPTION A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or more https://diamon.org/ctf/[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 +---------------------+ ---- include::common-see-babeltrace2-intro.txt[] [[input]] === Input A compcls: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 is not `metadata`. * **Optional**: One https://lttng.org/[LTTng] index directory named `index`. 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 man:lttng-rotate(1) starting from LTTng~2.11). You specify which physical CTF traces to open and read with the param: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 compcls: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 compcls: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 https://lttng.org/docs/#doc-taking-a-snapshot[LTTng snapshots] with a single compcls:source.ctf.fs component and silently discard the duplicated packets. === Trace quirks Many tracers produce CTF traces. A compcls:source.ctf.fs component makes some effort to support as many CTF traces as possible, even those with malformed streams. Generally: * If the `timestamp_begin` or `timestamp_end` packet 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. A compcls:source.ctf.fs component has special quirk handling for some https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces, depending on the tracer's version: All LTTng versions:: + -- * The component sets the `monotonic` clock class's origin to the Unix epoch so that different LTTng traces are always correlatable. + This is the equivalent of setting the param: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 packet's last event record's time as the packet end message's time. + This is useful for the traces which man: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 `timestamp_end` field. -- 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 `timestamp_begin` field. -- === CTF compliance A compcls:source.ctf.fs component decodes traces as per https://diamon.org/ctf/v1.8.3/[CTF~1.8.3], except: * It only supports integer field classes (TSDL `integer` block) with sizes from 1 to 64. * It only supports 32-bit and 64-bit floating point number classes (TSDL `floating_point` block). * It doesn't support ยง~4.1.6 (``GNU/C bitfields''). * It doesn't support TSDL `callsite` blocks: the parser simply ignores them. * It only supports a single clock class (TSDL `clock` block) reference per stream class (TSDL `stream` block). * It doesn't support the checksum, compression, and encryption features of metadata stream packets. == INITIALIZATION PARAMETERS param:clock-class-offset-ns='NS' vtype:[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 param:clock-class-offset-s parameter. param:clock-class-offset-s='SEC' vtype:[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 param:clock-class-offset-ns parameter. param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]:: Force the origin of all clock classes that the component creates to have a Unix epoch origin, whatever the detected tracer. param:inputs='DIRS' vtype:[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's stream files. + All the specified physical CTF traces must belong to the same logical CTF trace. See <> to learn more about logical and physical CTF traces. param:trace-name='NAME' vtype:[optional string]:: Set the name of the trace object that the component creates to 'NAME'. == PORTS ---- +--------------------+ | src.ctf.fs | | | | ...5c847 | 0 | 1 @ | ... @ +--------------------+ ---- === Output A compcls:source.ctf.fs component creates one output port for each logical CTF data stream. See <> to learn more about logical and physical CTF data streams. Each output port's name has one of the following forms: [verse] __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__ __TRACE-ID__ | __STREAM-ID__ The component uses the second form when the stream class ID is not available. __TRACE-ID__:: Trace's UUID if available, otherwise trace's absolute directory path. __STREAM-CLASS-ID__:: Stream class ID. __STREAM-ID__:: Stream ID if available, otherwise stream's absolute file path. [[query-objs]] == QUERY OBJECTS [[support-info]] === `babeltrace.support-info` See man: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: nlqres:weight:: 0.75 nlqres:group:: Trace's UUID if available, otherwise the entry does not exist. You can leverage this query object's nlqres:group entry to assemble many physical CTF traces as a single logical CTF trace (see <> to learn more about logical and physical CTF traces). This is how the man: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 compcls:source.ctf.fs component. === `babeltrace.trace-infos` See man: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 as well as whether or not it is packetized. Parameters: nlparam:path='PATH' vtype:[string]:: Path to the physical CTF trace directory which contains the `metadata` file. Result object (map): qres:is-packetized vtype:[boolean]:: True if the metadata stream file is packetized. qres:text vtype:[string]:: Plain text metadata stream. include::common-footer.txt[] == SEE ALSO man:babeltrace2-intro(7), man:babeltrace2-plugin-ctf(7), man:lttng-crash(1)