Commit | Line | Data |
---|---|---|
c1f82f3b | 1 | babeltrace2-source.ctf.fs(7) |
838dd456 PP |
2 | =========================== |
3 | :manpagetype: component class | |
4 | :revdate: 5 October 2017 | |
5 | ||
6 | ||
7 | NAME | |
8 | ---- | |
c1f82f3b | 9 | babeltrace2-source.ctf.fs - Babeltrace's file system CTF source |
838dd456 PP |
10 | component class |
11 | ||
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | The Babeltrace compcls:source.ctf.fs component class, provided by the | |
c1f82f3b | 16 | man:babeltrace2-plugin-ctf(7) plugin, once instantiated, opens one or |
838dd456 PP |
17 | more http://diamon.org/ctf/[CTF] traces on the file system and emits the |
18 | notifications of their data streams on its output ports. | |
19 | ||
20 | ||
21 | Operation | |
22 | ~~~~~~~~~ | |
23 | A compcls:source.ctf.fs component recurses the directory given by the | |
24 | param:path parameter to find CTF traces. Note that, since a CTF trace | |
25 | directory cannot contain another CTF trace, if you need to open a single | |
26 | trace, set the param:path parameter to a directory which directly | |
27 | contains the `metadata` file. | |
28 | ||
29 | For each trace, the component creates one output port per effective data | |
30 | stream. Multiple data stream files can constitute a single effective | |
31 | data stream. The name of a data stream output port is the absolute path | |
32 | to the corresponding data stream file, or to one of the corresponding | |
33 | data stream files if there's more than one. | |
34 | ||
35 | The component skips the following files when looking for data stream | |
36 | files: | |
37 | ||
38 | * Any file which starts with `.`, including subdirectories. | |
39 | * Any non-regular file. | |
40 | ||
41 | ||
42 | [[trace-naming]] | |
43 | Trace naming | |
44 | ~~~~~~~~~~~~ | |
45 | A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`, | |
46 | with: | |
47 | ||
48 | `HOSTNAME`:: | |
49 | Value of the trace's `hostname` environment constant. If this | |
50 | environment constant does not exist, or if its value is not a | |
51 | string, then this part is omitted. | |
52 | ||
53 | `PATH`:: | |
54 | Relative path to the trace, starting at and including the basename | |
55 | of the param:path parameter. This path is normalized, that is, it | |
56 | doesn't contain path elements named `..` or `.`. | |
57 | ||
58 | For example, assume the following hierarchy: | |
59 | ||
60 | ---- | |
61 | / | |
62 | home/ | |
63 | user/ | |
64 | my-traces/ | |
65 | trace1/ | |
66 | metadata | |
67 | ... | |
68 | node-traces/ | |
69 | server/ | |
70 | metadata | |
71 | ... | |
72 | client/ | |
73 | metadata | |
74 | ... | |
75 | ---- | |
76 | ||
77 | If you set the param:path parameter to `/home/user/my-traces`, and | |
78 | assuming the hostname of the `trace1` and `server` traces is `machine`, | |
79 | and the hostname of the `client` trace is `embedded`, then the trace | |
80 | names are: | |
81 | ||
82 | * `machine/my-traces/trace1` | |
83 | * `machine/my-traces/node-traces/server` | |
84 | * `embedded/my-traces/node-traces/client` | |
85 | ||
86 | ||
87 | Metadata quirks | |
88 | ~~~~~~~~~~~~~~~ | |
89 | A compcls:source.ctf.fs component makes some efforts to support as many | |
90 | CTF traces as possible, even those of which the metadata is malformed | |
91 | or implements specification bugs. | |
92 | ||
93 | In particular: | |
94 | ||
95 | * If the component detects that the trace was produced by LTTng, it sets | |
96 | the `monotonic` clock class as absolute so that different LTTng traces | |
97 | are directly correlatable. An LTTng trace has its `tracer_name` | |
98 | environment constant starting with `lttng`. | |
99 | ||
100 | * If the `timestamp_begin` or `timestamp_end` packet context field | |
101 | type exists, but it is not mapped to a clock class, and there's | |
102 | only one clock class at this point in the metadata stream, the | |
103 | component maps it to this unique clock class. | |
104 | ||
105 | * If an enumeration field type's label starts with `_`, the component | |
106 | removes the starting `_` character. This is needed to accomodate | |
107 | an eventual variant field type which refers to the enumeration field type | |
108 | as its tag and which has equivalent choice names also starting | |
109 | with `_` (the `_` must be removed from field and choice names as | |
110 | per CTF{nbsp}1.8.2). | |
111 | ||
112 | ||
113 | INITIALIZATION PARAMETERS | |
114 | ------------------------- | |
115 | The following parameters are optional unless indicated otherwise. | |
116 | ||
117 | param:clock-class-offset-ns (integer):: | |
118 | Value to add, in nanoseconds, to the offset of all the clock classes | |
119 | that the component creates. | |
120 | + | |
121 | You can combine this parameter with the param:clock-class-offset-s | |
122 | parameter. | |
123 | ||
124 | param:clock-class-offset-s (integer):: | |
125 | Value to add, in seconds, to the offset of all the clock classes | |
126 | that the component creates. | |
127 | + | |
128 | You can combine this parameter with the param:clock-class-offset-ns | |
129 | parameter. | |
130 | ||
131 | param:path='PATH' (string, mandatory):: | |
132 | Path to the directory to recurse for CTF traces. | |
133 | ||
134 | ||
135 | PORTS | |
136 | ----- | |
137 | Output | |
138 | ~~~~~~ | |
139 | For each opened trace, the component creates one output port for each | |
140 | effective data stream. The name of a data stream output port is the | |
141 | normalized (no `..` or `.` elements) absolute path to the corresponding | |
142 | data stream file, or to one of the corresponding data stream files if | |
143 | there's more than one. | |
144 | ||
145 | ||
146 | QUERY OBJECTS | |
147 | ------------- | |
148 | `metadata-info` | |
149 | ~~~~~~~~~~~~~~~ | |
150 | You can query the `metadata-info` object for a specific CTF trace to get | |
151 | its plain text metadata stream as well as whether or not it is | |
152 | packetized. | |
153 | ||
154 | Parameters: | |
155 | ||
156 | `path` (string, mandatory):: | |
157 | Path to the CTF trace directory which contains the `metadata` file. | |
158 | ||
159 | Returned object (map): | |
160 | ||
161 | `text` (string):: | |
162 | Plain text metadata. | |
163 | ||
164 | `is-packetized` (boolean):: | |
165 | True if the metadata stream is packetized. | |
166 | ||
167 | ||
9e534aae PP |
168 | `babeltrace.trace-info` |
169 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
170 | You can query the `babeltrace.trace-info` object for a set of CTF traces | |
171 | to get information about the data streams they contain, their | |
172 | intersection time range, and more. | |
838dd456 PP |
173 | |
174 | This query object requires that the processed CTF traces have the | |
175 | `timestamp_begin` and `timestamp_end` fields in their packet context | |
176 | field types. | |
177 | ||
178 | Parameters: | |
179 | ||
180 | `path` (string, mandatory):: | |
181 | Path to a directory to recurse to find CTF traces. | |
182 | ||
183 | Returned object (array of maps, one element for each found trace): | |
184 | ||
185 | `name` (string):: | |
186 | Trace name, as per the explanations in the <<trace-naming,Trace | |
187 | naming>> section. | |
188 | ||
189 | `path` (string):: | |
190 | Trace path. | |
191 | ||
192 | `range-ns` (map):: | |
193 | Full time range of the trace. | |
194 | + | |
195 | -- | |
196 | `begin` (integer):: | |
197 | Beginning time (ns since Epoch) of the trace. | |
198 | ||
199 | `end` (integer):: | |
200 | End time (ns since Epoch) of the trace. | |
201 | -- | |
202 | ||
203 | `intersection-range-ns` (map):: | |
204 | This entry only exists if there is a data stream intersection range. | |
205 | + | |
206 | -- | |
207 | `begin` (integer):: | |
208 | Beginning time (ns since Epoch) of the trace's data stream | |
209 | intersection. | |
210 | ||
211 | `end` (integer):: | |
212 | End time (ns since Epoch) of the trace's data stream intersection. | |
213 | -- | |
214 | ||
215 | `streams` (array of maps, one element for each trace's effective data stream):: | |
216 | + | |
217 | -- | |
218 | `paths` (array of strings):: | |
219 | Absolute paths to the data stream files which are part of this | |
220 | data stream. | |
221 | ||
222 | `class-id` (integer):: | |
223 | Numeric ID of the data stream's class. | |
224 | ||
225 | `range-ns` (map):: | |
226 | Full time range of the data stream. | |
227 | + | |
228 | -- | |
229 | `begin` (integer):: | |
230 | Beginning time (ns since Epoch) of the data stream. | |
231 | ||
232 | `end` (integer):: | |
233 | End time (ns since Epoch) of the data stream. | |
234 | -- | |
235 | -- | |
236 | ||
237 | ENVIRONMENT VARIABLES | |
238 | --------------------- | |
239 | include::common-ctf-plugin-env.txt[] | |
240 | ||
241 | ||
242 | Component class | |
243 | ~~~~~~~~~~~~~~~ | |
244 | include::common-common-compat-env.txt[] | |
245 | ||
246 | `BABELTRACE_SRC_CTF_FS_LOG_LEVEL`:: | |
247 | Component class's log level. The available values are the | |
c1f82f3b MJ |
248 | same as for the manopt:babeltrace2(1):--log-level option of |
249 | man:babeltrace2(1). | |
838dd456 PP |
250 | |
251 | ||
252 | include::common-footer.txt[] | |
253 | ||
254 | ||
255 | SEE ALSO | |
256 | -------- | |
c1f82f3b MJ |
257 | man:babeltrace2-plugin-ctf(7), |
258 | man:babeltrace2-intro(7) |