tests: make UUIDs under data/ctf-traces/intersection unique
[babeltrace.git] / doc / man / babeltrace2-source.ctf.fs.7.txt
CommitLineData
c1f82f3b 1babeltrace2-source.ctf.fs(7)
838dd456
PP
2===========================
3:manpagetype: component class
4:revdate: 5 October 2017
5
6
7NAME
8----
c1f82f3b 9babeltrace2-source.ctf.fs - Babeltrace's file system CTF source
838dd456
PP
10component class
11
12
13DESCRIPTION
14-----------
15The Babeltrace compcls:source.ctf.fs component class, provided by the
c1f82f3b 16man:babeltrace2-plugin-ctf(7) plugin, once instantiated, opens one or
838dd456
PP
17more http://diamon.org/ctf/[CTF] traces on the file system and emits the
18notifications of their data streams on its output ports.
19
20
21Operation
22~~~~~~~~~
23A compcls:source.ctf.fs component recurses the directory given by the
24param:path parameter to find CTF traces. Note that, since a CTF trace
25directory cannot contain another CTF trace, if you need to open a single
26trace, set the param:path parameter to a directory which directly
27contains the `metadata` file.
28
29For each trace, the component creates one output port per effective data
30stream. Multiple data stream files can constitute a single effective
31data stream. The name of a data stream output port is the absolute path
32to the corresponding data stream file, or to one of the corresponding
33data stream files if there's more than one.
34
35The component skips the following files when looking for data stream
36files:
37
38* Any file which starts with `.`, including subdirectories.
39* Any non-regular file.
40
41
42[[trace-naming]]
43Trace naming
44~~~~~~~~~~~~
45A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`,
46with:
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
58For 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
77If you set the param:path parameter to `/home/user/my-traces`, and
78assuming the hostname of the `trace1` and `server` traces is `machine`,
79and the hostname of the `client` trace is `embedded`, then the trace
80names are:
81
82* `machine/my-traces/trace1`
83* `machine/my-traces/node-traces/server`
84* `embedded/my-traces/node-traces/client`
85
86
87Metadata quirks
88~~~~~~~~~~~~~~~
89A compcls:source.ctf.fs component makes some efforts to support as many
90CTF traces as possible, even those of which the metadata is malformed
91or implements specification bugs.
92
93In 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
113INITIALIZATION PARAMETERS
114-------------------------
115The following parameters are optional unless indicated otherwise.
116
117param: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+
121You can combine this parameter with the param:clock-class-offset-s
122parameter.
123
124param: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+
128You can combine this parameter with the param:clock-class-offset-ns
129parameter.
130
131param:path='PATH' (string, mandatory)::
132 Path to the directory to recurse for CTF traces.
133
134
135PORTS
136-----
137Output
138~~~~~~
139For each opened trace, the component creates one output port for each
140effective data stream. The name of a data stream output port is the
141normalized (no `..` or `.` elements) absolute path to the corresponding
142data stream file, or to one of the corresponding data stream files if
143there's more than one.
144
145
146QUERY OBJECTS
147-------------
148`metadata-info`
149~~~~~~~~~~~~~~~
150You can query the `metadata-info` object for a specific CTF trace to get
151its plain text metadata stream as well as whether or not it is
152packetized.
153
154Parameters:
155
156`path` (string, mandatory)::
157 Path to the CTF trace directory which contains the `metadata` file.
158
159Returned 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~~~~~~~~~~~~~~~~~~~~~~~
170You can query the `babeltrace.trace-info` object for a set of CTF traces
171to get information about the data streams they contain, their
172intersection time range, and more.
838dd456
PP
173
174This query object requires that the processed CTF traces have the
175`timestamp_begin` and `timestamp_end` fields in their packet context
176field types.
177
178Parameters:
179
180`path` (string, mandatory)::
181 Path to a directory to recurse to find CTF traces.
182
183Returned 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
237ENVIRONMENT VARIABLES
238---------------------
239include::common-ctf-plugin-env.txt[]
240
241
242Component class
243~~~~~~~~~~~~~~~
244include::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
252include::common-footer.txt[]
253
254
255SEE ALSO
256--------
c1f82f3b
MJ
257man:babeltrace2-plugin-ctf(7),
258man:babeltrace2-intro(7)
This page took 0.04279 seconds and 4 git commands to generate.