This document defines a standard layout of files for supporting a CTF 2 trace (see CTF2-SPEC-2.0) on a file system with file name and directory support.

The purpose of this standard is to formalize the interoperability of producers writing CTF 2 traces on a file system with consumers reading those traces (see Compliance).

The layout defined in this document is compatible with the layout of LTTng 2 traces on a file system, and with the layout supported by the Babeltrace and Trace Compass consumers.

Note
RFC 2119
The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document, when emphasized, are to be interpreted as described in RFC 2119.

Compliance

A CTF 2 producer is said to apply CTF2-FS-1.0 if it can produce a CTF 2 trace and store it on a file system as defined by this document.

A CTF 2 consumer is said to support CTF2-FS-1.0 if it can read the streams of a CTF 2 trace stored on a file system as defined by this document.

Trace

The producer must write the metadata stream and all the data stream packets of a trace to regular files in a dedicated directory. In the present text, this dedicated directory is called the trace directory.

The producer must not create regular files in the trace directory that do not contain the metadata stream or data stream packets, unless the names of those files start with a full stop character (., U+002e).

The producer may create subdirectories in the trace directory.

The consumer must ignore subdirectories in the trace directory.

There are no constraints on the name of the trace directory.

Metadata stream

The metadata stream must be serialized to a single regular file named metadata. The file’s content can be either raw, in which case it contains the complete UTF-8 JSON metadata array, or it can be a packetized metadata stream as described in CTF2-PMETA-1.0.

Data streams

If the data stream packet context field type of a given data stream class does not contain a field tagged with the data-stream-id tag, then each data stream instantiated by this data stream class must be written to exactly one regular file. There is no constraints on the name of this file, except that it must not be metadata.

If the data stream packet context field type of a given data stream class does not contain a field tagged with the data-stream-id tag, then the individual packets of the data streams referring to this data stream class can be written to one or more files within the trace directory, except to the files described in the previous paragraph. There is no constraints on the name of those files, except that they must not be metadata.

Within any data stream file, the packets of a given data stream must be written in the order they are produced.

Examples

Here are a few examples of trace directories following the standard layout defined by this document.

Example 1. Four data streams (no field tagged with data-stream-id)
my-trace/
┣━ metadata       (contains the raw metadata array)
┣━ streamA        (contains all the packets of data stream 0)
┣━ streamB        (contains all the packets of data stream 1)
┣━ streamC        (contains all the packets of data stream 2)
┗━ streamD        (contains all the packets of data stream 3)
Example 2. One data stream (field tagged with data-stream-id)
my-trace/
┣━ metadata       (contains the packetized metadata array)
┣━ streamA        (contains some packets of data stream 0)
┣━ streamB        (contains some packets of data stream 0)
┣━ streamC        (contains some packets of data stream 0)
┗━ streamD        (contains some packets of data stream 0)
Example 3. Four data streams (field tagged with data-stream-id)
my-trace/
┣━ metadata       (contains the raw metadata array)
┣━ streamA0       (contains some packets of data stream 0)
┣━ streamA1       (contains some packets of data stream 0)
┣━ streamB0       (contains some packets of data stream 1)
┣━ streamB1       (contains some packets of data stream 1)
┣━ streamB2       (contains some packets of data stream 1)
┣━ streamC0       (contains some packets of data stream 2)
┣━ streamC1       (contains some packets of data stream 2)
┣━ streamD0       (contains some packets of data stream 3)
┣━ streamD1       (contains some packets of data stream 3)
┣━ streamD2       (contains some packets of data stream 3)
┗━ streamD3       (contains some packets of data stream 3)
Example 4. Two data streams with a field tagged with data-stream-id, two data streams without a field tagged with data-stream-id
my-trace/
┣━ metadata       (contains the packetized metadata array)
┣━ streamAa       (contains some packets of data stream 0)
┣━ streamAb       (contains some packets of data stream 0)
┣━ streamBa       (contains some packets of data stream 1)
┣━ streamBb       (contains some packets of data stream 1)
┣━ streamC        (contains all the packets of data stream 2)
┗━ streamD        (contains all the packets of data stream 3)
Example 5. Two data streams with a field tagged with data-stream-id
my-trace/
┣━ metadata       (contains the raw metadata array)
┣━ streamW        (contains some packets of data stream 0 and of data stream 1)
┣━ streamX        (contains some packets of data stream 0)
┣━ streamY        (contains some packets of data stream 1)
┗━ streamZ        (contains some packets of data stream 0 and of data stream 1)