NAMEDESCRIPTION
Trace IR to CTF 1.8 translationTrace IR to CTF 2 translationInput message constraintsAlignment and byte orderOutput path
INITIALIZATION PARAMETERSPORTS
Input
SEE ALSO

babeltrace2-sink.ctf.fs(7)

NAME

babeltrace2-sink.ctf.fs — Babeltrace 2: File system CTF sink component class

DESCRIPTION

A Babeltrace 2 sink.ctf.fs component writes the messages it consumes to one or more CTF 1.8 or CTF 2 traces on the file system.

            +-------------+
            | sink.ctf.fs |
            |             +--> CTF trace(s) on
Messages -->@ in          |    the file system
            +-------------+

See babeltrace2-intro(7) to learn more about the Babeltrace 2 project and its core concepts.

The ctf-version parameter controls the CTF version of the resulting traces.

As of this version, a sink.ctf.fs component may only write:

CTF 1.8 traces

When working under version 0 of the Message Interchange Protocol (MIP).

CTF 2 traces

When working under version 1 of the MIP.

Therefore, the "get supported MIP versions" method of a sink.ctf.fs component class reports to support only MIP 0 with the ctf-version parameter set to 1 and only MIP 1 with ctf-version set to 2.

A sink.ctf.fs component doesn’t merge traces: it writes the messages of different input traces to different output traces.

Trace IR to CTF 1.8 translation

A sink.ctf.fs component makes a best effort to write CTF 1.8 traces that are semantically equivalent to the input traces. As of this version, with the ctf-version parameter set to 1, the following field class translations can occur:

In all the cases above, the component adds a comment in the metadata stream, above the field class, to indicate that a special translation occurred.

The component doesn’t translate any user attribute: a CTF 1.8 metadata stream has no way to represent them.

Trace IR to CTF 2 translation

As of this version, with the ctf-version parameter set to 2:

Input message constraints

Because of limitations in CTF regarding how discarded events and packets are encoded:

The messages which a source.ctf.fs component creates satisfy all the requirements above.

If a discarded events or packets message has no events/packets count, then the sink.ctf.fs component adds 1 to the counter of the corresponding CTF stream.

Alignment and byte order

A sink.ctf.fs component always aligns data fields as such:

Fixed-length bit array fields with a size which isn’t a multiple of 8

1-bit.

All other scalar fields (fixed-length bit array, null-terminated string, BLOB)

8-bit.

The component writes fields using the native byte order of the machine. As of this version, there’s no way to force a custom byte order.

Output path

The path of a CTF trace is the directory which directly contains the metadata and data stream files.

The current strategy to build a path in which to write the streams of a given input trace is, in this order:

  1. If the assume-single-trace parameter is true, then the output trace path to use for the single input trace is the directory specified by the path parameter.

  2. If the component recognizes the input trace as an LTTng (2.11 or greater) trace, then it checks specific trace environment values to build a trace path relative to the directory specified by the path parameter:

    Linux kernel domain 
    HOST/SNAME-STIME/kernel
    User space domain, per-UID buffering 
    HOST/SNAME-STIME/ust/uid/UID/ARCHW-bit
    User space domain, per-PID buffering 
    HOST/SNAME-STIME/ust/pid/PNAME-PID-PTIME

    With:

    HOST

    Target hostname.

    SNAME

    Tracing session name.

    STIME

    Tracing session creation date/time.

    UID

    User ID.

    ARCHW

    Architecture width (32 or 64).

    PNAME

    Process name.

    PID

    Process ID.

    PTIME

    Process date/time.

  3. If the input trace has a name, then the component sanitizes this name and uses it as a relative path to the directory specified by the path parameter.

    The trace name sanitization operation:

    • Replaces . subdirectories with _.

    • Replaces .. subdirectories with __.

    • Removes any trailing / character.

  4. The component uses the subdirectory trace relative to the directory specified by the path parameter.

In all the cases above, if the effective output trace path already exists on the file system, then the component appends a numeric suffix to the name of the last subdirectory. The suffix starts at 0 and increments until the path doesn’t exist.

INITIALIZATION PARAMETERS

assume-single-trace=VAL [optional boolean]

If VAL is true, then assume that the component only receives messages related to a single input trace.

This parameter affects how the component builds the output trace path (see Output path).

Default: false.

ctf-version=VERSION [optional string]

Write traces following version VERSION of CTF, where VERSION is one of:

1
1.8

CTF 1.8.

2
2.0

CTF 2.

Default: 2.

ignore-discarded-events=VAL [optional boolean]

If VAL is true, then ignore discarded events messages.

Default: false.

ignore-discarded-packets=VAL [optional boolean]

If VAL is true, then ignore discarded packets messages.

Default: false.

path=PATH [string]

Base output path.

See Output path to learn how the component uses this parameter to build the output path for a given input trace.

quiet=VAL [optional boolean]

If VAL is true, then don’t write anything to the standard output.

Default: false.

PORTS

+-------------+
| sink.ctf.fs |
|             |
@ in          |
+-------------+

Input

in

Single input port.

SEE ALSO

babeltrace2-intro(7), babeltrace2-plugin-ctf(7)