RFC: docs: fix: Match stated automake requirement
[babeltrace.git] / doc / man / babeltrace2-source.ctf.fs.7.txt
... / ...
CommitLineData
1= babeltrace2-source.ctf.fs(7)
2:manpagetype: component class
3:revdate: 14 September 2019
4
5
6== NAME
7
8babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
9component class
10
11
12== DESCRIPTION
13
14A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or
15more https://diamon.org/ctf/[CTF]~1.8 streams on the file system
16and emits corresponding messages.
17
18----
19CTF streams on
20the file system
21 |
22 | +---------------------+
23 | | src.ctf.fs |
24 | | |
25 '-->| ...5c847 | 0 | 0 @--> Stream 0 messages
26 | ...5c847 | 0 | 1 @--> Stream 1 messages
27 | ...5c847 | 0 | 2 @--> Stream 2 messages
28 +---------------------+
29----
30
31include::common-see-babeltrace2-intro.txt[]
32
33
34[[input]]
35=== Input
36
37A compcls:source.ctf.fs component opens a single _logical_ CTF trace. A
38logical CTF trace contains one or more _physical_ CTF traces. A physical
39CTF trace on the file system is a directory which contains:
40
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
45 `index`.
46
47If the logical CTF trace to handle contains more than one physical CTF
48trace, then all the physical CTF traces must have a trace UUID and all
49UUIDs must be the same. Opening more than one physical CTF trace to
50constitute a single logical CTF trace is needed to support LTTng's
51tracing session rotation feature, for example (see man:lttng-rotate(1)
52starting from LTTng~2.11).
53
54You specify which physical CTF traces to open and read with the
55param:inputs array parameter. Each entry in this array is the path to a
56physical CTF trace directory, that is, the directory directly containing
57the stream files.
58
59A compcls:source.ctf.fs component does not recurse into directories to
60find CTF traces. However, the component class provides the
61`babeltrace.support-info` query object which indicates whether or not a
62given directory looks like a CTF trace directory (see
63<<support-info,```babeltrace.support-info`''>>).
64
65The component creates one output port for each logical CTF data stream.
66More than one physical CTF data stream file can support a single logical
67CTF data stream (LTTng's trace file rotation and tracing session
68rotation can cause this).
69
70If two or more data stream files contain the same packets, a
71compcls:source.ctf.fs message iterator reads each of them only once so
72that it never emits duplicated messages. This feature makes it possible,
73for example, to open overlapping
74https://lttng.org/docs/#doc-taking-a-snapshot[LTTng snapshots] with a
75single compcls:source.ctf.fs component and silently discard the
76duplicated packets.
77
78
79=== Trace quirks
80
81Many tracers produce CTF traces. A compcls:source.ctf.fs component makes
82some effort to support as many CTF traces as possible, even those with
83malformed streams.
84
85Generally:
86
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.
91
92A compcls:source.ctf.fs component has special quirk handling for some
93https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces,
94depending on the tracer's version:
95
96All LTTng versions::
97+
98--
99* The component sets the `monotonic` clock class's origin to the Unix
100 epoch so that different LTTng traces are always correlatable.
101+
102This is the equivalent of setting the
103param:force-clock-class-origin-unix-epoch parameter to true.
104
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.
108+
109This is useful for the traces which man:lttng-crash(1) generates.
110--
111
112LTTng-UST up to, but excluding, 2.11.0::
113LTTng-modules up to, but excluding, 2.9.13::
114LTTng-modules from 2.10.0 to 2.10.9::
115+
116--
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.
120--
121
122barectf up to, but excluding, 2.3.1::
123+
124--
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.
128--
129
130
131== INITIALIZATION PARAMETERS
132
133param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
134 Add 'NS' nanoseconds to the offset of all the clock classes that the
135 component creates.
136+
137You can combine this parameter with the param:clock-class-offset-s
138parameter.
139
140param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
141 Add 'SEC' seconds to the offset of all the clock classes that the
142 component creates.
143+
144You can combine this parameter with the param:clock-class-offset-ns
145parameter.
146
147param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
148 Force the origin of all clock classes that the component creates to
149 have a Unix epoch origin, whatever the detected tracer.
150
151param:inputs='DIRS' vtype:[array of strings]::
152 Open and read the physical CTF traces located in 'DIRS'.
153+
154Each element of 'DIRS' is the path to a physical CTF trace directory
155containing the trace's stream files.
156+
157All the specified physical CTF traces must belong to the same logical
158CTF trace. See <<input,``Input''>> to learn more about logical and
159physical CTF traces.
160
161param:trace-name='NAME' vtype:[optional string]::
162 Set the name of the trace object that the component creates to
163 'NAME'.
164
165
166== PORTS
167
168----
169+--------------------+
170| src.ctf.fs |
171| |
172| ...5c847 | 0 | 1 @
173| ... @
174+--------------------+
175----
176
177
178=== Output
179
180A compcls:source.ctf.fs component creates one output port for each
181logical CTF data stream. See <<input,``Input''>> to learn more about
182logical and physical CTF data streams.
183
184Each output port's name has one of the following forms:
185
186[verse]
187__TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
188__TRACE-ID__ | __STREAM-ID__
189
190The component uses the second form when the stream class ID is not
191available.
192
193__TRACE-ID__::
194 Trace's UUID if available, otherwise trace's absolute directory
195 path.
196
197__STREAM-CLASS-ID__::
198 Stream class ID.
199
200__STREAM-ID__::
201 Stream ID if available, otherwise stream's absolute file path.
202
203
204[[query-objs]]
205== QUERY OBJECTS
206
207[[support-info]]
208=== `babeltrace.support-info`
209
210See man:babeltrace2-query-babeltrace.support-info(7) to learn more
211about this query object.
212
213For a directory input which is the path to a CTF trace directory,
214the result object contains:
215
216nlqres:weight::
217 0.75
218
219nlqres:group::
220 Trace's UUID if available, otherwise the entry does not exist.
221
222You can leverage this query object's nlqres:group entry to assemble many
223physical CTF traces as a single logical CTF trace (see
224<<input,``Input''>> to learn more about logical and physical CTF
225traces). This is how the man:babeltrace2-convert(1) command makes it
226possible to specify as non-option arguments the paths to multiple
227physical CTF traces which belong to the same logical CTF trace and
228create a single compcls:source.ctf.fs component.
229
230
231=== `babeltrace.trace-infos`
232
233See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
234about this query object.
235
236
237=== `metadata-info`
238
239You can query the `metadata-info` object for a specific CTF trace to get
240its plain text metadata stream as well as whether or not it is
241packetized.
242
243Parameters:
244
245nlparam:path='PATH' vtype:[string]::
246 Path to the physical CTF trace directory which contains the
247 `metadata` file.
248
249Result object (map):
250
251qres:is-packetized vtype:[boolean]::
252 True if the metadata stream file is packetized.
253
254qres:text vtype:[string]::
255 Plain text metadata stream.
256
257
258include::common-footer.txt[]
259
260
261== SEE ALSO
262
263man:babeltrace2-intro(7),
264man:babeltrace2-plugin-ctf(7),
265man:lttng-crash(1)
This page took 0.023672 seconds and 4 git commands to generate.