Commit | Line | Data |
---|---|---|
e70712b3 | 1 | = babeltrace2-sink.ctf.fs(7) |
0659f3af | 2 | :manpagetype: component class |
6f6e5e61 | 3 | :revdate: 1 September 2023 |
0659f3af PP |
4 | |
5 | ||
e70712b3 PP |
6 | == NAME |
7 | ||
8 | babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component | |
0659f3af PP |
9 | class |
10 | ||
11 | ||
e70712b3 PP |
12 | == DESCRIPTION |
13 | ||
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 | |
0659f3af PP |
16 | the file system. |
17 | ||
e70712b3 PP |
18 | ---- |
19 | +-------------+ | |
20 | | sink.ctf.fs | | |
21 | | +--> CTF trace(s) on | |
22 | Messages -->@ in | the file system | |
23 | +-------------+ | |
24 | ---- | |
25 | ||
26 | include::common-see-babeltrace2-intro.txt[] | |
27 | ||
28 | A compcls:sink.ctf.fs component does not merge traces: it writes the | |
29 | messages of different input traces to different output traces. | |
30 | ||
31 | ||
32 | === Special trace IR to CTF translations | |
33 | ||
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: | |
38 | ||
39 | * The component translates a boolean field class to a CTF unsigned 8-bit | |
40 | integer field class. | |
41 | + | |
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. | |
44 | ||
45 | * The component translates a bit array field to a CTF unsigned | |
46 | integer field class having the same length. | |
47 | ||
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. | |
51 | + | |
52 | The empty structure field is selected when the option field has no | |
53 | field. | |
54 | ||
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 | |
118ae153 | 57 | occurred. |
e70712b3 PP |
58 | |
59 | ||
60 | === Input message constraints | |
61 | ||
62 | Because of limitations in CTF~1.8 regarding how discarded events | |
63 | and packets are encoded: | |
64 | ||
65 | * If a stream class supports discarded events and the | |
66 | param:ignore-discarded-events parameter is :not: true: | |
67 | ||
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. | |
77 | ||
78 | * If a stream class supports discarded packets and the | |
79 | param:ignore-discarded-packets parameter is :not: true: | |
80 | ||
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. | |
0659f3af | 88 | |
e70712b3 PP |
89 | The messages which a compcls:source.ctf.fs component creates satisfy all |
90 | the requirements above. | |
0659f3af | 91 | |
e70712b3 PP |
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 | |
94 | stream's counter. | |
0659f3af | 95 | |
0659f3af | 96 | |
e70712b3 | 97 | === Alignment and byte order |
0659f3af | 98 | |
e70712b3 PP |
99 | A compcls:sink.ctf.fs component always aligns data fields as such: |
100 | ||
101 | Integer fields with a size which is not a multiple of 8:: | |
102 | 1-bit. | |
103 | ||
104 | All other scalar fields (integer, enumeration, real, string):: | |
105 | 8-bit. | |
106 | ||
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. | |
109 | ||
110 | ||
111 | [[output-path]] | |
112 | === Output path | |
0659f3af | 113 | |
0659f3af | 114 | The path of a CTF trace is the directory which directly contains the |
e70712b3 | 115 | metadata and data stream files. |
0659f3af | 116 | |
e70712b3 PP |
117 | The current strategy to build a path in which to write the streams of |
118 | a given input trace is, in this order: | |
0659f3af | 119 | |
e70712b3 PP |
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. | |
123 | ||
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: | |
0659f3af | 128 | + |
e70712b3 PP |
129 | -- |
130 | ||
131 | Linux kernel domain:: | |
132 | + | |
133 | [verse] | |
134 | __HOST__/__SNAME__-__STIME__/kernel | |
135 | ||
136 | User space domain, per-UID buffering:: | |
0659f3af | 137 | + |
e70712b3 PP |
138 | [verse] |
139 | __HOST__/__SNAME__-__STIME__/ust/uid/__UID__/__ARCHW__-bit | |
140 | ||
141 | User space domain, per-PID buffering:: | |
142 | + | |
143 | [verse] | |
144 | __HOST__/__SNAME__-__STIME__/ust/pid/__PNAME__-__PID__-__PTIME__ | |
145 | ||
0659f3af | 146 | -- |
0659f3af | 147 | + |
e70712b3 | 148 | With: |
0659f3af | 149 | + |
0659f3af | 150 | -- |
e70712b3 PP |
151 | __HOST__:: |
152 | Target's hostname. | |
0659f3af | 153 | |
e70712b3 PP |
154 | __SNAME__:: |
155 | Tracing session name. | |
0659f3af | 156 | |
e70712b3 PP |
157 | __STIME__:: |
158 | Tracing session creation date/time. | |
0659f3af | 159 | |
e70712b3 PP |
160 | __UID__:: |
161 | User ID. | |
0659f3af | 162 | |
e70712b3 PP |
163 | __ARCHW__:: |
164 | Architecture's width (`32` or `64`). | |
0659f3af | 165 | |
e70712b3 PP |
166 | __PNAME__:: |
167 | Process name. | |
0659f3af | 168 | |
e70712b3 PP |
169 | __PID__:: |
170 | Process ID. | |
0659f3af | 171 | |
e70712b3 PP |
172 | __PTIME__:: |
173 | Process's date/time. | |
174 | -- | |
0659f3af | 175 | |
e70712b3 PP |
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. | |
179 | + | |
180 | The trace name sanitization operation: | |
181 | + | |
182 | * Replaces `.` subdirectories with `_`. | |
183 | * Replaces `..` subdirectories with `__`. | |
184 | * Removes any trailing `/` character. | |
0659f3af | 185 | |
e70712b3 PP |
186 | . The component uses the subdirectory `trace` relative to the directory |
187 | specified by the param:path parameter. | |
0659f3af | 188 | |
e70712b3 PP |
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. | |
0659f3af | 193 | |
0659f3af | 194 | |
e70712b3 PP |
195 | == INITIALIZATION PARAMETERS |
196 | ||
6f6e5e61 PP |
197 | param:assume-single-trace='VAL' vtype:[optional boolean]:: |
198 | If 'VAL' is true, then assume that the component only receives | |
199 | messages related to a single input trace. | |
e70712b3 PP |
200 | + |
201 | This parameter affects how the component builds the output trace path | |
202 | (see <<output-path,``Output path''>>). | |
6f6e5e61 PP |
203 | + |
204 | Default: false. | |
e70712b3 | 205 | |
6f6e5e61 PP |
206 | param:ignore-discarded-events='VAL' vtype:[optional boolean]:: |
207 | If 'VAL' is true, then ignore discarded events messages. | |
208 | + | |
209 | Default: false. | |
e70712b3 | 210 | |
6f6e5e61 PP |
211 | param:ignore-discarded-packets='VAL' vtype:[optional boolean]:: |
212 | If 'VAL' is true, then ignore discarded packets messages. | |
213 | + | |
214 | Default: false. | |
e70712b3 PP |
215 | |
216 | param:path='PATH' vtype:[string]:: | |
217 | Base output path. | |
218 | + | |
219 | See <<output-path,``Output path''>> to learn how the component uses this | |
220 | parameter to build the output path for a given input trace. | |
221 | ||
6f6e5e61 PP |
222 | param:quiet='VAL' vtype:[optional boolean]:: |
223 | If 'VAL' is true, then do not write anything to the standard output. | |
224 | + | |
225 | Default: false. | |
e70712b3 PP |
226 | |
227 | ||
228 | == PORTS | |
229 | ||
230 | ---- | |
231 | +-------------+ | |
232 | | sink.ctf.fs | | |
233 | | | | |
234 | @ in | | |
235 | +-------------+ | |
236 | ---- | |
237 | ||
238 | ||
239 | === Input | |
240 | ||
241 | `in`:: | |
242 | Single input port. | |
0659f3af PP |
243 | |
244 | ||
245 | include::common-footer.txt[] | |
246 | ||
247 | ||
e70712b3 PP |
248 | == SEE ALSO |
249 | ||
250 | man:babeltrace2-intro(7), | |
251 | man:babeltrace2-plugin-ctf(7) |