Percepio TraceRecorder Plugins

Modality includes a set of plugins to receive Percepio TraceRecorder (opens new window) data from RTOS systems. These plugins support both of TraceRecorder's protocols, snapshot and streaming. Data from either protocol can be imported from a file, and streaming data can be collected over either TCP or ITM. There are currently 3 plugins which support these various scenarios:

trace-recorder: importer for either snapshot protocol or streaming protocol data in files.
trace-recorder-rtt: collector for streaming protocol data collected live over RTT.
trace-recorder-itm: collector for streaming protocol data collected live over ITM.
trace-recorder-tcp: collector for streaming protocol data collected live over TCP.

The plugins currently support FreeRTOS. Support for other systems is coming soon.

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

# Getting Started

Add TraceRecorder (opens new window) source files and configuration into your RTOS project (e.g. using Using FreeRTOS-Plus-Trace (opens new window))
Use the importer to import a memory dump or streaming data file, or use one of the available streaming collectors to collect data from a running system

modality-reflector import trace-recorder /path/to/trace.bin

modality-reflector run --collector trace-recorder-tcp --config <your-config-file>

For more information about using TraceRecorder to collect data you can refer to the github repository (opens new window) or the Percepio Tracealyzer documentation (opens new window).

# Concepts

The following describes the default mapping between TraceRecorder's concepts and Modality's concepts. See the configuration section for ways to change the default behavior.

Task and ISR objects are represented as separate Modality timelines
The initial startup task ('(startup)') is also represented as a separate Modality timeline
Streaming header and snapshot fields are represented as Modality timeline attributes under the timeline.internal.trace_recorder prefix
Object properties and event context fields are represented as Modality event attributes under the event.internal.trace_recorder prefix
Event field attributes are at the root level (e.g. event.channel for USER_EVENT channel field)
Task and ISR context switches will be synthesized into Modality timeline interactions

# Deviant Events

When the deviant-event-id-base configuration is provided, Deviant related information will be parsed and mapped from TraceRecorder custom events to their reserved Modality event names and attributes.

Expected event ID offset and data:

Event: modality.mutator.announced
- Event ID offset: 0
- data: ['mutator_id']
  - mutator_id is a 16-byte UUID array
Event: modality.mutator.retired
- Event ID offset: 1
- data: ['mutator_id']
  - mutator_id is a 16-byte UUID array
Event: modality.mutation.command_communicated
- Event ID offset: 2
- data: ['mutator_id', 'mutation_id', 'mutation_success']
  - mutator_id is a 16-byte UUID array
  - mutation_id is a 16-byte UUID array
  - mutation_success is a 4-byte (uint32_t) boolean
Event: modality.mutation.clear_communicated
- Event ID offset: 3
- data: ['mutator_id', 'mutation_id', 'mutation_success']
  - mutator_id is a 16-byte UUID array
  - mutation_id is a 16-byte UUID array
  - mutation_success is a 4-byte (uint32_t) boolean
Event: modality.mutation.triggered
- Event ID offset: 4
- data: ['mutator_id', 'mutation_id', 'mutation_success']
  - mutator_id is a 16-byte UUID array
  - mutation_id is a 16-byte UUID array
  - mutation_success is a 4-byte (uint32_t) boolean
Event: modality.mutation.injected
- Event ID offset: 5
- data: ['mutator_id', 'mutation_id', 'mutation_success']
  - mutator_id is a 16-byte UUID array
  - mutation_id is a 16-byte UUID array
  - mutation_success is a 4-byte (uint32_t) boolean

See the Deviant documentation (opens new window) for more information on Mutators and Mutations.

# Configuration

Configuration fields should be placed in a [plugins.ingest.importers.trace-recorder.metadata], [plugins.ingest.collectors.trace-recorder-tcp.metadata], or [plugins.ingest.collectors.trace-recorder-itm.metadata] table in a modality-reflector configuration file. All fields are optional.

# Common Fields

These fields are the same for each of the plugins.

`run-id` `UUID`
Use the provided UUID as the run ID instead of generating a random one.

`time-domain` `UUID`
Use the provide a UUID as the time domain ID instead of generating a random one.

`startup-task-name` `string`
Use the provided initial startup task name instead of the default (`(startup)`).

`single-task-timeline` `boolean`
Use a single timeline for all tasks instead of a timeline per task. ISRs can still be represented with their own timelines or not.

`disable-task-interactions` `boolean`
Don't synthesize interactions between tasks and ISRs when a context switch occurs.

`deviant-event-id-base` `integer`
Parse Deviant custom events using the provided base event ID.

`ignored-object-classes` `string[]`
Array of object classes to ignore processing during ingest (e.g. `[queue, semaphore]`)

`user-event-channel` `string`
Instead of `USER_EVENT @ <task-name>`, use the user event channel as the event name (`<channel> @ <task-name>`).

`user-event-format-string` `string`
Instead of `USER_EVENT @ <task-name>`, use the user event format string as the event name (`<format-string> @ <task-name>`).

`[[user-event-channel-name]]` `table[]`
Use a custom event name whenever a user event with a matching channel is processed.

`user-event-channel-name.name` `string`
The input channel name to match on.

`user-event-channel-name.event-name` `string`
The Modality event name to use.

`[[user-event-formatted-string-name]]` `table[]`
Use a custom event name whenever a user event with a matching formatted string is processed.

`user-event-formatted-string-name.formatted-string` `string`
The input formatted string to match on.

`user-event-formatted-string-name.event-name` `string`
The Modality event name to use.

`[[user-event-fmt-arg-attr-keys]]` `table[]`
Use custom attribute keys instead of the default `argN` keys for user events matching the given channel and format string.

`user-event-fmt-arg-attr-keys.channel` `string`
The input channel name to match on.

`user-event-fmt-arg-attr-keys.format-string` `string`
The input format string to match on.

`user-event-fmt-arg-attr-keys.attribute-keys` `string[]`
Array of Modality event attribute keys to use.

# Importer Fields

These fields are specific to the importer plugin.

`protocol` `string`
The protocol to use. Either `streaming`, `snapshot`, or `auto`. The default is `auto`.

`file` `string`
Path to the file to import.

# Example Configuration

# config.toml for modality-reflector

[plugins.ingest.importers.trace-recorder.metadata]
startup-task-name = 'init'
user-event-channel = true
protocol = 'auto'

    [[plugins.ingest.importers.trace-recorder.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'comms-tx'
    format-string = '%u %u %d'
    attribute-keys = ['type', 'seqnum', 'adc']

    [[plugins.ingest.importers.trace-recorder.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'adc'
    format-string = '%d'
    attribute-keys = ['measurement']

# TCP Collector Fields

These fields are specific to the streaming TCP collector plugin.

`disable-control-plane` `boolean`
Disable sending control plane commands to the target.
By default, `CMD_SET_ACTIVE` is sent on startup and shutdown to start and stop tracing on the target.

`restart` `boolean`
Send a stop command before a start command to reset tracing on the target.

`connect-timeout` `string`
Specify a connection timeout. Accepts durations like "10ms" or "1minute 2seconds 22ms".

`file` `string`
Path to the file to import.

`remote` `string`
The remote address and port to connect to. The default is `127.0.0.1:8888`.

# Example Configuration

# config.toml for modality-reflector

[plugins.ingest.collectors.trace-recorder-tcp.metadata]
startup-task-name = 'init'
user-event-channel = true
remote = "192.0.2.80:8888"
connect-timeout = "60s"

    [[plugins.ingest.collectors.trace-recorder-tcp.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'comms-tx'
    format-string = '%u %u %d'
    attribute-keys = ['type', 'seqnum', 'adc']

    [[plugins.ingest.collectors.trace-recorder-tcp.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'adc'
    format-string = '%d'
    attribute-keys = ['measurement']

# ITM Collector Fields

These fields are specific to the streaming ITM collector plugin.

`disable-control-plane` `boolean`
Disable sending control plane commands to the target.
By default, `CMD_SET_ACTIVE` is sent on startup and shutdown to start and stop tracing on the target.

`restart` `boolean`
Send a stop command before a start command to reset tracing on the target.

`elf-file` `string`
Extract the location in memory of the ITM streaming port variables from the debug symbols from an ELF file (`tz_host_command_bytes_to_read` and `tz_host_command_data`).
These are used to start and stop tracing by writing control plane commands from the probe.

`command-data-addr` `integer`
Use the provided memory address for the ITM streaming port variable `tz_host_command_data`.
These are used to start and stop tracing by writing control plane commands from the probe.

`command-len-addr` `integer`
Use the provided memory address for the ITM streaming port variable `tz_host_command_bytes_to_read`.
These are used to start and stop tracing by writing control plane commands from the probe.

`stimulus-port` `integer`
The ITM stimulus port used for trace recorder data.The default value is 1.

`probe-selector` `string`
Select a specific probe instead of opening the first available one.

`chip` `string`
The target chip to attach to (e.g. `STM32F407VE`).

`protocol` `string`
Protocol used to connect to chip. Possible options: [`swd`, `jtag`].
The default value is `swd`.

`speed` `integer`
The protocol speed in kHz. The default value is 4000.

`core` `integer`
The selected core to target. The default value is 0.

`clk` `integer`
The speed of the clock feeding the TPIU/SWO module in Hz.

`baud` `integer`
The desired baud rate of the SWO output.

`reset` `boolean`
Reset the target on startup.

`chip-description-path` `string`
Provides custom target descriptions based on CMSIS Pack files.
See the probe-rs target extraction (opens new window) section for more information.

# Example Configuration

# config.toml for modality-reflector

[plugins.ingest.collectors.trace-recorder-itm.metadata]
startup-task-name = 'init'
user-event-channel = true
elf-file = '/path/to/elf.elf'
stimulus-port = 3
probe-selector = '234:234'
chip = 'stm32'
protocol = 'Jtag'
speed = 1234
core = 1
clk = 222
baud = 4444
reset = true

    [[plugins.ingest.collectors.trace-recorder-itm.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'comms-tx'
    format-string = '%u %u %d'
    attribute-keys = ['type', 'seqnum', 'adc']

    [[plugins.ingest.collectors.trace-recorder-itm.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'adc'
    format-string = '%d'
    attribute-keys = ['measurement']

# RTT Collector Fields

These fields are specific to the streaming RTT collector plugin.

`attach-timeout` `string`
Specify a target attach retry timeout.
When provided, the plugin will continually attempt to attach and search for a valid RTT control block anywhere in the target RAM.
Accepts durations like "10ms" or "1minute 2seconds 22ms".
See the RTT timing section (opens new window) for more information.

`disable-control-plane` `boolean`
Disable sending control plane commands to the target.
By default, `CMD_SET_ACTIVE` is sent on startup and shutdown to start and stop tracing on the target.

`restart` `boolean`
Send a stop command before a start command to reset tracing on the target.

`control-block-address` `integer`
Use the provided RTT control block address instead of scanning the target memory for it.

`up-channel` `integer`
The RTT up (target to host) channel number to poll on. The default value is 1.

`down-channel` `integer`
The RTT down (host to target) channel number to send start/stop commands on. The default value is 1.

`probe-selector` `string`
Select a specific probe instead of opening the first available one.

`chip` `string`
The target chip to attach to (e.g. `STM32F407VE`).

`protocol` `string`
Protocol used to connect to chip. Possible options: [`swd`, `jtag`].
The default value is `swd`.

`speed` `integer`
The protocol speed in kHz. The default value is 4000.

`core` `integer`
The selected core to target. The default value is 0.

`reset` `boolean`
Reset the target on startup.

`chip-description-path` `string`
Provides custom target descriptions based on CMSIS Pack files.
See the probe-rs target extraction (opens new window) section for more information.

# Example Configuration

# config.toml for modality-reflector

[plugins.ingest.collectors.trace-recorder-rtt.metadata]
startup-task-name = 'init'
user-event-channel = true
attach-timeout = "10s"
up-channel = 1
down-channel = 1
chip = 'S32K344'
chip-description-path = "/tmp/S32K_Series.yaml"
protocol = 'swd'
core = 0
reset = true

    [[plugins.ingest.collectors.trace-recorder-rtt.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'comms-tx'
    format-string = '%u %u %d'
    attribute-keys = ['type', 'seqnum', 'adc']

    [[plugins.ingest.collectors.trace-recorder-rtt.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'adc'
    format-string = '%d'
    attribute-keys = ['measurement']

← LTTng OpenTelemetry →