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
  71 === Trace quirks
  72
  73 Many tracers produce CTF traces. A compcls:source.ctf.fs component makes
  74 some effort to support as many CTF traces as possible, even those with
  75 malformed streams.
  76
  77 Generally:
  78
  79 * If the `timestamp_begin` or `timestamp_end` packet context field class
  80   exists, but it is not mapped to a clock class, and there's only one
  81   clock class at this point in the metadata stream, the component maps
  82   the field class to this unique clock class.
  83
  84 A compcls:source.ctf.fs component has special quirk handling for some
  85 https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces,
  86 depending on the tracer's version:
  87
  88 All LTTng versions::
  89 +
  90 --
  91 * The component sets the `monotonic` clock class's origin to the Unix
  92   epoch so that different LTTng traces are always correlatable.
  93 +
  94 This is the equivalent of setting the
  95 param:force-clock-class-origin-unix-epoch parameter to true.
  96
  97 * For a given data stream, for all the contiguous last packets of which
  98   the `timestamp_end` context field is 0, the message iterator uses the
  99   packet's last event record's time as the packet end message's time.
 100 +
 101 This is useful for the traces which man:lttng-crash(1) generates.
 102 --
 103
 104 LTTng-UST up to, but excluding, 2.11.0::
 105 LTTng-modules up to, but excluding, 2.9.13::
 106 LTTng-modules from 2.10.0 to 2.10.9::
 107 +
 108 --
 109 * For a given packet, the message iterator uses the packet's last
 110   event record's time as the packet end message's time, ignoring the
 111   packet context's `timestamp_end` field.
 112 --
 113
 114 barectf up to, but excluding, 2.3.1::
 115 +
 116 --
 117 * For a given packet, the message iterator uses the packet's first event
 118   record's time as the packet beginning message's time, ignoring the
 119   packet context's `timestamp_begin` field.
 120 --
 121
 122
 123 == INITIALIZATION PARAMETERS
 124
 125 param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
 126     Add 'NS' nanoseconds to the offset of all the clock classes that the
 127     component creates.
 128 +
 129 You can combine this parameter with the param:clock-class-offset-s
 130 parameter.
 131
 132 param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
 133     Add 'SEC' seconds to the offset of all the clock classes that the
 134     component creates.
 135 +
 136 You can combine this parameter with the param:clock-class-offset-ns
 137 parameter.
 138
 139 param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
 140     Force the origin of all clock classes that the component creates to
 141     have a Unix epoch origin, whatever the detected tracer.
 142
 143 param:inputs='DIRS' vtype:[array of strings]::
 144     Open and read the physical CTF traces located in 'DIRS'.
 145 +
 146 Each element of 'DIRS' is the path to a physical CTF trace directory
 147 containing the trace's stream files.
 148 +
 149 All the specified physical CTF traces must belong to the same logical
 150 CTF trace. See <<input,``Input''>> to learn more about logical and
 151 physical CTF traces.
 152
 153 param:trace-name='NAME' vtype:[optional string]::
 154     Set the name of the trace object that the component creates to
 155     'NAME'.
 156
 157
 158 == PORTS
 159
 160 ----
 161 +--------------------+
 162 |     src.ctf.fs     |
 163 |                    |
 164 |   ...5c847 | 0 | 1 @
 165 |                ... @
 166 +--------------------+
 167 ----
 168
 169
 170 === Output
 171
 172 A compcls:source.ctf.fs component creates one output port for each
 173 logical CTF data stream. See <<input,``Input''>> to learn more about
 174 logical and physical CTF data streams.
 175
 176 Each output port's name has one of the following forms:
 177
 178 [verse]
 179 __TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
 180 __TRACE-ID__ | __STREAM-ID__
 181
 182 The component uses the second form when the stream class ID is not
 183 available.
 184
 185 __TRACE-ID__::
 186     Trace's UUID if available, otherwise trace's absolute directory
 187     path.
 188
 189 __STREAM-CLASS-ID__::
 190     Stream class ID.
 191
 192 __STREAM-ID__::
 193     Stream ID if available, otherwise stream's absolute file path.
 194
 195
 196 [[query-objs]]
 197 == QUERY OBJECTS
 198
 199 [[support-info]]
 200 === `babeltrace.support-info`
 201
 202 See man:babeltrace2-query-babeltrace.support-info(7) to learn more
 203 about this query object.
 204
 205 For a directory input which is the path to a CTF trace directory,
 206 the result object contains:
 207
 208 nlqres:weight::
 209     0.75
 210
 211 nlqres:group::
 212     Trace's UUID if available, otherwise the entry does not exist.
 213
 214 You can leverage this query object's nlqres:group entry to assemble many
 215 physical CTF traces as a single logical CTF trace (see
 216 <<input,``Input''>> to learn more about logical and physical CTF
 217 traces). This is how the man:babeltrace2-convert(1) command makes it
 218 possible to specify as non-option arguments the paths to multiple
 219 physical CTF traces which belong to the same logical CTF trace and
 220 create a single compcls:source.ctf.fs component.
 221
 222
 223 === `babeltrace.trace-infos`
 224
 225 See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
 226 about this query object.
 227
 228
 229 === `metadata-info`
 230
 231 You can query the `metadata-info` object for a specific CTF trace to get
 232 its plain text metadata stream as well as whether or not it is
 233 packetized.
 234
 235 Parameters:
 236
 237 nlparam:path='PATH' vtype:[string]::
 238     Path to the physical CTF trace directory which contains the
 239     `metadata` file.
 240
 241 Result object (map):
 242
 243 qres:is-packetized vtype:[boolean]::
 244     True if the metadata stream file is packetized.
 245
 246 qres:text vtype:[string]::
 247     Plain text metadata stream.
 248
 249
 250 include::common-footer.txt[]
 251
 252
 253 == SEE ALSO
 254
 255 man:babeltrace2-intro(7),
 256 man:babeltrace2-plugin-ctf(7),
 257 man:lttng-crash(1)