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 `trace-info`
 169 ~~~~~~~~~~~~
 170 You can query the `trace-info` object for a set of CTF traces to get
 171 information about the data streams they contain, their intersection time
 172 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)