1 babeltrace2-source.ctf.fs(7)
2 ===========================
3 :manpagetype: component class
4 :revdate: 5 October 2017
9 babeltrace2-source.ctf.fs - Babeltrace's file system CTF source
15 The Babeltrace compcls:source.ctf.fs component class, provided by the
16 man:babeltrace2-plugin-ctf(7) plugin, once instantiated, opens one or
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.
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.
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.
35 The component skips the following files when looking for data stream
38 * Any file which starts with `.`, including subdirectories.
39 * Any non-regular file.
45 A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`,
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.
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 `.`.
58 For example, assume the following hierarchy:
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
82 * `machine/my-traces/trace1`
83 * `machine/my-traces/node-traces/server`
84 * `embedded/my-traces/node-traces/client`
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.
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`.
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.
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
113 INITIALIZATION PARAMETERS
114 -------------------------
115 The following parameters are optional unless indicated otherwise.
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.
121 You can combine this parameter with the param:clock-class-offset-s
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.
128 You can combine this parameter with the param:clock-class-offset-ns
131 param:path='PATH' (string, mandatory)::
132 Path to the directory to recurse for CTF traces.
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.
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
156 `path` (string, mandatory)::
157 Path to the CTF trace directory which contains the `metadata` file.
159 Returned object (map):
164 `is-packetized` (boolean)::
165 True if the metadata stream is packetized.
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.
174 This query object requires that the processed CTF traces have the
175 `timestamp_begin` and `timestamp_end` fields in their packet context
180 `path` (string, mandatory)::
181 Path to a directory to recurse to find CTF traces.
183 Returned object (array of maps, one element for each found trace):
186 Trace name, as per the explanations in the <<trace-naming,Trace
193 Full time range of the trace.
197 Beginning time (ns since Epoch) of the trace.
200 End time (ns since Epoch) of the trace.
203 `intersection-range-ns` (map)::
204 This entry only exists if there is a data stream intersection range.
208 Beginning time (ns since Epoch) of the trace's data stream
212 End time (ns since Epoch) of the trace's data stream intersection.
215 `streams` (array of maps, one element for each trace's effective data stream)::
218 `paths` (array of strings)::
219 Absolute paths to the data stream files which are part of this
222 `class-id` (integer)::
223 Numeric ID of the data stream's class.
226 Full time range of the data stream.
230 Beginning time (ns since Epoch) of the data stream.
233 End time (ns since Epoch) of the data stream.
237 ENVIRONMENT VARIABLES
238 ---------------------
239 include::common-ctf-plugin-env.txt[]
244 include::common-common-compat-env.txt[]
246 `BABELTRACE_SRC_CTF_FS_LOG_LEVEL`::
247 Component class's log level. The available values are the
248 same as for the manopt:babeltrace2(1):--log-level option of
252 include::common-footer.txt[]
257 man:babeltrace2-plugin-ctf(7),
258 man:babeltrace2-intro(7)