doc/man/babeltrace2-source.ctf.fs.7.txt

   1 = babeltrace2-source.ctf.fs(7)
   2 :manpagetype: component class
   3 :revdate: 14 September 2019
   4
   5
   6 == NAME
   7
   8 babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
   9 component class
  10
  11
  12 == DESCRIPTION
  13
  14 A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or
  15 more https://diamon.org/ctf/[CTF]~1.8 streams on the file system
  16 and emits corresponding messages.
  17
  18 ----
  19 CTF streams on
  20 the file system
  21   |
  22   |   +---------------------+
  23   |   |      src.ctf.fs     |
  24   |   |                     |
  25   '-->|    ...5c847 | 0 | 0 @--> Stream 0 messages
  26       |    ...5c847 | 0 | 1 @--> Stream 1 messages
  27       |    ...5c847 | 0 | 2 @--> Stream 2 messages
  28       +---------------------+
  29 ----
  30
  31 include::common-see-babeltrace2-intro.txt[]
  32
  33
  34 [[input]]
  35 === Input
  36
  37 A compcls:source.ctf.fs component opens a single _logical_ CTF trace. A
  38 logical CTF trace contains one or more _physical_ CTF traces. A physical
  39 CTF trace on the file system is a directory which contains:
  40
  41 * One metadata stream file named `metadata`.
  42 * One or more data stream files, that is, any file with a name that does
  43   not start with `.` and which is not `metadata`.
  44 * **Optional**: One https://lttng.org/[LTTng] index directory named
  45   `index`.
  46
  47 If the logical CTF trace to handle contains more than one physical CTF
  48 trace, then all the physical CTF traces must have a trace UUID and all
  49 UUIDs must be the same. Opening more than one physical CTF trace to
  50 constitute a single logical CTF trace is needed to support LTTng's
  51 tracing session rotation feature, for example (see man:lttng-rotate(1)
  52 starting from LTTng~2.11).
  53
  54 You specify which physical CTF traces to open and read with the
  55 param:inputs array parameter. Each entry in this array is the path to a
  56 physical CTF trace directory, that is, the directory directly containing
  57 the stream files.
  58
  59 A compcls:source.ctf.fs component does not recurse into directories to
  60 find CTF traces. However, the component class provides the
  61 `babeltrace.support-info` query object which indicates whether or not a
  62 given directory looks like a CTF trace directory (see
  63 <<support-info,```babeltrace.support-info`''>>).
  64
  65 The component creates one output port for each logical CTF data stream.
  66 More than one physical CTF data stream file can support a single logical
  67 CTF data stream (LTTng's trace file rotation and tracing session
  68 rotation can cause this).
  69
  70 If two or more data stream files contain the same packets, a
  71 compcls:source.ctf.fs message iterator reads each of  them only once so
  72 that it never emits duplicated messages. This feature makes it possible,
  73 for example, to open overlapping
  74 https://lttng.org/docs/#doc-taking-a-snapshot[LTTng snapshots] with a
  75 single compcls:source.ctf.fs component and silently discard the
  76 duplicated packets.
  77
  78
  79 === Trace quirks
  80
  81 Many tracers produce CTF traces. A compcls:source.ctf.fs component makes
  82 some effort to support as many CTF traces as possible, even those with
  83 malformed streams.
  84
  85 Generally:
  86
  87 * If the `timestamp_begin` or `timestamp_end` packet context field class
  88   exists, but it is not mapped to a clock class, and there's only one
  89   clock class at this point in the metadata stream, the component maps
  90   the field class to this unique clock class.
  91
  92 A compcls:source.ctf.fs component has special quirk handling for some
  93 https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces,
  94 depending on the tracer's version:
  95
  96 All LTTng versions::
  97 +
  98 --
  99 * The component sets the `monotonic` clock class's origin to the Unix
 100   epoch so that different LTTng traces are always correlatable.
 101 +
 102 This is the equivalent of setting the
 103 param:force-clock-class-origin-unix-epoch parameter to true.
 104
 105 * For a given data stream, for all the contiguous last packets of which
 106   the `timestamp_end` context field is 0, the message iterator uses the
 107   packet's last event record's time as the packet end message's time.
 108 +
 109 This is useful for the traces which man:lttng-crash(1) generates.
 110 --
 111
 112 LTTng-UST up to, but excluding, 2.11.0::
 113 LTTng-modules up to, but excluding, 2.9.13::
 114 LTTng-modules from 2.10.0 to 2.10.9::
 115 +
 116 --
 117 * For a given packet, the message iterator uses the packet's last
 118   event record's time as the packet end message's time, ignoring the
 119   packet context's `timestamp_end` field.
 120 --
 121
 122 barectf up to, but excluding, 2.3.1::
 123 +
 124 --
 125 * For a given packet, the message iterator uses the packet's first event
 126   record's time as the packet beginning message's time, ignoring the
 127   packet context's `timestamp_begin` field.
 128 --
 129
 130
 131 === CTF compliance
 132
 133 A compcls:source.ctf.fs component decodes traces as per
 134 https://diamon.org/ctf/v1.8.3/[CTF~1.8.3], except:
 135
 136 * It only supports integer field classes (TSDL `integer` block) with
 137   sizes from 1 to 64.
 138
 139 * It only supports 32-bit and 64-bit floating point number classes (TSDL
 140   `floating_point` block).
 141
 142 * It doesn't support §~4.1.6 (``GNU/C bitfields'').
 143
 144 * It doesn't support TSDL `callsite` blocks: the parser simply ignores
 145   them.
 146
 147 * It only supports a single clock class (TSDL `clock` block) reference
 148   per stream class (TSDL `stream` block).
 149
 150 * It doesn't support the checksum, compression, and encryption features
 151   of metadata stream packets.
 152
 153
 154 == INITIALIZATION PARAMETERS
 155
 156 param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
 157     Add 'NS' nanoseconds to the offset of all the clock classes that the
 158     component creates.
 159 +
 160 You can combine this parameter with the param:clock-class-offset-s
 161 parameter.
 162
 163 param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
 164     Add 'SEC' seconds to the offset of all the clock classes that the
 165     component creates.
 166 +
 167 You can combine this parameter with the param:clock-class-offset-ns
 168 parameter.
 169
 170 param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
 171     Force the origin of all clock classes that the component creates to
 172     have a Unix epoch origin, whatever the detected tracer.
 173
 174 param:inputs='DIRS' vtype:[array of strings]::
 175     Open and read the physical CTF traces located in 'DIRS'.
 176 +
 177 Each element of 'DIRS' is the path to a physical CTF trace directory
 178 containing the trace's stream files.
 179 +
 180 All the specified physical CTF traces must belong to the same logical
 181 CTF trace. See <<input,``Input''>> to learn more about logical and
 182 physical CTF traces.
 183
 184 param:trace-name='NAME' vtype:[optional string]::
 185     Set the name of the trace object that the component creates to
 186     'NAME'.
 187
 188
 189 == PORTS
 190
 191 ----
 192 +--------------------+
 193 |     src.ctf.fs     |
 194 |                    |
 195 |   ...5c847 | 0 | 1 @
 196 |                ... @
 197 +--------------------+
 198 ----
 199
 200
 201 === Output
 202
 203 A compcls:source.ctf.fs component creates one output port for each
 204 logical CTF data stream. See <<input,``Input''>> to learn more about
 205 logical and physical CTF data streams.
 206
 207 Each output port's name has one of the following forms:
 208
 209 [verse]
 210 __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
 211 __TRACE-ID__ | __STREAM-ID__
 212
 213 The component uses the second form when the stream class ID is not
 214 available.
 215
 216 __TRACE-ID__::
 217     Trace's UUID if available, otherwise trace's absolute directory
 218     path.
 219
 220 __STREAM-CLASS-ID__::
 221     Stream class ID.
 222
 223 __STREAM-ID__::
 224     Stream ID if available, otherwise stream's absolute file path.
 225
 226
 227 [[query-objs]]
 228 == QUERY OBJECTS
 229
 230 [[support-info]]
 231 === `babeltrace.support-info`
 232
 233 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
 234 about this query object.
 235
 236 For a directory input which is the path to a CTF trace directory,
 237 the result object contains:
 238
 239 nlqres:weight::
 240     0.75
 241
 242 nlqres:group::
 243     Trace's UUID if available, otherwise the entry does not exist.
 244
 245 You can leverage this query object's nlqres:group entry to assemble many
 246 physical CTF traces as a single logical CTF trace (see
 247 <<input,``Input''>> to learn more about logical and physical CTF
 248 traces). This is how the man:babeltrace2-convert(1) command makes it
 249 possible to specify as non-option arguments the paths to multiple
 250 physical CTF traces which belong to the same logical CTF trace and
 251 create a single compcls:source.ctf.fs component.
 252
 253
 254 === `babeltrace.trace-infos`
 255
 256 See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
 257 about this query object.
 258
 259
 260 === `metadata-info`
 261
 262 You can query the `metadata-info` object for a specific CTF trace to get
 263 its plain text metadata stream as well as whether or not it is
 264 packetized.
 265
 266 Parameters:
 267
 268 nlparam:path='PATH' vtype:[string]::
 269     Path to the physical CTF trace directory which contains the
 270     `metadata` file.
 271
 272 Result object (map):
 273
 274 qres:is-packetized vtype:[boolean]::
 275     True if the metadata stream file is packetized.
 276
 277 qres:text vtype:[string]::
 278     Plain text metadata stream.
 279
 280
 281 include::common-footer.txt[]
 282
 283
 284 == SEE ALSO
 285
 286 man:babeltrace2-intro(7),
 287 man:babeltrace2-plugin-ctf(7),
 288 man:lttng-crash(1)