BABELTRACE2-SOURCE() BABELTRACE2-SOURCE()
NAME
babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
component class
DESCRIPTION
A Babeltrace 2 source.ctf.fs message iterator reads one or more CTF
(see ) 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
+---------------------+
See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
and its core concepts.
Input
A 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:
o One metadata stream file named metadata.
o One or more data stream files, that is, any file with a name that
does not start with . and which is not metadata.
o Optional: One LTTng (see ) 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 lttng-rotate(1)
starting from LTTng 2.11).
You specify which physical CTF traces to open and read with the 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 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 "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
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 LTTng snapshots (see
) with a single
source.ctf.fs component and silently discard the duplicated packets.
Trace quirks
Many tracers produce CTF traces. A source.ctf.fs component makes some
effort to support as many CTF traces as possible, even those with
malformed streams.
Generally:
o 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 source.ctf.fs component has special quirk handling for some LTTng
(see ) and barectf (see )
traces, depending on the tracer's version:
All LTTng versions
o 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 force-clock-class-origin-
unix-epoch parameter to true.
o 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 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
o 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
o 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.
INITIALIZATION PARAMETERS
clock-class-offset-ns=NS [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 clock-class-offset-s
parameter.
clock-class-offset-s=SEC [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 clock-class-offset-ns
parameter.
force-clock-class-origin-unix-epoch=yes [optional boolean]
Force the origin of all clock classes that the component creates to
have a Unix epoch origin, whatever the detected tracer.
inputs=DIRS [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" to learn more about logical and
physical CTF traces.
trace-name=NAME [optional string]
Set the name of the trace object that the component creates to
NAME.
PORTS
+--------------------+
| src.ctf.fs |
| |
| ...5c847 | 0 | 1 @
| ... @
+--------------------+
Output
A source.ctf.fs component creates one output port for each logical CTF
data stream. See "Input" to learn more about logical and physical CTF
data streams.
Each output port's name has one of the following forms:
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 OBJECTS
babeltrace.support-info
See 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:
weight
0.75
group
Trace's UUID if available, otherwise the entry does not exist.
You can leverage this query object's group entry to assemble many
physical CTF traces as a single logical CTF trace (see "Input" to learn
more about logical and physical CTF traces). This is how the
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 source.ctf.fs
component.
babeltrace.trace-infos
See 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:
path=PATH [string]
Path to the physical CTF trace directory which contains the
metadata file.
Result object (map):
is-packetized [boolean]
True if the metadata stream file is packetized.
text [string]
Plain text metadata stream.
BUGS
If you encounter any issue or usability problem, please report it on
the Babeltrace bug tracker (see
).
RESOURCES
The Babeltrace project shares some communication channels with the
LTTng project (see ).
o Babeltrace website (see )
o Mailing list (see ) for support and
development: lttng-dev@lists.lttng.org
o IRC channel (see ): #lttng on
irc.oftc.net
o Bug tracker (see )
o Git repository (see )
o GitHub project (see )
o Continuous integration (see
)
o Code review (see )
AUTHORS
The Babeltrace 2 project is the result of hard work by many regular
developers and occasional contributors.
The current project maintainer is Jeremie Galarneau
.
COPYRIGHT
This component class is part of the Babeltrace 2 project.
Babeltrace is distributed under the MIT license (see
).
SEE ALSO
babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-crash(1)
BABELTRACE2-SOURCE()