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

   1 = babeltrace2-source.ctf.fs(7)
   2 :manpagetype: component class
   3 :revdate: 1 September 2023
   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='VAL' vtype:[optional boolean]::
 171     If 'VAL' is true, then force the origin of all clock classes that
 172     the component creates to have a Unix epoch origin, whatever the
 173     detected tracer.
 174 +
 175 Default: false.
 176
 177 param:inputs='DIRS' vtype:[array of strings]::
 178     Open and read the physical CTF traces located in 'DIRS'.
 179 +
 180 Each element of 'DIRS' is the path to a physical CTF trace directory
 181 containing the trace's stream files.
 182 +
 183 All the specified physical CTF traces must belong to the same logical
 184 CTF trace. See <<input,``Input''>> to learn more about logical and
 185 physical CTF traces.
 186
 187 param:trace-name='NAME' vtype:[optional string]::
 188     Set the name of the trace object that the component creates to
 189     'NAME'.
 190
 191
 192 == PORTS
 193
 194 ----
 195 +--------------------+
 196 |     src.ctf.fs     |
 197 |                    |
 198 |   ...5c847 | 0 | 1 @
 199 |                ... @
 200 +--------------------+
 201 ----
 202
 203
 204 === Output
 205
 206 A compcls:source.ctf.fs component creates one output port for each
 207 logical CTF data stream. See <<input,``Input''>> to learn more about
 208 logical and physical CTF data streams.
 209
 210 Each output port's name has one of the following forms:
 211
 212 [verse]
 213 __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
 214 __TRACE-ID__ | __STREAM-ID__
 215
 216 The component uses the second form when the stream class ID is not
 217 available.
 218
 219 __TRACE-ID__::
 220     Trace's UUID if available, otherwise trace's absolute directory
 221     path.
 222
 223 __STREAM-CLASS-ID__::
 224     Stream class ID.
 225
 226 __STREAM-ID__::
 227     Stream ID if available, otherwise stream's absolute file path.
 228
 229
 230 [[query-objs]]
 231 == QUERY OBJECTS
 232
 233 [[support-info]]
 234 === `babeltrace.support-info`
 235
 236 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
 237 about this query object.
 238
 239 For a directory input which is the path to a CTF trace directory,
 240 the result object contains:
 241
 242 nlqres:weight::
 243     0.75
 244
 245 nlqres:group::
 246     Trace's UUID if available, otherwise the entry does not exist.
 247
 248 You can leverage this query object's nlqres:group entry to assemble many
 249 physical CTF traces as a single logical CTF trace (see
 250 <<input,``Input''>> to learn more about logical and physical CTF
 251 traces). This is how the man:babeltrace2-convert(1) command makes it
 252 possible to specify as non-option arguments the paths to multiple
 253 physical CTF traces which belong to the same logical CTF trace and
 254 create a single compcls:source.ctf.fs component.
 255
 256
 257 === `babeltrace.trace-infos`
 258
 259 See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
 260 about this query object.
 261
 262
 263 === `metadata-info`
 264
 265 You can query the `metadata-info` object for a specific CTF trace to get
 266 its plain text metadata stream as well as whether or not it is
 267 packetized.
 268
 269 Parameters:
 270
 271 nlparam:path='PATH' vtype:[string]::
 272     Path to the physical CTF trace directory which contains the
 273     `metadata` file.
 274
 275 Result object (map):
 276
 277 qres:is-packetized vtype:[boolean]::
 278     True if the metadata stream file is packetized.
 279
 280 qres:text vtype:[string]::
 281     Plain text metadata stream.
 282
 283
 284 include::common-footer.txt[]
 285
 286
 287 == SEE ALSO
 288
 289 man:babeltrace2-intro(7),
 290 man:babeltrace2-plugin-ctf(7),
 291 man:lttng-crash(1)