1BABELTRACE2-SINK.(7)          Babeltrace 2 manual         BABELTRACE2-SINK.(7)
2
3
4

NAME

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

DESCRIPTION

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
14                       +-------------+
15                       | sink.ctf.fs |
16                       |             +--> CTF trace(s) on
17           Messages -->@ in          |    the file system
18                       +-------------+
19
20       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
21       and its core concepts.
22
23       A sink.ctf.fs component does not merge traces: it writes the messages
24       of different input traces to different output traces.
25
26   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
32       •   The component translates a boolean field class to a CTF unsigned
33           8-bit integer field class.
34
35           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
38       •   The component translates a bit array field to a CTF unsigned
39           integer field class having the same length.
40
41       •   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
45           The empty structure field is selected when the option field has no
46           field.
47
48       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
52   Input message constraints
53       Because of limitations in CTF 1.8 regarding how discarded events and
54       packets are encoded:
55
56       •   If a stream class supports discarded events and the ignore-
57           discarded-events parameter is NOT true:
58
59           •   The stream class must support packets.
60
61           •   Discarded events messages must have times.
62
63           •   Any discarded events message must occur between a packet end
64               and a packet beginning message.
65
66           •   The beginning time of a discarded events message must be the
67               same as the time of the last packet end message.
68
69           •   The end time of a discarded events message must be the same as
70               the time of the next packet end message.
71
72           •   Time ranges of discarded events messages must not overlap.
73
74       •   If a stream class supports discarded packets and the ignore-
75           discarded-packets parameter is NOT true:
76
77           •   The stream class must support packets.
78
79           •   Discarded packets messages must have times.
80
81           •   The beginning time of a discarded events message must be the
82               same as the time of the last packet end message.
83
84           •   The end time of a discarded events message must be the same as
85               the time of the next packet beginning message.
86
87           •   Time ranges of discarded packets messages must not overlap.
88
89       The messages which a source.ctf.fs component creates satisfy all the
90       requirements above.
91
92       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
96   Alignment and byte order
97       A sink.ctf.fs component always aligns data fields as such:
98
99       Integer fields with a size which is not a multiple of 8
100           1-bit.
101
102       All other scalar fields (integer, enumeration, real, string)
103           8-bit.
104
105       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
108   Output path
109       The path of a CTF trace is the directory which directly contains the
110       metadata and data stream files.
111
112       The current strategy to build a path in which to write the streams of a
113       given input trace is, in this order:
114
115        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
119        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
124           Linux kernel domain
125
126                   HOST/SNAME-STIME/kernel
127
128           User space domain, per-UID buffering
129
130                   HOST/SNAME-STIME/ust/uid/UID/ARCHW-bit
131
132           User space domain, per-PID buffering
133
134                   HOST/SNAME-STIME/ust/pid/PNAME-PID-PTIME
135
136           With:
137
138           HOST
139               Target’s hostname.
140
141           SNAME
142               Tracing session name.
143
144           STIME
145               Tracing session creation date/time.
146
147           UID
148               User ID.
149
150           ARCHW
151               Architecture’s width (32 or 64).
152
153           PNAME
154               Process name.
155
156           PID
157               Process ID.
158
159           PTIME
160               Process’s date/time.
161
162        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
166           The trace name sanitization operation:
167
168           •   Replaces .  subdirectories with _.
169
170           •   Replaces ..  subdirectories with __.
171
172           •   Removes any trailing / character.
173
174        4. The component uses the subdirectory trace relative to the directory
175           specified by the path parameter.
176
177       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

INITIALIZATION PARAMETERS

183       assume-single-trace=yes [optional boolean]
184           Assume that the component only receives messages related to a
185           single input trace.
186
187           This parameter affects how the component builds the output trace
188           path (see “Output path”).
189
190       ignore-discarded-events=yes [optional boolean]
191           Ignore discarded events messages.
192
193       ignore-discarded-packets=yes [optional boolean]
194           Ignore discarded packets messages.
195
196       path=PATH [string]
197           Base output path.
198
199           See “Output path” to learn how the component uses this parameter to
200           build the output path for a given input trace.
201
202       quiet=yes [optional boolean]
203           Do not write anything to the standard output.
204

PORTS

206           +-------------+
207           | sink.ctf.fs |
208           |             |
209           @ in          |
210           +-------------+
211
212   Input
213       in
214           Single input port.
215

BUGS

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

RESOURCES

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

AUTHORS

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

SEE ALSO

258       babeltrace2-intro(7), babeltrace2-plugin-ctf(7)
259
260
261
262Babeltrace 2.0.5               14 September 2019          BABELTRACE2-SINK.(7)
Impressum