1 = babeltrace2-source.ctf.fs(7)
2 :manpagetype: component class
3 :revdate: 1 September 2023
8 babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
14 A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or
15 more https://diamon.org/ctf/[CTF]~1.8 streams on the file system
16 and emits corresponding messages.
22 | +---------------------+
25 '-->| ...5c847 | 0 | 0 @--> Stream 0 messages
26 | ...5c847 | 0 | 1 @--> Stream 1 messages
27 | ...5c847 | 0 | 2 @--> Stream 2 messages
28 +---------------------+
31 include::common-see-babeltrace2-intro.txt[]
37 A compcls:source.ctf.fs component opens a single _logical_ CTF trace. A
38 logical CTF trace contains one or more _physical_ CTF traces. A physical
39 CTF trace on the file system is a directory which contains:
41 * One metadata stream file named `metadata`.
42 * One or more data stream files, that is, any file with a name that does
43 not start with `.` and which is not `metadata`.
44 * **Optional**: One https://lttng.org/[LTTng] index directory named
47 If the logical CTF trace to handle contains more than one physical CTF
48 trace, then all the physical CTF traces must have a trace UUID and all
49 UUIDs must be the same. Opening more than one physical CTF trace to
50 constitute a single logical CTF trace is needed to support LTTng's
51 tracing session rotation feature, for example (see man:lttng-rotate(1)
52 starting from LTTng~2.11).
54 You specify which physical CTF traces to open and read with the
55 param:inputs array parameter. Each entry in this array is the path to a
56 physical CTF trace directory, that is, the directory directly containing
59 A compcls:source.ctf.fs component does not recurse into directories to
60 find CTF traces. However, the component class provides the
61 `babeltrace.support-info` query object which indicates whether or not a
62 given directory looks like a CTF trace directory (see
63 <<support-info,```babeltrace.support-info`''>>).
65 The component creates one output port for each logical CTF data stream.
66 More than one physical CTF data stream file can support a single logical
67 CTF data stream (LTTng's trace file rotation and tracing session
68 rotation can cause this).
70 If two or more data stream files contain the same packets, a
71 compcls:source.ctf.fs message iterator reads each of them only once so
72 that it never emits duplicated messages. This feature makes it possible,
73 for example, to open overlapping
74 https://lttng.org/docs/#doc-taking-a-snapshot[LTTng snapshots] with a
75 single compcls:source.ctf.fs component and silently discard the
81 Many tracers produce CTF traces. A compcls:source.ctf.fs component makes
82 some effort to support as many CTF traces as possible, even those with
87 * If the `timestamp_begin` or `timestamp_end` packet context field class
88 exists, but it is not mapped to a clock class, and there's only one
89 clock class at this point in the metadata stream, the component maps
90 the field class to this unique clock class.
92 A compcls:source.ctf.fs component has special quirk handling for some
93 https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces,
94 depending on the tracer's version:
99 * The component sets the `monotonic` clock class's origin to the Unix
100 epoch so that different LTTng traces are always correlatable.
102 This is the equivalent of setting the
103 param:force-clock-class-origin-unix-epoch parameter to true.
105 * For a given data stream, for all the contiguous last packets of which
106 the `timestamp_end` context field is 0, the message iterator uses the
107 packet's last event record's time as the packet end message's time.
109 This is useful for the traces which man:lttng-crash(1) generates.
112 LTTng-UST up to, but excluding, 2.11.0::
113 LTTng-modules up to, but excluding, 2.9.13::
114 LTTng-modules from 2.10.0 to 2.10.9::
117 * For a given packet, the message iterator uses the packet's last
118 event record's time as the packet end message's time, ignoring the
119 packet context's `timestamp_end` field.
122 barectf up to, but excluding, 2.3.1::
125 * For a given packet, the message iterator uses the packet's first event
126 record's time as the packet beginning message's time, ignoring the
127 packet context's `timestamp_begin` field.
133 A compcls:source.ctf.fs component decodes traces as per
134 https://diamon.org/ctf/v1.8.3/[CTF~1.8.3], except:
136 * It only supports integer field classes (TSDL `integer` block) with
139 * It only supports 32-bit and 64-bit floating point number classes (TSDL
140 `floating_point` block).
142 * It doesn't support ยง~4.1.6 (``GNU/C bitfields'').
144 * It doesn't support TSDL `callsite` blocks: the parser simply ignores
147 * It only supports a single clock class (TSDL `clock` block) reference
148 per stream class (TSDL `stream` block).
150 * It doesn't support the checksum, compression, and encryption features
151 of metadata stream packets.
154 == INITIALIZATION PARAMETERS
156 param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
157 Add 'NS' nanoseconds to the offset of all the clock classes that the
160 You can combine this parameter with the param:clock-class-offset-s
163 param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
164 Add 'SEC' seconds to the offset of all the clock classes that the
167 You can combine this parameter with the param:clock-class-offset-ns
170 param:force-clock-class-origin-unix-epoch='VAL' vtype:[optional boolean]::
171 If 'VAL' is true, then force the origin of all clock classes that
172 the component creates to have a Unix epoch origin, whatever the
177 param:inputs='DIRS' vtype:[array of strings]::
178 Open and read the physical CTF traces located in 'DIRS'.
180 Each element of 'DIRS' is the path to a physical CTF trace directory
181 containing the trace's stream files.
183 All the specified physical CTF traces must belong to the same logical
184 CTF trace. See <<input,``Input''>> to learn more about logical and
187 param:trace-name='NAME' vtype:[optional string]::
188 Set the name of the trace object that the component creates to
195 +--------------------+
200 +--------------------+
206 A compcls:source.ctf.fs component creates one output port for each
207 logical CTF data stream. See <<input,``Input''>> to learn more about
208 logical and physical CTF data streams.
210 Each output port's name has one of the following forms:
213 __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
214 __TRACE-ID__ | __STREAM-ID__
216 The component uses the second form when the stream class ID is not
220 Trace's UUID if available, otherwise trace's absolute directory
223 __STREAM-CLASS-ID__::
227 Stream ID if available, otherwise stream's absolute file path.
234 === `babeltrace.support-info`
236 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
237 about this query object.
239 For a directory input which is the path to a CTF trace directory,
240 the result object contains:
246 Trace's UUID if available, otherwise the entry does not exist.
248 You can leverage this query object's nlqres:group entry to assemble many
249 physical CTF traces as a single logical CTF trace (see
250 <<input,``Input''>> to learn more about logical and physical CTF
251 traces). This is how the man:babeltrace2-convert(1) command makes it
252 possible to specify as non-option arguments the paths to multiple
253 physical CTF traces which belong to the same logical CTF trace and
254 create a single compcls:source.ctf.fs component.
257 === `babeltrace.trace-infos`
259 See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
260 about this query object.
265 You can query the `metadata-info` object for a specific CTF trace to get
266 its plain text metadata stream as well as whether or not it is
271 nlparam:path='PATH' vtype:[string]::
272 Path to the physical CTF trace directory which contains the
277 qres:is-packetized vtype:[boolean]::
278 True if the metadata stream file is packetized.
280 qres:text vtype:[string]::
281 Plain text metadata stream.
284 include::common-footer.txt[]
289 man:babeltrace2-intro(7),
290 man:babeltrace2-plugin-ctf(7),