|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | DESCRIPTION | INITIALIZATION PARAMETERS | PORTS | QUERY OBJECTS | BUGS | RESOURCES | AUTHORS | COPYRIGHT | SEE ALSO | COLOPHON |
|
|
|
BABELTRACE2-SOURCE() BABELTRACE2-SOURCE()
babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
component class
A Babeltrace 2 source.ctf.fs message iterator reads one or more
CTF (see <https://diamon.org/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
+---------------------+
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:
• 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 LTTng (see <https://lttng.org/>) 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
<https://lttng.org/docs/#doc-taking-a-snapshot>) 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:
• 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 <https://lttng.org/>) and barectf (see
<https://lttng.org/>) 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 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 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 source.ctf.fs component decodes traces as per CTF 1.8.3 (see
<https://diamon.org/ctf/v1.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.
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=VAL [optional boolean]
If VAL is true, then force the origin of all clock classes
that the component creates to have a Unix epoch origin,
whatever the detected tracer.
Default: false.
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.
+--------------------+
| 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.
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.
If you encounter any issue or usability problem, please report it
on the Babeltrace bug tracker (see
<https://bugs.lttng.org/projects/babeltrace>).
The Babeltrace project shares some communication channels with
the LTTng project (see <https://lttng.org/>).
• Babeltrace website (see <https://babeltrace.org/>)
• Mailing list (see <https://lists.lttng.org>) for support and
development: lttng-dev@lists.lttng.org
• IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
irc.oftc.net
• Bug tracker (see
<https://bugs.lttng.org/projects/babeltrace>)
• Git repository (see
<https://git.efficios.com/?p=babeltrace.git>)
• GitHub project (see <https://github.com/efficios/babeltrace>)
• Continuous integration (see
<https://ci.lttng.org/view/Babeltrace/>)
• Code review (see
<https://review.lttng.org/q/project:babeltrace>)
The Babeltrace 2 project is the result of hard work by many
regular developers and occasional contributors.
The current project maintainer is Jérémie Galarneau
<mailto:jeremie.galarneau@efficios.com>.
This component class is part of the Babeltrace 2 project.
Babeltrace is distributed under the MIT license (see
<https://opensource.org/licenses/MIT>).
babeltrace2-intro(7), babeltrace2-plugin-ctf(7), lttng-crash(1)
This page is part of the babeltrace (trace read and write
libraries and a trace converter) project. Information about the
project can be found at ⟨http://www.efficios.com/babeltrace⟩. If
you have a bug report for this manual page, send it to
lttng-dev@lists.lttng.org. This page was obtained from the
project's upstream Git repository
⟨git://git.efficios.com/babeltrace.git⟩ on 2024-06-14. (At that
time, the date of the most recent commit that was found in the
repository was 2024-05-31.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
BABELTRACE2-SOURCE()
Pages that refer to this page: babeltrace2(1), babeltrace2-convert(1), babeltrace2-plugin-ctf(7)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|