Commit | Line | Data |
---|---|---|
e70712b3 | 1 | = babeltrace2-source.ctf.fs(7) |
0659f3af | 2 | :manpagetype: component class |
e70712b3 | 3 | :revdate: 14 September 2019 |
0659f3af PP |
4 | |
5 | ||
e70712b3 PP |
6 | == NAME |
7 | ||
8 | babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source | |
0659f3af PP |
9 | component class |
10 | ||
11 | ||
e70712b3 | 12 | == DESCRIPTION |
0659f3af | 13 | |
e70712b3 PP |
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. | |
0659f3af | 17 | |
e70712b3 PP |
18 | ---- |
19 | CTF streams on | |
20 | the 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 | ---- | |
0659f3af | 30 | |
e70712b3 | 31 | include::common-see-babeltrace2-intro.txt[] |
0659f3af | 32 | |
0659f3af | 33 | |
e70712b3 PP |
34 | [[input]] |
35 | === Input | |
0659f3af | 36 | |
e70712b3 PP |
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: | |
0659f3af | 40 | |
e70712b3 PP |
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`. | |
0659f3af | 46 | |
e70712b3 PP |
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). | |
0659f3af | 53 | |
e70712b3 PP |
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 | |
57 | the stream files. | |
0659f3af | 58 | |
e70712b3 PP |
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`''>>). | |
0659f3af | 64 | |
e70712b3 PP |
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). | |
0659f3af | 69 | |
66f6f862 PP |
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 | |
76 | duplicated packets. | |
77 | ||
0659f3af | 78 | |
e70712b3 | 79 | === Trace quirks |
0659f3af | 80 | |
e70712b3 PP |
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 | |
83 | malformed streams. | |
0659f3af | 84 | |
e70712b3 | 85 | Generally: |
0659f3af | 86 | |
e70712b3 PP |
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. | |
0659f3af | 91 | |
e70712b3 PP |
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: | |
0659f3af | 95 | |
e70712b3 PP |
96 | All 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 | + | |
102 | This is the equivalent of setting the | |
103 | param:force-clock-class-origin-unix-epoch parameter to true. | |
0659f3af | 104 | |
e70712b3 PP |
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 | + | |
109 | This is useful for the traces which man:lttng-crash(1) generates. | |
110 | -- | |
111 | ||
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:: | |
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 | ||
122 | barectf 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 | -- | |
0659f3af PP |
129 | |
130 | ||
eb9c9831 PP |
131 | === CTF compliance |
132 | ||
133 | A compcls:source.ctf.fs component decodes traces as per | |
134 | https://diamon.org/ctf/v1.8.3/[CTF~1.8.3], except: | |
135 | ||
136 | * It only supports integer field classes (TSDL `integer` block) with | |
137 | sizes from 1 to 64. | |
138 | ||
139 | * It only supports 32-bit and 64-bit floating point number classes (TSDL | |
140 | `floating_point` block). | |
141 | ||
142 | * It doesn't support ยง~4.1.6 (``GNU/C bitfields''). | |
143 | ||
144 | * It doesn't support TSDL `callsite` blocks: the parser simply ignores | |
145 | them. | |
146 | ||
147 | * It only supports a single clock class (TSDL `clock` block) reference | |
148 | per stream class (TSDL `stream` block). | |
149 | ||
150 | * It doesn't support the checksum, compression, and encryption features | |
151 | of metadata stream packets. | |
152 | ||
153 | ||
e70712b3 | 154 | == INITIALIZATION PARAMETERS |
0659f3af | 155 | |
e70712b3 PP |
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 | |
158 | component creates. | |
0659f3af PP |
159 | + |
160 | You can combine this parameter with the param:clock-class-offset-s | |
161 | parameter. | |
162 | ||
e70712b3 PP |
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 | |
165 | component creates. | |
0659f3af PP |
166 | + |
167 | You can combine this parameter with the param:clock-class-offset-ns | |
168 | parameter. | |
169 | ||
e70712b3 PP |
170 | param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]:: |
171 | Force the origin of all clock classes that the component creates to | |
172 | have a Unix epoch origin, whatever the detected tracer. | |
0659f3af | 173 | |
e70712b3 PP |
174 | param:inputs='DIRS' vtype:[array of strings]:: |
175 | Open and read the physical CTF traces located in 'DIRS'. | |
176 | + | |
177 | Each element of 'DIRS' is the path to a physical CTF trace directory | |
178 | containing the trace's stream files. | |
179 | + | |
180 | All the specified physical CTF traces must belong to the same logical | |
181 | CTF trace. See <<input,``Input''>> to learn more about logical and | |
182 | physical CTF traces. | |
0659f3af | 183 | |
e70712b3 PP |
184 | param:trace-name='NAME' vtype:[optional string]:: |
185 | Set the name of the trace object that the component creates to | |
186 | 'NAME'. | |
0659f3af PP |
187 | |
188 | ||
e70712b3 | 189 | == PORTS |
0659f3af | 190 | |
e70712b3 PP |
191 | ---- |
192 | +--------------------+ | |
193 | | src.ctf.fs | | |
194 | | | | |
195 | | ...5c847 | 0 | 1 @ | |
196 | | ... @ | |
197 | +--------------------+ | |
198 | ---- | |
0659f3af | 199 | |
0659f3af | 200 | |
e70712b3 | 201 | === Output |
0659f3af | 202 | |
e70712b3 PP |
203 | A compcls:source.ctf.fs component creates one output port for each |
204 | logical CTF data stream. See <<input,``Input''>> to learn more about | |
205 | logical and physical CTF data streams. | |
0659f3af | 206 | |
e70712b3 | 207 | Each output port's name has one of the following forms: |
0659f3af | 208 | |
e70712b3 PP |
209 | [verse] |
210 | __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__ | |
211 | __TRACE-ID__ | __STREAM-ID__ | |
0659f3af | 212 | |
e70712b3 PP |
213 | The component uses the second form when the stream class ID is not |
214 | available. | |
0659f3af | 215 | |
e70712b3 PP |
216 | __TRACE-ID__:: |
217 | Trace's UUID if available, otherwise trace's absolute directory | |
218 | path. | |
0659f3af | 219 | |
e70712b3 PP |
220 | __STREAM-CLASS-ID__:: |
221 | Stream class ID. | |
0659f3af | 222 | |
e70712b3 PP |
223 | __STREAM-ID__:: |
224 | Stream ID if available, otherwise stream's absolute file path. | |
0659f3af | 225 | |
0659f3af | 226 | |
e70712b3 PP |
227 | [[query-objs]] |
228 | == QUERY OBJECTS | |
0659f3af | 229 | |
e70712b3 PP |
230 | [[support-info]] |
231 | === `babeltrace.support-info` | |
0659f3af | 232 | |
e70712b3 PP |
233 | See man:babeltrace2-query-babeltrace.support-info(7) to learn more |
234 | about this query object. | |
0659f3af | 235 | |
e70712b3 PP |
236 | For a directory input which is the path to a CTF trace directory, |
237 | the result object contains: | |
0659f3af | 238 | |
e70712b3 PP |
239 | nlqres:weight:: |
240 | 0.75 | |
0659f3af | 241 | |
e70712b3 PP |
242 | nlqres:group:: |
243 | Trace's UUID if available, otherwise the entry does not exist. | |
0659f3af | 244 | |
e70712b3 PP |
245 | You can leverage this query object's nlqres:group entry to assemble many |
246 | physical CTF traces as a single logical CTF trace (see | |
247 | <<input,``Input''>> to learn more about logical and physical CTF | |
248 | traces). This is how the man:babeltrace2-convert(1) command makes it | |
249 | possible to specify as non-option arguments the paths to multiple | |
250 | physical CTF traces which belong to the same logical CTF trace and | |
251 | create a single compcls:source.ctf.fs component. | |
0659f3af | 252 | |
0659f3af | 253 | |
e70712b3 | 254 | === `babeltrace.trace-infos` |
0659f3af | 255 | |
e70712b3 PP |
256 | See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more |
257 | about this query object. | |
258 | ||
259 | ||
260 | === `metadata-info` | |
261 | ||
262 | You can query the `metadata-info` object for a specific CTF trace to get | |
263 | its plain text metadata stream as well as whether or not it is | |
264 | packetized. | |
0659f3af | 265 | |
e70712b3 PP |
266 | Parameters: |
267 | ||
268 | nlparam:path='PATH' vtype:[string]:: | |
269 | Path to the physical CTF trace directory which contains the | |
270 | `metadata` file. | |
0659f3af | 271 | |
e70712b3 | 272 | Result object (map): |
0659f3af | 273 | |
e70712b3 PP |
274 | qres:is-packetized vtype:[boolean]:: |
275 | True if the metadata stream file is packetized. | |
0659f3af | 276 | |
e70712b3 PP |
277 | qres:text vtype:[string]:: |
278 | Plain text metadata stream. | |
0659f3af PP |
279 | |
280 | ||
281 | include::common-footer.txt[] | |
282 | ||
283 | ||
e70712b3 PP |
284 | == SEE ALSO |
285 | ||
286 | man:babeltrace2-intro(7), | |
a8be4294 | 287 | man:babeltrace2-plugin-ctf(7), |
e70712b3 | 288 | man:lttng-crash(1) |