Add `babeltrace.` prefix to `trace-info` and `support-info` query objects
[babeltrace.git] / doc / man / babeltrace2-source.ctf.fs.7.txt
1 babeltrace2-source.ctf.fs(7)
2 ===========================
3 :manpagetype: component class
4 :revdate: 5 October 2017
5
6
7 NAME
8 ----
9 babeltrace2-source.ctf.fs - Babeltrace's file system CTF source
10 component class
11
12
13 DESCRIPTION
14 -----------
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.
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
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.
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
248 same as for the manopt:babeltrace2(1):--log-level option of
249 man:babeltrace2(1).
250
251
252 include::common-footer.txt[]
253
254
255 SEE ALSO
256 --------
257 man:babeltrace2-plugin-ctf(7),
258 man:babeltrace2-intro(7)
This page took 0.037245 seconds and 4 git commands to generate.