1BABELTRACE2-SINK.(7) Babeltrace 2 manual BABELTRACE2-SINK.(7)
2
6 babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component
7 class
8
10 A Babeltrace 2 sink.ctf.fs component writes the messages it consumes to
11 one or more CTF (see <https://diamon.org/ctf/>) 1.8 traces on the file
12 system.
13 +-------------+
15 | sink.ctf.fs |
16 | +--> CTF trace(s) on
17 Messages -->@ in | the file system
18 +-------------+
19 See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
21 and its core concepts.
22 A sink.ctf.fs component does not merge traces: it writes the messages
24 of different input traces to different output traces.
25 Special trace IR to CTF translations
27 A sink.ctf.fs component makes a best effort to write CTF traces that
28 are semantically equivalent to the input traces. As of this version,
29 the component writes CTF 1.8 traces, so the following field class
30 translations can occur:
31 • The component translates a boolean field class to a CTF unsigned
33 8-bit integer field class.
34 The unsigned integer field’s value is 0 when the boolean field’s
36 value is false and 1 when the boolean field’s value is true.
37 • The component translates a bit array field to a CTF unsigned
39 integer field class having the same length.
40 • The component translates an option field class to a CTF variant
42 field class where the options are an empty structure field class
43 and the optional field class itself.
44 The empty structure field is selected when the option field has no
46 field.
47 In all the cases above, the component adds a comment in the metadata
49 stream, above the field class, to indicate that a special translation
50 occurred.
51 Input message constraints
53 Because of limitations in CTF 1.8 regarding how discarded events and
54 packets are encoded:
55 • If a stream class supports discarded events and the ignore-
57 discarded-events parameter is NOT true:
58 • The stream class must support packets.
60 • Discarded events messages must have times.
62 • Any discarded events message must occur between a packet end
64 and a packet beginning message.
65 • The beginning time of a discarded events message must be the
67 same as the time of the last packet end message.
68 • The end time of a discarded events message must be the same as
70 the time of the next packet end message.
71 • Time ranges of discarded events messages must not overlap.
73 • If a stream class supports discarded packets and the ignore-
75 discarded-packets parameter is NOT true:
76 • The stream class must support packets.
78 • Discarded packets messages must have times.
80 • The beginning time of a discarded events message must be the
82 same as the time of the last packet end message.
83 • The end time of a discarded events message must be the same as
85 the time of the next packet beginning message.
86 • Time ranges of discarded packets messages must not overlap.
88 The messages which a source.ctf.fs component creates satisfy all the
90 requirements above.
91 If a discarded events or packets message has no events/packets count,
93 the sink.ctf.fs component adds 1 to the corresponding CTF stream’s
94 counter.
95 Alignment and byte order
97 A sink.ctf.fs component always aligns data fields as such:
98 Integer fields with a size which is not a multiple of 8
100 1-bit.
101 All other scalar fields (integer, enumeration, real, string)
103 8-bit.
104 The component writes fields using the machine’s native byte order. As
106 of this version, there’s no way to force a custom byte order.
107 Output path
109 The path of a CTF trace is the directory which directly contains the
110 metadata and data stream files.
111 The current strategy to build a path in which to write the streams of a
113 given input trace is, in this order:
114 1. If the assume-single-trace parameter is true, then the output trace
116 path to use for the single input trace is the directory specified
117 by the path parameter.
118 2. If the component recognizes the input trace as an LTTng (2.11 or
120 greater) trace, then it checks specific trace environment values to
121 build a trace path relative to the directory specified by the path
122 parameter:
123 Linux kernel domain
125 HOST/SNAME-STIME/kernel
127 User space domain, per-UID buffering
129 HOST/SNAME-STIME/ust/uid/UID/ARCHW-bit
131 User space domain, per-PID buffering
133 HOST/SNAME-STIME/ust/pid/PNAME-PID-PTIME
135 With:
137 HOST
139 Target’s hostname.
140 SNAME
142 Tracing session name.
143 STIME
145 Tracing session creation date/time.
146 UID
148 User ID.
149 ARCHW
151 Architecture’s width (32 or 64).
152 PNAME
154 Process name.
155 PID
157 Process ID.
158 PTIME
160 Process’s date/time.
161 3. If the input trace has a name, then the component sanitizes this
163 name and uses it as a relative path to the directory specified by
164 the path parameter.
165 The trace name sanitization operation:
167 • Replaces . subdirectories with _.
169 • Replaces .. subdirectories with __.
171 • Removes any trailing / character.
173 4. The component uses the subdirectory trace relative to the directory
175 specified by the path parameter.
176 In all the cases above, if the effective output trace path already
178 exists on the file system, the component appends a numeric suffix to
179 the name of the last subdirectory. The suffix starts at 0 and
180 increments until the path does not exist.
181
183 assume-single-trace=yes [optional boolean]
184 Assume that the component only receives messages related to a
185 single input trace.
186 This parameter affects how the component builds the output trace
188 path (see “Output path”).
189 ignore-discarded-events=yes [optional boolean]
191 Ignore discarded events messages.
192 ignore-discarded-packets=yes [optional boolean]
194 Ignore discarded packets messages.
195 path=PATH [string]
197 Base output path.
198 See “Output path” to learn how the component uses this parameter to
200 build the output path for a given input trace.
201 quiet=yes [optional boolean]
203 Do not write anything to the standard output.
204
206 +-------------+
207 | sink.ctf.fs |
208 | |
209 @ in |
210 +-------------+
211 Input
213 in
214 Single input port.
215
217 If you encounter any issue or usability problem, please report it on
218 the Babeltrace bug tracker (see
219 <https://bugs.lttng.org/projects/babeltrace>).
220
222 The Babeltrace project shares some communication channels with the
223 LTTng project (see <https://lttng.org/>).
224 • Babeltrace website (see <https://babeltrace.org/>)
226 • Mailing list (see <https://lists.lttng.org>) for support and
228 development: lttng-dev@lists.lttng.org
229 • IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
231 irc.oftc.net
232 • Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
234 • Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
236 • GitHub project (see <https://github.com/efficios/babeltrace>)
238 • Continuous integration (see
240 <https://ci.lttng.org/view/Babeltrace/>)
241 • Code review (see <https://review.lttng.org/q/project:babeltrace>)
243
245 The Babeltrace 2 project is the result of hard work by many regular
246 developers and occasional contributors.
247 The current project maintainer is Jérémie Galarneau
249 <mailto:jeremie.galarneau@efficios.com>.
250
252 This component class is part of the Babeltrace 2 project.
253 Babeltrace is distributed under the MIT license (see
255 <https://opensource.org/licenses/MIT>).
256
258 babeltrace2-intro(7), babeltrace2-plugin-ctf(7)
259Babeltrace 2.0.5 14 September 2019 BABELTRACE2-SINK.(7)