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 == INITIALIZATION PARAMETERS
 132
 133 param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
 134     Add 'NS' nanoseconds to the offset of all the clock classes that the
 135     component creates.
 136 +
 137 You can combine this parameter with the param:clock-class-offset-s
 138 parameter.
 139
 140 param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
 141     Add 'SEC' seconds to the offset of all the clock classes that the
 142     component creates.
 143 +
 144 You can combine this parameter with the param:clock-class-offset-ns
 145 parameter.
 146
 147 param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
 148     Force the origin of all clock classes that the component creates to
 149     have a Unix epoch origin, whatever the detected tracer.
 150
 151 param:inputs='DIRS' vtype:[array of strings]::
 152     Open and read the physical CTF traces located in 'DIRS'.
 153 +
 154 Each element of 'DIRS' is the path to a physical CTF trace directory
 155 containing the trace's stream files.
 156 +
 157 All the specified physical CTF traces must belong to the same logical
 158 CTF trace. See <<input,``Input''>> to learn more about logical and
 159 physical CTF traces.
 160
 161 param:trace-name='NAME' vtype:[optional string]::
 162     Set the name of the trace object that the component creates to
 163     'NAME'.
 164
 165
 166 == PORTS
 167
 168 ----
 169 +--------------------+
 170 |     src.ctf.fs     |
 171 |                    |
 172 |   ...5c847 | 0 | 1 @
 173 |                ... @
 174 +--------------------+
 175 ----
 176
 177
 178 === Output
 179
 180 A compcls:source.ctf.fs component creates one output port for each
 181 logical CTF data stream. See <<input,``Input''>> to learn more about
 182 logical and physical CTF data streams.
 183
 184 Each output port's name has one of the following forms:
 185
 186 [verse]
 187 __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
 188 __TRACE-ID__ | __STREAM-ID__
 189
 190 The component uses the second form when the stream class ID is not
 191 available.
 192
 193 __TRACE-ID__::
 194     Trace's UUID if available, otherwise trace's absolute directory
 195     path.
 196
 197 __STREAM-CLASS-ID__::
 198     Stream class ID.
 199
 200 __STREAM-ID__::
 201     Stream ID if available, otherwise stream's absolute file path.
 202
 203
 204 [[query-objs]]
 205 == QUERY OBJECTS
 206
 207 [[support-info]]
 208 === `babeltrace.support-info`
 209
 210 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
 211 about this query object.
 212
 213 For a directory input which is the path to a CTF trace directory,
 214 the result object contains:
 215
 216 nlqres:weight::
 217     0.75
 218
 219 nlqres:group::
 220     Trace's UUID if available, otherwise the entry does not exist.
 221
 222 You can leverage this query object's nlqres:group entry to assemble many
 223 physical CTF traces as a single logical CTF trace (see
 224 <<input,``Input''>> to learn more about logical and physical CTF
 225 traces). This is how the man:babeltrace2-convert(1) command makes it
 226 possible to specify as non-option arguments the paths to multiple
 227 physical CTF traces which belong to the same logical CTF trace and
 228 create a single compcls:source.ctf.fs component.
 229
 230
 231 === `babeltrace.trace-infos`
 232
 233 See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
 234 about this query object.
 235
 236
 237 === `metadata-info`
 238
 239 You can query the `metadata-info` object for a specific CTF trace to get
 240 its plain text metadata stream as well as whether or not it is
 241 packetized.
 242
 243 Parameters:
 244
 245 nlparam:path='PATH' vtype:[string]::
 246     Path to the physical CTF trace directory which contains the
 247     `metadata` file.
 248
 249 Result object (map):
 250
 251 qres:is-packetized vtype:[boolean]::
 252     True if the metadata stream file is packetized.
 253
 254 qres:text vtype:[string]::
 255     Plain text metadata stream.
 256
 257
 258 include::common-footer.txt[]
 259
 260
 261 == SEE ALSO
 262
 263 man:babeltrace2-intro(7),
 264 man:babeltrace2-plugin-ctf(7),
 265 man:lttng-crash(1)