babeltrace2-source.ctf.fs(7): add a "CTF compliance" description section

[babeltrace.git] / doc / man / babeltrace2-source.ctf.fs.7.txt

= babeltrace2-source.ctf.fs(7)
:manpagetype: component class
:revdate: 14 September 2019


== NAME

babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
component class


== DESCRIPTION

A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or
more https://diamon.org/ctf/[CTF]~1.8 streams on the file system
and emits corresponding messages.

----
CTF streams on
the file system
  |
  |   +---------------------+
  |   |      src.ctf.fs     |
  |   |                     |
  '-->|    ...5c847 | 0 | 0 @--> Stream 0 messages
      |    ...5c847 | 0 | 1 @--> Stream 1 messages
      |    ...5c847 | 0 | 2 @--> Stream 2 messages
      +---------------------+
----

include::common-see-babeltrace2-intro.txt[]


[[input]]
=== Input

A compcls:source.ctf.fs component opens a single _logical_ CTF trace. A
logical CTF trace contains one or more _physical_ CTF traces. A physical
CTF trace on the file system is a directory which contains:

* One metadata stream file named `metadata`.
* One or more data stream files, that is, any file with a name that does
  not start with `.` and which is not `metadata`.
* **Optional**: One https://lttng.org/[LTTng] index directory named
  `index`.

If the logical CTF trace to handle contains more than one physical CTF
trace, then all the physical CTF traces must have a trace UUID and all
UUIDs must be the same. Opening more than one physical CTF trace to
constitute a single logical CTF trace is needed to support LTTng's
tracing session rotation feature, for example (see man:lttng-rotate(1)
starting from LTTng~2.11).

You specify which physical CTF traces to open and read with the
param:inputs array parameter. Each entry in this array is the path to a
physical CTF trace directory, that is, the directory directly containing
the stream files.

A compcls:source.ctf.fs component does not recurse into directories to
find CTF traces. However, the component class provides the
`babeltrace.support-info` query object which indicates whether or not a
given directory looks like a CTF trace directory (see
<<support-info,```babeltrace.support-info`''>>).

The component creates one output port for each logical CTF data stream.
More than one physical CTF data stream file can support a single logical
CTF data stream (LTTng's trace file rotation and tracing session
rotation can cause this).

If two or more data stream files contain the same packets, a
compcls:source.ctf.fs message iterator reads each of  them only once so
that it never emits duplicated messages. This feature makes it possible,
for example, to open overlapping
https://lttng.org/docs/#doc-taking-a-snapshot[LTTng snapshots] with a
single compcls:source.ctf.fs component and silently discard the
duplicated packets.


=== Trace quirks

Many tracers produce CTF traces. A compcls:source.ctf.fs component makes
some effort to support as many CTF traces as possible, even those with
malformed streams.

Generally:

* If the `timestamp_begin` or `timestamp_end` packet context field class
  exists, but it is not mapped to a clock class, and there's only one
  clock class at this point in the metadata stream, the component maps
  the field class to this unique clock class.

A compcls:source.ctf.fs component has special quirk handling for some
https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces,
depending on the tracer's version:

All LTTng versions::
+
--
* The component sets the `monotonic` clock class's origin to the Unix
  epoch so that different LTTng traces are always correlatable.
+
This is the equivalent of setting the
param:force-clock-class-origin-unix-epoch parameter to true.

* For a given data stream, for all the contiguous last packets of which
  the `timestamp_end` context field is 0, the message iterator uses the
  packet's last event record's time as the packet end message's time.
+
This is useful for the traces which man:lttng-crash(1) generates.
--

LTTng-UST up to, but excluding, 2.11.0::
LTTng-modules up to, but excluding, 2.9.13::
LTTng-modules from 2.10.0 to 2.10.9::
+
--
* For a given packet, the message iterator uses the packet's last
  event record's time as the packet end message's time, ignoring the
  packet context's `timestamp_end` field.
--

barectf up to, but excluding, 2.3.1::
+
--
* For a given packet, the message iterator uses the packet's first event
  record's time as the packet beginning message's time, ignoring the
  packet context's `timestamp_begin` field.
--


=== CTF compliance

A compcls:source.ctf.fs component decodes traces as per
https://diamon.org/ctf/v1.8.3/[CTF~1.8.3], except:

* It only supports integer field classes (TSDL `integer` block) with
  sizes from 1 to 64.

* It only supports 32-bit and 64-bit floating point number classes (TSDL
  `floating_point` block).

* It doesn't support §~4.1.6 (``GNU/C bitfields'').

* It doesn't support TSDL `callsite` blocks: the parser simply ignores
  them.

* It only supports a single clock class (TSDL `clock` block) reference
  per stream class (TSDL `stream` block).

* It doesn't support the checksum, compression, and encryption features
  of metadata stream packets.


== INITIALIZATION PARAMETERS

param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
    Add 'NS' nanoseconds to the offset of all the clock classes that the
    component creates.
+
You can combine this parameter with the param:clock-class-offset-s
parameter.

param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
    Add 'SEC' seconds to the offset of all the clock classes that the
    component creates.
+
You can combine this parameter with the param:clock-class-offset-ns
parameter.

param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
    Force the origin of all clock classes that the component creates to
    have a Unix epoch origin, whatever the detected tracer.

param:inputs='DIRS' vtype:[array of strings]::
    Open and read the physical CTF traces located in 'DIRS'.
+
Each element of 'DIRS' is the path to a physical CTF trace directory
containing the trace's stream files.
+
All the specified physical CTF traces must belong to the same logical
CTF trace. See <<input,``Input''>> to learn more about logical and
physical CTF traces.

param:trace-name='NAME' vtype:[optional string]::
    Set the name of the trace object that the component creates to
    'NAME'.


== PORTS

----
+--------------------+
|     src.ctf.fs     |
|                    |
|   ...5c847 | 0 | 1 @
|                ... @
+--------------------+
----


=== Output

A compcls:source.ctf.fs component creates one output port for each
logical CTF data stream. See <<input,``Input''>> to learn more about
logical and physical CTF data streams.

Each output port's name has one of the following forms:

[verse]
__TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
__TRACE-ID__ | __STREAM-ID__

The component uses the second form when the stream class ID is not
available.

__TRACE-ID__::
    Trace's UUID if available, otherwise trace's absolute directory
    path.

__STREAM-CLASS-ID__::
    Stream class ID.

__STREAM-ID__::
    Stream ID if available, otherwise stream's absolute file path.


[[query-objs]]
== QUERY OBJECTS

[[support-info]]
=== `babeltrace.support-info`

See man:babeltrace2-query-babeltrace.support-info(7) to learn more
about this query object.

For a directory input which is the path to a CTF trace directory,
the result object contains:

nlqres:weight::
    0.75

nlqres:group::
    Trace's UUID if available, otherwise the entry does not exist.

You can leverage this query object's nlqres:group entry to assemble many
physical CTF traces as a single logical CTF trace (see
<<input,``Input''>> to learn more about logical and physical CTF
traces). This is how the man:babeltrace2-convert(1) command makes it
possible to specify as non-option arguments the paths to multiple
physical CTF traces which belong to the same logical CTF trace and
create a single compcls:source.ctf.fs component.


=== `babeltrace.trace-infos`

See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
about this query object.


=== `metadata-info`

You can query the `metadata-info` object for a specific CTF trace to get
its plain text metadata stream as well as whether or not it is
packetized.

Parameters:

nlparam:path='PATH' vtype:[string]::
    Path to the physical CTF trace directory which contains the
    `metadata` file.

Result object (map):

qres:is-packetized vtype:[boolean]::
    True if the metadata stream file is packetized.

qres:text vtype:[string]::
    Plain text metadata stream.


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2-plugin-ctf(7),
man:lttng-crash(1)