1BABELTRACE2-SOURCE() BABELTRACE2-SOURCE()
2
6 babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
7 component class
8
10 A Babeltrace 2 source.ctf.fs message iterator reads one or more CTF
11 (see <https://diamon.org/ctf/>) 1.8 streams on the file system and
12 emits corresponding messages.
13 CTF streams on
15 the file system
16 |
17 | +---------------------+
18 | | src.ctf.fs |
19 | | |
20 '-->| ...5c847 | 0 | 0 @--> Stream 0 messages
21 | ...5c847 | 0 | 1 @--> Stream 1 messages
22 | ...5c847 | 0 | 2 @--> Stream 2 messages
23 +---------------------+
24 See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
26 and its core concepts.
27 Input
29 A source.ctf.fs component opens a single logical CTF trace. A logical
30 CTF trace contains one or more physical CTF traces. A physical CTF
31 trace on the file system is a directory which contains:
32 • One metadata stream file named metadata.
34 • One or more data stream files, that is, any file with a name that
36 does not start with . and which is not metadata.
37 • Optional: One LTTng (see <https://lttng.org/>) index directory
39 named index.
40 If the logical CTF trace to handle contains more than one physical CTF
42 trace, then all the physical CTF traces must have a trace UUID and all
43 UUIDs must be the same. Opening more than one physical CTF trace to
44 constitute a single logical CTF trace is needed to support LTTng’s
45 tracing session rotation feature, for example (see lttng-rotate(1)
46 starting from LTTng 2.11).
47 You specify which physical CTF traces to open and read with the inputs
49 array parameter. Each entry in this array is the path to a physical CTF
50 trace directory, that is, the directory directly containing the stream
51 files.
52 A source.ctf.fs component does not recurse into directories to find CTF
54 traces. However, the component class provides the babeltrace.support-
55 info query object which indicates whether or not a given directory
56 looks like a CTF trace directory (see “babeltrace.support-info”).
57 The component creates one output port for each logical CTF data stream.
59 More than one physical CTF data stream file can support a single
60 logical CTF data stream (LTTng’s trace file rotation and tracing
61 session rotation can cause this).
62 If two or more data stream files contain the same packets, a
64 source.ctf.fs message iterator reads each of them only once so that it
65 never emits duplicated messages. This feature makes it possible, for
66 example, to open overlapping LTTng snapshots (see
67 <https://lttng.org/docs/#doc-taking-a-snapshot>) with a single
68 source.ctf.fs component and silently discard the duplicated packets.
69 Trace quirks
71 Many tracers produce CTF traces. A source.ctf.fs component makes some
72 effort to support as many CTF traces as possible, even those with
73 malformed streams.
74 Generally:
76 • If the timestamp_begin or timestamp_end packet context field class
78 exists, but it is not mapped to a clock class, and there’s only one
79 clock class at this point in the metadata stream, the component
80 maps the field class to this unique clock class.
81 A source.ctf.fs component has special quirk handling for some LTTng
83 (see <https://lttng.org/>) and barectf (see <https://lttng.org/>)
84 traces, depending on the tracer’s version:
85 All LTTng versions
87 • The component sets the monotonic clock class’s origin to the
89 Unix epoch so that different LTTng traces are always
90 correlatable.
91 This is the equivalent of setting the force-clock-class-origin-
93 unix-epoch parameter to true.
94 • For a given data stream, for all the contiguous last packets of
96 which the timestamp_end context field is 0, the message
97 iterator uses the packet’s last event record’s time as the
98 packet end message’s time.
99 This is useful for the traces which lttng-crash(1) generates.
101 LTTng-UST up to, but excluding, 2.11.0, LTTng-modules up to, but
103 excluding, 2.9.13, LTTng-modules from 2.10.0 to 2.10.9
104 • For a given packet, the message iterator uses the packet’s last
106 event record’s time as the packet end message’s time, ignoring
107 the packet context’s timestamp_end field.
108 barectf up to, but excluding, 2.3.1
110 • For a given packet, the message iterator uses the packet’s
112 first event record’s time as the packet beginning message’s
113 time, ignoring the packet context’s timestamp_begin field.
114
116 clock-class-offset-ns=NS [optional signed integer]
117 Add NS nanoseconds to the offset of all the clock classes that the
118 component creates.
119 You can combine this parameter with the clock-class-offset-s
121 parameter.
122 clock-class-offset-s=SEC [optional signed integer]
124 Add SEC seconds to the offset of all the clock classes that the
125 component creates.
126 You can combine this parameter with the clock-class-offset-ns
128 parameter.
129 force-clock-class-origin-unix-epoch=yes [optional boolean]
131 Force the origin of all clock classes that the component creates to
132 have a Unix epoch origin, whatever the detected tracer.
133 inputs=DIRS [array of strings]
135 Open and read the physical CTF traces located in DIRS.
136 Each element of DIRS is the path to a physical CTF trace directory
138 containing the trace’s stream files.
139 All the specified physical CTF traces must belong to the same
141 logical CTF trace. See “Input” to learn more about logical and
142 physical CTF traces.
143 trace-name=NAME [optional string]
145 Set the name of the trace object that the component creates to
146 NAME.
147
149 +--------------------+
150 | src.ctf.fs |
151 | |
152 | ...5c847 | 0 | 1 @
153 | ... @
154 +--------------------+
155 Output
157 A source.ctf.fs component creates one output port for each logical CTF
158 data stream. See “Input” to learn more about logical and physical CTF
159 data streams.
160 Each output port’s name has one of the following forms:
162 TRACE-ID | STREAM-CLASS-ID | STREAM-ID
164 TRACE-ID | STREAM-ID
165 The component uses the second form when the stream class ID is not
167 available.
168 TRACE-ID
170 Trace’s UUID if available, otherwise trace’s absolute directory
171 path.
172 STREAM-CLASS-ID
174 Stream class ID.
175 STREAM-ID
177 Stream ID if available, otherwise stream’s absolute file path.
178
180 babeltrace.support-info
181 See babeltrace2-query-babeltrace.support-info(7) to learn more about
182 this query object.
183 For a directory input which is the path to a CTF trace directory, the
185 result object contains:
186 weight
188 0.75
189 group
191 Trace’s UUID if available, otherwise the entry does not exist.
192 You can leverage this query object’s group entry to assemble many
194 physical CTF traces as a single logical CTF trace (see “Input” to learn
195 more about logical and physical CTF traces). This is how the
196 babeltrace2-convert(1) command makes it possible to specify as
197 non-option arguments the paths to multiple physical CTF traces which
198 belong to the same logical CTF trace and create a single source.ctf.fs
199 component.
200 babeltrace.trace-infos
202 See babeltrace2-query-babeltrace.trace-infos(7) to learn more about
203 this query object.
204 metadata-info
206 You can query the metadata-info object for a specific CTF trace to get
207 its plain text metadata stream as well as whether or not it is
208 packetized.
209 Parameters:
211 path=PATH [string]
213 Path to the physical CTF trace directory which contains the
214 metadata file.
215 Result object (map):
217 is-packetized [boolean]
219 True if the metadata stream file is packetized.
220 text [string]
222 Plain text metadata stream.
223
225 If you encounter any issue or usability problem, please report it on
226 the Babeltrace bug tracker (see
227 <https://bugs.lttng.org/projects/babeltrace>).
228
230 The Babeltrace project shares some communication channels with the
231 LTTng project (see <https://lttng.org/>).
232 • Babeltrace website (see <https://babeltrace.org/>)
234 • Mailing list (see <https://lists.lttng.org>) for support and
236 development: lttng-dev@lists.lttng.org
237 • IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
239 irc.oftc.net
240 • Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
242 • Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
244 • GitHub project (see <https://github.com/efficios/babeltrace>)
246 • Continuous integration (see
248 <https://ci.lttng.org/view/Babeltrace/>)
249 • Code review (see <https://review.lttng.org/q/project:babeltrace>)
251
253 The Babeltrace 2 project is the result of hard work by many regular
254 developers and occasional contributors.
255 The current project maintainer is Jérémie Galarneau
257 <mailto:jeremie.galarneau@efficios.com>.
258
260 This component class is part of the Babeltrace 2 project.
261 Babeltrace is distributed under the MIT license (see
263 <https://opensource.org/licenses/MIT>).
264
266 babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-crash(1)
267 BABELTRACE2-SOURCE()