1 = babeltrace2-sink.ctf.fs(7)
2 :manpagetype: component class
3 :revdate: 14 September 2019
8 babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component
14 A Babeltrace~2 compcls:sink.ctf.fs component writes the messages it
15 consumes to one or more https://diamon.org/ctf/[CTF]~1.8 traces on
21 | +--> CTF trace(s) on
22 Messages -->@ in | the file system
26 include::common-see-babeltrace2-intro.txt[]
28 A compcls:sink.ctf.fs component does not merge traces: it writes the
29 messages of different input traces to different output traces.
32 === Special trace IR to CTF translations
34 A compcls:sink.ctf.fs component makes a best effort to write CTF traces
35 that are semantically equivalent to the input traces. As of this
36 version, the component writes CTF~1.8 traces, so the following
37 field class translations can occur:
39 * The component translates a boolean field class to a CTF unsigned 8-bit
42 The unsigned integer field's value is 0 when the boolean field's value
43 is false and 1 when the boolean field's value is true.
45 * The component translates a bit array field to a CTF unsigned
46 integer field class having the same length.
48 * The component translates an option field class to a CTF variant
49 field class where the options are an empty structure field class
50 and the optional field class itself.
52 The empty structure field is selected when the option field has no
55 In all the cases above, the component adds a comment in the metadata
56 stream, above the field class, to indicate that a special translation
60 === Input message constraints
62 Because of limitations in CTF~1.8 regarding how discarded events
63 and packets are encoded:
65 * If a stream class supports discarded events and the
66 param:ignore-discarded-events parameter is :not: true:
68 ** The stream class must support packets.
69 ** Discarded events messages must have times.
70 ** Any discarded events message must occur between a packet end
71 and a packet beginning message.
72 ** The beginning time of a discarded events message must be the same
73 as the time of the last packet end message.
74 ** The end time of a discarded events message must be the same
75 as the time of the next packet end message.
76 ** Time ranges of discarded events messages must not overlap.
78 * If a stream class supports discarded packets and the
79 param:ignore-discarded-packets parameter is :not: true:
81 ** The stream class must support packets.
82 ** Discarded packets messages must have times.
83 ** The beginning time of a discarded events message must be the same
84 as the time of the last packet end message.
85 ** The end time of a discarded events message must be the same
86 as the time of the next packet beginning message.
87 ** Time ranges of discarded packets messages must not overlap.
89 The messages which a compcls:source.ctf.fs component creates satisfy all
90 the requirements above.
92 If a discarded events or packets message has no events/packets count,
93 the compcls:sink.ctf.fs component adds 1 to the corresponding CTF
97 === Alignment and byte order
99 A compcls:sink.ctf.fs component always aligns data fields as such:
101 Integer fields with a size which is not a multiple of 8::
104 All other scalar fields (integer, enumeration, real, string)::
107 The component writes fields using the machine's native byte order. As of
108 this version, there's no way to force a custom byte order.
114 The path of a CTF trace is the directory which directly contains the
115 metadata and data stream files.
117 The current strategy to build a path in which to write the streams of
118 a given input trace is, in this order:
120 . If the param:assume-single-trace parameter is true, then the output
121 trace path to use for the single input trace is the directory
122 specified by the param:path parameter.
124 . If the component recognizes the input trace as an LTTng (2.11 or
125 greater) trace, then it checks specific trace environment values to
126 build a trace path relative to the directory specified by the
127 param:path parameter:
131 Linux kernel domain::
134 __HOST__/__SNAME__-__STIME__/kernel
136 User space domain, per-UID buffering::
139 __HOST__/__SNAME__-__STIME__/ust/uid/__UID__/__ARCHW__-bit
141 User space domain, per-PID buffering::
144 __HOST__/__SNAME__-__STIME__/ust/pid/__PNAME__-__PID__-__PTIME__
155 Tracing session name.
158 Tracing session creation date/time.
164 Architecture's width (`32` or `64`).
176 . If the input trace has a name, then the component sanitizes this name
177 and uses it as a relative path to the directory specified by the
178 param:path parameter.
180 The trace name sanitization operation:
182 * Replaces `.` subdirectories with `_`.
183 * Replaces `..` subdirectories with `__`.
184 * Removes any trailing `/` character.
186 . The component uses the subdirectory `trace` relative to the directory
187 specified by the param:path parameter.
189 In all the cases above, if the effective output trace path already
190 exists on the file system, the component appends a numeric suffix to the
191 name of the last subdirectory. The suffix starts at 0 and increments
192 until the path does not exist.
195 == INITIALIZATION PARAMETERS
197 param:assume-single-trace=`yes` vtype:[optional boolean]::
198 Assume that the component only receives messages related to a single
201 This parameter affects how the component builds the output trace path
202 (see <<output-path,``Output path''>>).
204 param:ignore-discarded-events=`yes` vtype:[optional boolean]::
205 Ignore discarded events messages.
207 param:ignore-discarded-packets=`yes` vtype:[optional boolean]::
208 Ignore discarded packets messages.
210 param:path='PATH' vtype:[string]::
213 See <<output-path,``Output path''>> to learn how the component uses this
214 parameter to build the output path for a given input trace.
216 param:quiet=`yes` vtype:[optional boolean]::
217 Do not write anything to the standard output.
237 include::common-footer.txt[]
242 man:babeltrace2-intro(7),
243 man:babeltrace2-plugin-ctf(7)