1BABELTRACE2-SOURCE()                                      BABELTRACE2-SOURCE()
2
3
4

NAME

6       babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
7       component class
8

DESCRIPTION

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
14           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
25       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
26       and its core concepts.
27
28   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
33       •   One metadata stream file named metadata.
34
35       •   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
38Optional: One LTTng (see <https://lttng.org/>) index directory
39           named index.
40
41       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
48       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
53       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
58       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
63       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
70   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
75       Generally:
76
77       •   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
82       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
86       All LTTng versions
87
88           •   The component sets the monotonic clock class’s origin to the
89               Unix epoch so that different LTTng traces are always
90               correlatable.
91
92               This is the equivalent of setting the force-clock-class-origin-
93               unix-epoch parameter to true.
94
95           •   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
100               This is useful for the traces which lttng-crash(1) generates.
101
102       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
105           •   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
109       barectf up to, but excluding, 2.3.1
110
111           •   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

INITIALIZATION PARAMETERS

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
120           You can combine this parameter with the clock-class-offset-s
121           parameter.
122
123       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
127           You can combine this parameter with the clock-class-offset-ns
128           parameter.
129
130       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
134       inputs=DIRS [array of strings]
135           Open and read the physical CTF traces located in DIRS.
136
137           Each element of DIRS is the path to a physical CTF trace directory
138           containing the trace’s stream files.
139
140           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
144       trace-name=NAME [optional string]
145           Set the name of the trace object that the component creates to
146           NAME.
147

PORTS

149           +--------------------+
150           |     src.ctf.fs     |
151           |                    |
152           |   ...5c847 | 0 | 1 @
153           |                ... @
154           +--------------------+
155
156   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
161       Each output port’s name has one of the following forms:
162
163           TRACE-ID | STREAM-CLASS-ID | STREAM-ID
164           TRACE-ID | STREAM-ID
165
166       The component uses the second form when the stream class ID is not
167       available.
168
169       TRACE-ID
170           Trace’s UUID if available, otherwise trace’s absolute directory
171           path.
172
173       STREAM-CLASS-ID
174           Stream class ID.
175
176       STREAM-ID
177           Stream ID if available, otherwise stream’s absolute file path.
178

QUERY OBJECTS

180   babeltrace.support-info
181       See babeltrace2-query-babeltrace.support-info(7) to learn more about
182       this query object.
183
184       For a directory input which is the path to a CTF trace directory, the
185       result object contains:
186
187       weight
188           0.75
189
190       group
191           Trace’s UUID if available, otherwise the entry does not exist.
192
193       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
201   babeltrace.trace-infos
202       See babeltrace2-query-babeltrace.trace-infos(7) to learn more about
203       this query object.
204
205   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
210       Parameters:
211
212       path=PATH [string]
213           Path to the physical CTF trace directory which contains the
214           metadata file.
215
216       Result object (map):
217
218       is-packetized [boolean]
219           True if the metadata stream file is packetized.
220
221       text [string]
222           Plain text metadata stream.
223

BUGS

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

RESOURCES

230       The Babeltrace project shares some communication channels with the
231       LTTng project (see <https://lttng.org/>).
232
233       •   Babeltrace website (see <https://babeltrace.org/>)
234
235       •   Mailing list (see <https://lists.lttng.org>) for support and
236           development: lttng-dev@lists.lttng.org
237
238       •   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
239           irc.oftc.net
240
241       •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
242
243       •   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
244
245       •   GitHub project (see <https://github.com/efficios/babeltrace>)
246
247       •   Continuous integration (see
248           <https://ci.lttng.org/view/Babeltrace/>)
249
250       •   Code review (see <https://review.lttng.org/q/project:babeltrace>)
251

AUTHORS

253       The Babeltrace 2 project is the result of hard work by many regular
254       developers and occasional contributors.
255
256       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
262       Babeltrace is distributed under the MIT license (see
263       <https://opensource.org/licenses/MIT>).
264

SEE ALSO

266       babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-crash(1)
267
268
269
270                                                          BABELTRACE2-SOURCE()
Impressum