CTF Import Plugin

This plugin implements an importer for Common Trace Format (opens new window) data using babeltrace (opens new window).

The source code can be found in the plugin's repository (opens new window).

# Getting Started

  1. Configure a modality reflector (see the Configuration section below)
  2. Run the modality reflector import command with the path(s) to your CTF trace
modality-reflector import ctf /path/to/example-trace/metadata

CTF Trace Input

The importer accepts an array of input paths (either positionally at the CLI or in a configuration file) which constitute 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 index directory named index.

# Concepts

The following describes the default mapping between CTF (opens new window) concepts and Modality's concepts. See the configuration section for ways to change the default behavior.

  • CTF streams are represented as separate Modality timelines
  • CTF trace and stream properties are represented as Modality timeline attributes under the timeline.internal.ctf prefix
  • CTF event common, specific, and packet context fields are represented as Modality event attributes under the timeline.internal.ctf prefix
  • CTF event field attributes are at the root level

# Configuration

Configuration fields should be placed in a [plugins.ingest.importers.ctf.metadata] table in a modality-reflector configuration file. All fields are optional.

Configuration values may also be passed as command line options.

run-id
UUID
Use the provided UUID as the run ID instead of generating a random one.
trace-uuid
UUID
Provide a trace UUID for this data import. This UUID will override a UUID contained in the CTF metadata, if any.
This is useful for constructing deterministic trace UUIDs which form the timeline IDs.
log-level
string
Logging level for libbabeltrace itself, useful for diagnosing import issues. Must be one of trace, debug, info, warning, error, fatal, none. Defaults to none. See the libbabeltrace documentation (opens new window) for more info.
trace-name
string
Set the name of the trace object, overriding the data's trace name if present. Corresponds to the trace-name (opens new window) parameter in babeltrace.
clock-class-offset-ns
integer
Add clock-class-offset-ns nanoseconds to the offset of all the clock classes in the data. Can be combined with clock-class-offset-s. Corresponds to the clock-class-offset-ns (opens new window) parameter in babeltrace.
offset-s
integer
Add clock-class-offset-s seconds to the offset of all the clock classes in the data. Can be combined with clock-class-offset-ns. Corresponds to the clock-class-offset-s (opens new window) parameter in babeltrace.
force-clock-class-origin-unix-epoch
boolean
Force the origin of all clock classes in the data to have a Unix epoch origin. Corresponds to the force-clock-class-origin-unix-epoch (opens new window) parameter in babeltrace.
inputs
string[]
The metadata file paths of the CTF traces to import.

# Example Configuration

# config.toml for modality-reflector

[plugins.ingest.importers.ctf.metadata]
trace-name = 'drone'
log-level = 'error'
force-clock-class-origin-unix-epoch = true

← LTTng →